ACE/ACEXML/common/Transcode.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Transcode.h
   6  *
   7  * This file declares functions to convert char string among different
   8  * unicode encoding (utf8, utf16, utf32)
   9  *
  10  *  @author Nanbor Wang <nanbor@cs.wustl.edu>
  11  */
  12 //=============================================================================
  13
  14 #ifndef _ACEXML_TRANSCODE_H_
  15 #define _ACEXML_TRANSCODE_H_
  16
  17 #include /**/ "ace/pre.h"
  18 #include "ACEXML/common/ACEXML_Export.h"
  19
  20 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  21 #pragma once
  22 #endif /* ACE_LACKS_PRAGMA_ONCE */
  23
  24 #include "ACEXML/common/XML_Types.h"
  25
  26 /**
  27  * @class ACEXML_Transcoder
  28  *
  29  * @brief ACEXML_Transcoder
  30  *
  31  * Wrapper class for performing transcoding among different UNICODE
  32  * encoding.
  33  */
  34 class ACEXML_Export ACEXML_Transcoder
  35 {
  36 public:
  37   /*
  38    * Status of the conversion function.
  39    */
  40   enum
  41   {
  42     ACEXML_SUCCESS = 0,
  43     ACEXML_DESTINATION_TOO_SHORT = -1,
  44     ACEXML_END_OF_SOURCE = -2,
  45     ACEXML_INVALID_ARGS = -3,
  46     ACEXML_IS_SURROGATE = -4,
  47     ACEXML_NON_UNICODE = -5
  48   } ACEXML_STATUS;
  49
  50
  51   // The following functions translate a unicode characters
  52   // into different encoding.  Return number of characters put into
  53   // destination or consumed from src if success without
  54   // error, otherwise, return corresponding error code.
  55   /*
  56    * Convert a UTF-16 character into a string in UTF-8 encoding.
  57    *
  58    * @return number of characters the function uses to store the
  59    *         converted string if it succeeds or one of the error STATUS
  60    *         otherwise.
  61    */
  62   static int utf162utf8 (ACEXML_UTF16 src,
  63                          ACEXML_UTF8 *dst,
  64                          size_t len);
  65
  66   /*
  67    * Convert a UCS-4 character into a string in UTF-8 encoding.
  68    *
  69    * @return number of characters the function uses to store the
  70    *         converted string if it succeeds or one of the error STATUS
  71    *         otherwise.
  72    */
  73   static int ucs42utf8 (ACEXML_UCS4 src,
  74                         ACEXML_UTF8 *dst,
  75                         size_t len);
  76
  77   /*
  78    * Convert a UCS-4 character into a string in UTF-16 encoding.
  79    *
  80    * @return number of characters the function uses to store the
  81    *         converted string if it succeeds or one of the error STATUS
  82    *         otherwise.
  83    */
  84   static int ucs42utf16 (ACEXML_UCS4 src,
  85                          ACEXML_UTF16 *dst,
  86                          size_t len);
  87
  88   /*
  89    * Convert a UTF-16 surrogate character pair into a string in UTF-8 encoding.
  90    *
  91    * @return number of characters the function uses to store the
  92    *         converted string if it succeeds or one of the error STATUS
  93    *         otherwise.
  94    */
  95   static int surrogate2utf8 (ACEXML_UTF16 high,
  96                              ACEXML_UTF16 low,
  97                              ACEXML_UTF8 *dst,
  98                              size_t len);
  99
 100   /*
 101    * Convert a UTF-16 surrogate character pair into a UCS-4 character.
 102    *
 103    * @return SUCCESS if it succeeds or one of the error STATUS
 104    *         otherwise.
 105    */
 106   static int surrogate2ucs4 (ACEXML_UTF16 high,
 107                              ACEXML_UTF16 low,
 108                              ACEXML_UCS4 &dst);
 109
 110   /*
 111    * Convert the first UNICODE character in a UTF-8 character string
 112    * into a UCS-4 character.
 113    *
 114    * @return number of characters the function consumed from the
 115    *         UTF-8 string if it succeeds or one of the error STATUS
 116    *         otherwise.
 117    */
 118   static int utf82ucs4 (const ACEXML_UTF8 *src,
 119                         size_t len,
 120                         ACEXML_UCS4 &dst);
 121
 122   /*
 123    * Convert the first UNICODE character in a UTF-16 character string
 124    * into a UCS-4 character.
 125    *
 126    * @return number of characters the function consumed from the
 127    *         UTF-16 string if it succeeds or one of the error STATUS
 128    *         otherwise.
 129    */
 130   static int utf162ucs4 (const ACEXML_UTF16 *src,
 131                         size_t len,
 132                         ACEXML_UCS4 &dst);
 133
 134 //    static int utf82utf16 (const ACEXML_UTF8 *src,
 135 //                           size_t len,
 136 //                           ACEXML_UTF16 &dst);
 137   // This function does not handle surrogates.
 138
 139   // = The following functions are non-inlined:
 140
 141   /*
 142    * Convert a UTF-8 string into a UTF-16 string.
 143    *
 144    * @param len The length of @a dst string.
 145    *
 146    * @return number of characters the function consumed from the
 147    *         UTF-8 string if it succeeds or one of the error STATUS
 148    *         otherwise.
 149    */
 150   static int utf8s2utf16s (const ACEXML_UTF8 *src,
 151                            ACEXML_UTF16 *dst,
 152                            size_t len);
 153
 154   /*
 155    * Convert a UTF-16 string into a UTF-8 string.
 156    *
 157    * @param len The length of @a dst string.
 158    *
 159    * @return number of characters the function uses in
 160    *         UTF-8 string if it succeeds or one of the error STATUS
 161    *         otherwise.
 162    */
 163   static int utf16s2utf8s (const ACEXML_UTF16 *src,
 164                            ACEXML_UTF8 *dst,
 165                            size_t len);
 166 };
 167
 168 #include /**/ "ace/post.h"
 169
 170 #endif /* _ACEXML_TRANSCODE_H_ */