new fortune
[feisty_meow.git] / nucleus / library / basis / utf_conversion.h
1 #ifndef UTF_CONVERSION_GROUP
2 #define UTF_CONVERSION_GROUP
3
4 /*****************************************************************************\
5 *                                                                             *
6 *  Name   : utf_conversion                                                    *
7 *  Author : Unicode, Inc. (C conversion functions)                            *
8 *  Author : Chris Koeritz (C++ conversion classes)                            *
9 *                                                                             *
10 *******************************************************************************
11 * Copyright (c) 2006-$now By Author.  This program is free software; you can  *
12 * redistribute it and/or modify it under the terms of the GNU General Public  *
13 * License as published by the Free Software Foundation; either version 2 of   *
14 * the License or (at your option) any later version.  This is online at:      *
15 *     http://www.fsf.org/copyleft/gpl.html                                    *
16 * Please send any updates to: fred@gruntose.com                               *
17 \*****************************************************************************/
18
19 #include "astring.h"
20 #include "definitions.h"
21
22 //! @file utf_conversion.h Support for unicode builds.
23 /*! @file utf_conversion.h
24   This file provides conversions between UTF-8 and UTF-16 that are essential
25   to having the code compile in either the UNICODE or regular ANSI character
26   builds of win32-based code.
27 */
28
29 // original copyright notice still applies to low-level conversion code:
30 /*
31  * Copyright 2001-$now Unicode, Inc.
32  * 
33  * Disclaimer
34  * 
35  * This source code is provided as is by Unicode, Inc. No claims are
36  * made as to fitness for any particular purpose. No warranties of any
37  * kind are expressed or implied. The recipient agrees to determine
38  * applicability of information provided. If this file has been
39  * purchased on magnetic or optical media from Unicode, Inc., the
40  * sole remedy for any claim will be exchange of defective media
41  * within 90 days of receipt.
42  * 
43  * Limitations on Rights to Redistribute This Code
44  * 
45  * Unicode, Inc. hereby grants the right to freely use the information
46  * supplied in this file in the creation of products supporting the
47  * Unicode Standard, and to make copies of this file in any form
48  * for internal or external distribution as long as this notice
49  * remains attached.
50  */
51
52 /* ---------------------------------------------------------------------
53
54     Conversions between UTF32, UTF-16, and UTF-8.  Header file.
55
56     Several funtions are included here, forming a complete set of
57     conversions between the three formats.  UTF-7 is not included
58     here, but is handled in a separate source file.
59
60     Each of these routines takes pointers to input buffers and output
61     buffers.  The input buffers are const.
62
63     Each routine converts the text between *sourceStart and sourceEnd,
64     putting the result into the buffer between *targetStart and
65     targetEnd. Note: the end pointers are *after* the last item: e.g. 
66     *(sourceEnd - 1) is the last item.
67
68     The return result indicates whether the conversion was successful,
69     and if not, whether the problem was in the source or target buffers.
70     (Only the first encountered problem is indicated.)
71
72     After the conversion, *sourceStart and *targetStart are both
73     updated to point to the end of last text successfully converted in
74     the respective buffers.
75
76     Input parameters:
77         sourceStart - pointer to a pointer to the source buffer.
78                 The contents of this are modified on return so that
79                 it points at the next thing to be converted.
80         targetStart - similarly, pointer to pointer to the target buffer.
81         sourceEnd, targetEnd - respectively pointers to the ends of the
82                 two buffers, for overflow checking only.
83
84     These conversion functions take a ConversionFlags argument. When this
85     flag is set to strict, both irregular sequences and isolated surrogates
86     will cause an error.  When the flag is set to lenient, both irregular
87     sequences and isolated surrogates are converted.
88
89     Whether the flag is strict or lenient, all illegal sequences will cause
90     an error return. This includes sequences such as: <F4 90 80 80>, <C0 80>,
91     or <A0> in UTF-8, and values above 0x10FFFF in UTF-32. Conformant code
92     must check for illegal sequences.
93
94     When the flag is set to lenient, characters over 0x10FFFF are converted
95     to the replacement character; otherwise (when the flag is set to strict)
96     they constitute an error.
97
98     Output parameters:
99         The value "sourceIllegal" is returned from some routines if the input
100         sequence is malformed.  When "sourceIllegal" is returned, the source
101         value will point to the illegal value that caused the problem. E.g.,
102         in UTF-8 when a sequence is malformed, it points to the start of the
103         malformed sequence.  
104
105     Author: Mark E. Davis, 1994.
106     Rev History: Rick McGowan, fixes & updates May 2001.
107         Fixes & updates, Sept 2001.
108
109 ------------------------------------------------------------------------ */
110
111 namespace basis {
112
113 /* ---------------------------------------------------------------------
114     The following 4 definitions are compiler-specific.
115     The C standard does not guarantee that wchar_t has at least
116     16 bits, so wchar_t is no less portable than unsigned short!
117     All should be unsigned values to avoid sign extension during
118     bit mask & shift operations.
119 ------------------------------------------------------------------------ */
120 typedef unsigned long UTF32;  /* at least 32 bits */
121 typedef unsigned short UTF16;  /* at least 16 bits */
122 typedef unsigned char UTF8;  /* typically 8 bits */
123 typedef unsigned char Booleano;  /* 0 or 1 */
124
125 //hmmm: this is some really gross stuff below, just because it's got
126 //      so much of its guts hanging out.  make a class out of the lower-
127 //      level conversion stuff and hide all the details.
128
129 /* Some fundamental constants */
130 #define UNI_REPLACEMENT_CHAR (UTF32)0x0000FFFD
131 #define UNI_MAX_BMP (UTF32)0x0000FFFF
132 #define UNI_MAX_UTF16 (UTF32)0x0010FFFF
133 #define UNI_MAX_UTF32 (UTF32)0x7FFFFFFF
134 #define UNI_MAX_LEGAL_UTF32 (UTF32)0x0010FFFF
135
136 typedef enum {
137   conversionOK,     /* conversion successful */
138   sourceExhausted,  /* partial character in source, but hit end */
139   targetExhausted,  /* insuff. room in target for conversion */
140   sourceIllegal  /* source sequence is illegal/malformed */
141 } ConversionResult;
142
143 typedef enum {
144   strictConversion = 0,
145   lenientConversion
146 } ConversionFlags;
147
148 #ifdef __cplusplus
149 extern "C" {
150 #endif
151
152 ConversionResult ConvertUTF8toUTF16 (const UTF8** sourceStart,
153     const UTF8* sourceEnd, UTF16** targetStart, UTF16* targetEnd,
154     ConversionFlags flags);
155
156 ConversionResult ConvertUTF16toUTF8 (const UTF16** sourceStart,
157     const UTF16* sourceEnd, UTF8** targetStart, UTF8* targetEnd,
158     ConversionFlags flags);
159
160 ConversionResult ConvertUTF8toUTF32 (const UTF8** sourceStart,
161     const UTF8* sourceEnd, UTF32** targetStart, UTF32* targetEnd,
162     ConversionFlags flags);
163
164 ConversionResult ConvertUTF32toUTF8 (const UTF32** sourceStart,
165     const UTF32* sourceEnd, UTF8** targetStart, UTF8* targetEnd,
166     ConversionFlags flags);
167
168 ConversionResult ConvertUTF16toUTF32 (const UTF16** sourceStart,
169     const UTF16* sourceEnd, UTF32** targetStart, UTF32* targetEnd,
170     ConversionFlags flags);
171
172 ConversionResult ConvertUTF32toUTF16 (const UTF32** sourceStart,
173     const UTF32* sourceEnd, UTF16** targetStart, UTF16* targetEnd,
174     ConversionFlags flags);
175
176 Booleano isLegalUTF8Sequence(const UTF8 *source, const UTF8 *sourceEnd);
177
178 #ifdef __cplusplus
179 } //extern
180 #endif //cplusplus
181
182 //////////////
183
184 #ifdef __cplusplus
185
186 // The following types and macros help to make it irrelevant what kind of
187 // win32 build is being done.  They will adapt as needed to provide the
188 // types used in system calls.  They are rendered harmless for other operating
189 // systems or for non-Unicode builds; this is especially useful for POSIX
190 // compliant functions that required Unicode in win32 but not in Unix systems.
191
192 #if defined(UNICODE)
193 #error should not be in here right now --cak
194 ///holding to test wx && defined(__WIN32__)
195   //! to_unicode_temp() converts to UTF-16 as needed for win32 system calls.
196   /*! this conversion is only appropriate to use within expressions.  it does
197     not create a permanent object and will go out of scope when the full
198     expression does. */
199   #define to_unicode_temp(s) transcode_to_utf16(s)
200   //! the from_unicode_temp() macro converts the win32 unicode string to UTF-8.
201   /*! this has the same contraint as to_unicode_temp; it does not persist
202     beyond the lifetime of the expression containing it. */
203   #define from_unicode_temp(s) transcode_to_utf8(s)
204   //! to_unicode_persist creates a UTF-16 object with block scope.
205   /*! the object with "name" that is created by this macro will exist on
206     the stack until the block containing it is closed.  this is needed when
207     storing unicode strings into windows structure, for example. */
208   #define to_unicode_persist(name, s) transcode_to_utf16 name(s)
209   //! from_unicode_persist creates a UTF-8 object with block scope.
210   /*! similar to to_unicode_persist, this is used for longer-lived objects. */
211   #define from_unicode_persist(name, s) transcode_to_utf8 name(s)
212 #else
213   // these versions of the macros simply defang any conversions.
214   #define to_unicode_temp(s) null_transcoder(s, false)
215   #define from_unicode_temp(s) null_transcoder(s, false)
216   #define to_unicode_persist(name, s) null_transcoder name(s, true)
217   #define from_unicode_persist(name, s) null_transcoder name(s, true) 
218 #endif
219
220 #ifdef _MSC_VER
221   //! sends UTF-8 information to the diagnostic view in the IDE.
222   #define TRACE_PRINT(s) TRACE(_T("%s"), to_unicode_temp(s))
223 #endif
224
225 //////////////
226
227 // The next two classes support converting a UTF-8 string into a UTF-16
228 // string and vice-versa.  They hold onto the converted string and provide
229 // operators that return it.
230
231 //! handles the conversion of UTF-8 format strings into UTF-16.
232
233 class transcode_to_utf16 : public virtual root_object
234 {
235 public:
236   transcode_to_utf16(const char *utf8_input);
237     //!< translates the "utf8_input" from UTF-8 into UTF-16 format.
238     /*!< the resulting memory is held in this object until destruction, which
239     makes this especially convenient for in-place conversions. */
240
241   transcode_to_utf16(const astring &utf8_input);
242     //!< this conversion converts the astring in "utf8_input" into UTF-16.
243
244   virtual ~transcode_to_utf16();
245
246   int length() const;
247     //!< reports the length of the double-byte-based converted string.
248
249   operator const UTF16 * () const { return _converted; }
250     //!< observes the converted version of the string (constant version).
251   operator UTF16 * () { return _converted; }
252     //!< accesses the converted version of the string (modifiable version).
253   operator const flexichar * () const { return (const flexichar *)_converted; }
254     //!< accesses the converted version of the string (modifiable version).
255   operator flexichar * () { return (flexichar *)_converted; }
256     //!< accesses the converted version of the string (modifiable version).
257
258   ConversionResult _result;
259 private:
260   int _orig_length;  //!< how long is the original argument?
261   UTF16 *_converted;  //!< the double-byte version of the original string.
262 };
263
264 //////////////
265
266 //! handles the conversion of UTF-16 format strings into UTF-8.
267
268 class transcode_to_utf8 : public virtual root_object
269 {
270 public:
271   transcode_to_utf8(const UTF16 *utf16_input);
272     //!< translates the "utf16_input" from UTF-16 into UTF-8 format.
273     /*!< the resulting memory is held in this object until destruction, which
274     makes this especially convenient for in-place conversions. */
275
276   transcode_to_utf8(const wchar_t *utf16_input);
277     //!< converts win32 style wide characters to UTF-8.
278
279   virtual ~transcode_to_utf8();
280
281   int length() const;
282     //!< reports the length of the byte-based converted string.
283
284   operator const UTF8 * () const { return _converted; }
285     //!< observes the converted version of the string (constant version).
286   operator UTF8 * () { return _converted; }
287     //!< accesses the converted version of the string (modifiable version).
288
289   operator astring() const;
290     //!< converts the char pointer into an astring object.
291
292   ConversionResult _result;
293 private:
294   int _orig_length;  //!< how long is the original argument?
295   int _new_length;  //!< what did we predictively allocate for the result?
296   UTF8 *_converted;  //!< the double-byte version of the original string.
297 };
298
299 //////////////
300
301 //! provides an interface like the transcoders above, but stays in UTF-8.
302
303 class null_transcoder : public virtual root_object
304 {
305 public:
306   //! allocates memory for the converted form if "make_own_copy" is true.
307   null_transcoder(const char *utf8_input, bool make_own_copy);
308   //! similar, but supports astrings.
309   null_transcoder(const astring &utf8_input, bool make_own_copy);
310   ~null_transcoder() {
311     if (_make_own_copy) delete [] _converted;
312     _converted = NULL_POINTER;
313   }
314
315   int length() const;
316   operator char * () { return (char *)_converted; }
317   operator const char * () const { return (const char *)_converted; }
318
319 private:
320   bool _make_own_copy;
321   const UTF8 *_converted;
322 };
323
324 #endif //cplusplus
325
326 } //namespace.
327
328 #endif // outer guard.
329