ConvertUTF.h
Go to the documentation of this file.
00001 /*
00002  * Copyright 2001-2004 Unicode, Inc.
00003  * 
00004  * Disclaimer
00005  * 
00006  * This source code is provided as is by Unicode, Inc. No claims are
00007  * made as to fitness for any particular purpose. No warranties of any
00008  * kind are expressed or implied. The recipient agrees to determine
00009  * applicability of information provided. If this file has been
00010  * purchased on magnetic or optical media from Unicode, Inc., the
00011  * sole remedy for any claim will be exchange of defective media
00012  * within 90 days of receipt.
00013  * 
00014  * Limitations on Rights to Redistribute This Code
00015  * 
00016  * Unicode, Inc. hereby grants the right to freely use the information
00017  * supplied in this file in the creation of products supporting the
00018  * Unicode Standard, and to make copies of this file in any form
00019  * for internal or external distribution as long as this notice
00020  * remains attached.
00021  */
00022 
00023 /* ---------------------------------------------------------------------
00024 
00025     Conversions between UTF32, UTF-16, and UTF-8.  Header file.
00026 
00027     Several funtions are included here, forming a complete set of
00028     conversions between the three formats.  UTF-7 is not included
00029     here, but is handled in a separate source file.
00030 
00031     Each of these routines takes pointers to input buffers and output
00032     buffers.  The input buffers are const.
00033 
00034     Each routine converts the text between *sourceStart and sourceEnd,
00035     putting the result into the buffer between *targetStart and
00036     targetEnd. Note: the end pointers are *after* the last item: e.g. 
00037     *(sourceEnd - 1) is the last item.
00038 
00039     The return result indicates whether the conversion was successful,
00040     and if not, whether the problem was in the source or target buffers.
00041     (Only the first encountered problem is indicated.)
00042 
00043     After the conversion, *sourceStart and *targetStart are both
00044     updated to point to the end of last text successfully converted in
00045     the respective buffers.
00046 
00047     Input parameters:
00048         sourceStart - pointer to a pointer to the source buffer.
00049                 The contents of this are modified on return so that
00050                 it points at the next thing to be converted.
00051         targetStart - similarly, pointer to pointer to the target buffer.
00052         sourceEnd, targetEnd - respectively pointers to the ends of the
00053                 two buffers, for overflow checking only.
00054 
00055     These conversion functions take a ConversionFlags argument. When this
00056     flag is set to strict, both irregular sequences and isolated surrogates
00057     will cause an error.  When the flag is set to lenient, both irregular
00058     sequences and isolated surrogates are converted.
00059 
00060     Whether the flag is strict or lenient, all illegal sequences will cause
00061     an error return. This includes sequences such as: <F4 90 80 80>, <C0 80>,
00062     or <A0> in UTF-8, and values above 0x10FFFF in UTF-32. Conformant code
00063     must check for illegal sequences.
00064 
00065     When the flag is set to lenient, characters over 0x10FFFF are converted
00066     to the replacement character; otherwise (when the flag is set to strict)
00067     they constitute an error.
00068 
00069     Output parameters:
00070         The value "sourceIllegal" is returned from some routines if the input
00071         sequence is malformed.  When "sourceIllegal" is returned, the source
00072         value will point to the illegal value that caused the problem. E.g.,
00073         in UTF-8 when a sequence is malformed, it points to the start of the
00074         malformed sequence.  
00075 
00076     Author: Mark E. Davis, 1994.
00077     Rev History: Rick McGowan, fixes & updates May 2001.
00078                  Fixes & updates, Sept 2001.
00079 
00080 ------------------------------------------------------------------------ */
00081 
00082 /* ---------------------------------------------------------------------
00083     The following 4 definitions are compiler-specific.
00084     The C standard does not guarantee that wchar_t has at least
00085     16 bits, so wchar_t is no less portable than unsigned short!
00086     All should be unsigned values to avoid sign extension during
00087     bit mask & shift operations.
00088 ------------------------------------------------------------------------ */
00089 
00090 typedef unsigned int    UTF32;  /* at least 32 bits */
00091 typedef unsigned short  UTF16;  /* at least 16 bits */
00092 typedef unsigned char   UTF8;   /* typically 8 bits */
00093 typedef unsigned char   Boolean; /* 0 or 1 */
00094 
00095 /* Some fundamental constants */
00096 #define UNI_REPLACEMENT_CHAR (UTF32)0x0000FFFD
00097 #define UNI_MAX_BMP (UTF32)0x0000FFFF
00098 #define UNI_MAX_UTF16 (UTF32)0x0010FFFF
00099 #define UNI_MAX_UTF32 (UTF32)0x7FFFFFFF
00100 #define UNI_MAX_LEGAL_UTF32 (UTF32)0x0010FFFF
00101 
00102 typedef enum {
00103         conversionOK,           /* conversion successful */
00104         sourceExhausted,        /* partial character in source, but hit end */
00105         targetExhausted,        /* insuff. room in target for conversion */
00106         sourceIllegal           /* source sequence is illegal/malformed */
00107 } ConversionResult;
00108 
00109 typedef enum {
00110         strictConversion = 0,
00111         lenientConversion
00112 } ConversionFlags;
00113 
00114 /* This is for C++ and does no harm in C */
00115 #ifdef __cplusplus
00116 extern "C" {
00117 #endif
00118 
00119 ConversionResult ConvertUTF8toUTF16 (
00120                 const UTF8** sourceStart, const UTF8* sourceEnd, 
00121                 UTF16** targetStart, UTF16* targetEnd, ConversionFlags flags);
00122 
00123 ConversionResult ConvertUTF16toUTF8 (
00124                 const UTF16** sourceStart, const UTF16* sourceEnd, 
00125                 UTF8** targetStart, UTF8* targetEnd, ConversionFlags flags);
00126                 
00127 ConversionResult ConvertUTF8toUTF32 (
00128                 const UTF8** sourceStart, const UTF8* sourceEnd, 
00129                 UTF32** targetStart, UTF32* targetEnd, ConversionFlags flags);
00130 
00131 ConversionResult ConvertUTF32toUTF8 (
00132                 const UTF32** sourceStart, const UTF32* sourceEnd, 
00133                 UTF8** targetStart, UTF8* targetEnd, ConversionFlags flags);
00134                 
00135 ConversionResult ConvertUTF16toUTF32 (
00136                 const UTF16** sourceStart, const UTF16* sourceEnd, 
00137                 UTF32** targetStart, UTF32* targetEnd, ConversionFlags flags);
00138 
00139 ConversionResult ConvertUTF32toUTF16 (
00140                 const UTF32** sourceStart, const UTF32* sourceEnd, 
00141                 UTF16** targetStart, UTF16* targetEnd, ConversionFlags flags);
00142 
00143 Boolean isLegalUTF8Sequence(const UTF8 *source, const UTF8 *sourceEnd);
00144 
00145 #ifdef __cplusplus
00146 }
00147 #endif
00148 
00149 /* --------------------------------------------------------------------- */


rtabmap
Author(s): Mathieu Labbe
autogenerated on Fri Aug 28 2015 12:51:31