home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 6 / AACD06.ISO / AACD / Programming / ICU / include / convert.h < prev    next >
C/C++ Source or Header  |  1999-11-12  |  15KB  |  325 lines
  1. /*******************************************************************************
  2.  *                                                                              *
  3.  * COPYRIGHT:                                                                   *
  4.  *   (C) Copyright International Business Machines Corporation,  1998           *
  5.  *   Licensed Material - Program-Property of IBM - All Rights Reserved.         *
  6.  *   US Government Users Restricted Rights - Use, duplication, or disclosure    *
  7.  *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  8.  *                                                                              *
  9.  *******************************************************************************/
  10.  
  11. #ifndef CONVERT_H
  12. #define CONVERT_H
  13.  
  14.  
  15. #include "unistr.h"
  16. #include "ucnv.h"
  17.  
  18. class U_COMMON_API UnicodeConverterCPP
  19. {
  20.  private:
  21.   /*Internal Data representation of the Converter*/
  22.   UConverter* myUnicodeConverter;
  23.   /*Debug method*/
  24.   void printRef(void) const;
  25.  
  26.  public:
  27.  
  28. //Constructors and a destructor
  29.  
  30.   /**
  31.  * Creates Unicode Conversion Object will default to LATIN1 <-> encoding
  32.  * @return An object Handle if successful or a NULL if the creation failed
  33.  */
  34.  UnicodeConverterCPP();
  35.  
  36. /**
  37.  * Creates Unicode Conversion Object by specifying the codepage name.  The name
  38.  * string is in ASCII format.
  39.  * @param code_set the pointer to a char[] object containing a codepage name. (I)
  40.  * @param UErrorCode Error status (I/O) IILLEGAL_ARGUMENT_ERROR will be returned if the string is empty.
  41.  * If the internal program does not work correctly, for example, if there's no such codepage,
  42.  * U_INTERNAL_PROGRAM_ERROR will be returned.
  43.  * @return An object Handle if successful or a NULL if the creation failed
  44.  */
  45.  UnicodeConverterCPP(const char*             name,
  46.              UErrorCode&              err);
  47.  
  48.  /**
  49.   *Creates a UnicodeConverter object with the names specified as unicode strings. The name should be limited to
  50.   *the ASCII-7 alphanumerics. Dash and underscore characters are allowed for readability, but are ignored in the
  51.   *search.
  52.   *@param code_set name of the uconv table in Unicode string (I)
  53.   *@param err error status (I/O) IILLEGAL_ARGUMENT_ERROR will be returned if the string is empty.  If the internal
  54.   *program does not work correctly, for example, if there's no such codepage, U_INTERNAL_PROGRAM_ERROR will be
  55.   *returned.
  56.   *@return the created Unicode converter object
  57.   */
  58.  UnicodeConverterCPP(const UnicodeString&    name,
  59.              UErrorCode&              err);
  60.  
  61.  /**
  62.   * Creates Unicode Conversion Object using the codepage ID number.
  63.   * @param code_set a codepage # (I)
  64.   * @UErrorCode Error status (I/O) IILLEGAL_ARGUMENT_ERROR will be returned if the string is empty.
  65.   * If the internal program does not work correctly, for example, if there's no such codepage,
  66.   * U_INTERNAL_PROGRAM_ERROR will be returned.
  67.   * @return An object Handle if successful or a NULL if failed
  68.   *
  69.   */
  70.  UnicodeConverterCPP(int32_t                      codepageNumber,
  71.              UConverterPlatform  platform,
  72.              UErrorCode&                   err);
  73.  
  74.  ~UnicodeConverterCPP();
  75.  
  76.  
  77.  /**
  78.   * Transcodes the source UnicodeString to the target string in a codepage encoding
  79.   * with the specified Unicode converter.  For example, if a Unicode to/from JIS
  80.   * converter is specified, the source string in Unicode will be transcoded to JIS
  81.   * encoding.  The result will be stored in JIS encoding.
  82.   *
  83.   * @param source the source Unicode string
  84.   * @param target the target string in codepage encoding
  85.   * @param targetSize Input the number of bytes available in the "target" buffer, Output the number of bytes copied to it
  86.   * @param err the error status code.  U_MEMORY_ALLOCATION_ERROR will be returned if the
  87.   * the internal process buffer cannot be allocated for transcoding.  U_ILLEGAL_ARGUMENT_ERROR
  88.   * is returned if the converter is null or the source or target string is empty.
  89.   */
  90. void fromUnicodeString(char*                    target,
  91.                int32_t&                 targetSize,
  92.                const UnicodeString&     source,
  93.                UErrorCode&               err) const;
  94.  
  95. /**
  96.  * Transcode the source string in codepage encoding to the target string in
  97.  * Unicode encoding.  For example, if a Unicode to/from JIS
  98.  * converter is specified, the source string in JIS encoding will be transcoded
  99.  * to Unicode encoding.  The result will be stored in Unicode encoding.
  100.  * @param source the source string in codepage encoding
  101.  * @param target the target string in Unicode encoding
  102.  * @param targetSize : I/O parameter, Input size buffer, Output # of bytes copied to it
  103.  * @param err the error status code U_MEMORY_ALLOCATION_ERROR will be returned if the
  104.  * the internal process buffer cannot be allocated for transcoding.  U_ILLEGAL_ARGUMENT_ERROR
  105.  * is returned if the converter is null or the source or target string is empty.
  106.  */
  107. void  toUnicodeString(UnicodeString&    target,
  108.                       const char*       source,
  109.                       int32_t           sourceSize,
  110.                       UErrorCode&        err) const;
  111.  
  112. /**
  113.  * Transcodes an array of unicode characters to an array of codepage characters.
  114.  * The source pointer is an I/O parameter, it starts out pointing at the place
  115.  * to begin translating, and ends up pointing after the first sequence of the bytes
  116.  * that it encounters that are semantically invalid.
  117.  * if T_UnicodeConverter_setMissingCharAction is called with an action other than STOP
  118.  * before a call is made to this API, consumed and source should point to the same place
  119.  * (unless target ends with an imcomplete sequence of bytes and flush is FALSE).
  120.  * @param target : I/O parameter. Input : Points to the beginning of the buffer to copy
  121.  *  codepage characters to. Output : points to after the last codepage character copied
  122.  *  to target.
  123.  * @param targetLimit the pointer to the end of the target array
  124.  * @param source the source Unicode character array
  125.  * @param sourceLimit the pointer to the end of the source array
  126.  * @param flush TRUE if the buffer is the last buffer and the conversion will finish
  127.  * in this call, FALSE otherwise.  (future feature pending)
  128.  * @param UErrorCode the error status.  U_ILLEGAL_ARGUMENT_ERROR will be returned if the
  129.  * converter is null.
  130.  */
  131. void fromUnicode(char*&         target,
  132.                  const char*    targetLimit,
  133.                  const UChar*&      source,
  134.                  const UChar* sourceLimit,
  135.          int32_t * offsets,
  136.                  bool_t         flush,
  137.                  UErrorCode&     err);
  138.  
  139.  
  140. /**
  141.  * Converts an array of codepage characters into an array of unicode characters.
  142.  * The source pointer is an I/O parameter, it starts out pointing at the place
  143.  * to begin translating, and ends up pointing after the first sequence of the bytes
  144.  * that it encounters that are semantically invalid.
  145.  * if T_UnicodeConverter_setMissingUnicodeAction is called with an action other than STOP
  146.  * before a call is made to this API, consumed and source should point to the same place
  147.  * (unless target ends with an imcomplete sequence of bytes and flush is FALSE).
  148.  * @param target : I/O parameter. Input : Points to the beginning of the buffer to copy
  149.  *  Unicode characters to. Output : points to after the last UChar copied to target.
  150.  * @param targetLimit the pointer to the end of the target array
  151.  * @param source the source codepage character array
  152.  * @param sourceLimit the pointer to the end of the source array
  153.  * @param flush TRUE if the buffer is the last buffer and the conversion will finish
  154.  * in this call, FALSE otherwise.  (future feature pending)
  155.  * @param err the error code status  U_ILLEGAL_ARGUMENT_ERROR will be returned if the
  156.  * converter is null, targetLimit < target, sourceLimit < source
  157.  */
  158.  void toUnicode(UChar*&        target,
  159.         const UChar*   targetLimit,
  160.         const char*&     source,
  161.         const char*      sourceLimit,
  162.         int32_t * offsets,
  163.         bool_t           flush,
  164.         UErrorCode&       err);
  165.  
  166.  
  167. /*
  168. * Returns the maximum length of bytes used by a character. This varies between 1 and 4
  169. * @return the max number of bytes per codepage character  * converter is null, targetLimit < target, sourceLimit < source
  170. */
  171. int8_t getMaxBytesPerChar(void) const;
  172.  
  173. /**
  174. * Returns the minimum byte length for characters in this codepage. This is either
  175. * 1 or 2 for all supported codepages.
  176. * @return the minimum number of byte per codepage character
  177. */
  178. int8_t getMinBytesPerChar(void) const;
  179.  
  180. /**
  181.  *Gets the type of conversion associated with the converter
  182.  * e.g. SBCS, MBCS, DBCS, UTF8, UTF16_BE, UTF16_LE, ISO_2022, EBCDIC_STATEFUL, LATIN_1
  183.  * @return the type of the converter
  184.  */
  185. UConverterType getType(void) const;
  186.  
  187. /**
  188.  *Gets the "starter" bytes for the converters of type MBCS
  189.  *will fill in an <TT>U_ILLEGAL_ARGUMENT_ERROR</TT> if converter passed in
  190.  *is not MBCS.
  191.  *fills in an array of boolean, with the value of the byte as offset to the array.
  192.  *At return, if TRUE is found in at offset 0x20, it means that the byte 0x20 is a starter byte
  193.  *in this converter.
  194.  * @param starters: an array of size 256 to be filled in
  195.  * @param err: an array of size 256 to be filled in
  196.  * @see ucnv_getType
  197.  */
  198.  void getStarters(bool_t starters[256],
  199.           UErrorCode& err) const;
  200.  /**
  201.  * Fills in the output parameter, subChars, with the substitution characters
  202.  * as multiple bytes.
  203.  * @param subChars the subsitution characters
  204.  * @param len the number of bytes of the substitution character array
  205.  * @param  err the error status code.  U_ILLEGAL_ARGUMENT_ERROR will be returned if
  206.  * the converter is null.  If the substitution character array is too small, an
  207.  * U_INDEX_OUTOFBOUNDS_ERROR will be returned.
  208.  */
  209. void getSubstitutionChars(char*         subChars,
  210.                           int8_t&       len,
  211.                           UErrorCode&    err) const;
  212. /**
  213.  * Sets the substitution chars when converting from unicode to a codepage. The
  214.  * substitution is specified as a string of 1-4 bytes, and may contain null byte.
  215.  * The fill-in parameter err will get the error status on return.
  216.  * @param cstr the substitution character array to be set with
  217.  * @param len the number of bytes of the substitution character array and upon return will contain the
  218.  * number of bytes copied to that buffer
  219.  * @param err the error status code.  U_ILLEGAL_ARGUMENT_ERROR if the converter is
  220.  * null.   or if the number of bytes provided are not in the codepage's range (e.g length 1 for ucs-2)
  221.  */
  222. void setSubstitutionChars(const char*   subChars,
  223.                           int8_t        len,
  224.                           UErrorCode&    err);
  225.  
  226. /**
  227.  * Resets the state of stateful conversion to the default state. This is used
  228.  * in the case of error to restart a conversion from a known default state.
  229.  */
  230. void resetState(void);
  231.  
  232. /**
  233.  * Gets the name of the converter (zero-terminated).
  234.  * the name will be the internal name of the converter
  235.  * @param converter the Unicode converter
  236.  * @param err the error status code. U_INDEX_OUTOFBOUNDS_ERROR in the converterNameLen is too
  237.  * small to contain the name.
  238.  */
  239. const char*  getName( UErrorCode&  err) const;
  240.  
  241.  
  242. /**
  243.  * Gets a codepage number associated with the converter. This is not guaranteed
  244.  * to be the one used to create the converter. Some converters do not represent
  245.  * IBM registered codepages and return zero for the codepage number.
  246.  * The error code fill-in parameter indicates if the codepage number is available.
  247.  * @param err the error status code.  U_ILLEGAL_ARGUMENT_ERROR will returned if
  248.  * the converter is null or if converter's data table is null.
  249.  * @return If any error occurrs, null will be returned.
  250.  */
  251.  int32_t  getCodepage(UErrorCode& err) const;
  252.  
  253.  /**
  254.   * Returns the current setting action taken when a character from a codepage
  255.   * is missing. (Currently STOP or SUBSTITUTE).
  256.   * @return the action constant when a Unicode character cannot be converted to a
  257.   * codepage equivalent
  258.   */
  259.  UConverterToUCallback   getMissingCharAction(void) const;
  260.  
  261. /**
  262.  * Return the current setting action taken when a unicode character is missing.
  263.  * (Currently STOP or SUBSTITUTE).
  264.  * @return the action constant when a codepage character cannot be converted to a
  265.  * Unicode eqivalent
  266.  */
  267.  UConverterFromUCallback   getMissingUnicodeAction(void) const;
  268.  
  269.  /**
  270.   * Sets the current setting action taken when a character from a codepage is
  271.   * missing. (Currently STOP or SUBSTITUTE).
  272.   * @param action the action constant if an equivalent codepage character is missing
  273.   */
  274.  void  setMissingCharAction(UConverterToUCallback     action,
  275.                 UErrorCode&            err);
  276.  
  277. /**
  278.  * Sets the current setting action taken when a unicode character is missing.
  279.  * (currently T_UnicodeConverter_MissingUnicodeAction is either STOP or SUBSTITUTE,
  280.  *  SKIP, CLOSEST_MATCH, ESCAPE_SEQ may be added in the future).
  281.  * @param action the action constant if an equivalent Unicode character is missing
  282.  * @param err the error status code
  283. */
  284.  void  setMissingUnicodeAction(UConverterFromUCallback  action,
  285.                    UErrorCode&            err);
  286. /**
  287.  * Returns the localized name of the UnicodeConverter, if for any reason it is
  288.  * available, the internal name will be returned instead.
  289.  * @param displayLocale the valid Locale, from which we want to localize
  290.  * @param displayString a UnicodeString that is going to be filled in.
  291.  */
  292. void getDisplayName(const Locale&   displayLocale,
  293.                     UnicodeString&  displayName) const;
  294.  
  295. /**
  296.  * Returns the T_UnicodeConverter_platform (ICU defined enum) of a UnicodeConverter
  297.  * available, the internal name will be returned instead.
  298.  * @param err the error code status
  299.  * @return the codepages platform
  300.  */
  301. UConverterPlatform  getCodepagePlatform(UErrorCode& err) const;
  302.  
  303.  
  304.  UnicodeConverterCPP&   operator=(const UnicodeConverterCPP& that);
  305.  bool_t              operator==(const UnicodeConverterCPP& that) const;
  306.  bool_t              operator!=(const UnicodeConverterCPP& that) const;
  307.  UnicodeConverterCPP(const UnicodeConverterCPP&  that);
  308.  
  309. /**
  310.  * Returns the available names. Lazy evaluated, Library owns the storage
  311.  * @param num the number of available converters
  312.  * @param err the error code status
  313.  * @return the name array
  314.  */
  315. static  const char* const* getAvailableNames(int32_t&   num,
  316.                          UErrorCode&  err);
  317.  
  318. /**
  319.  * Iterates through every cached converter and frees all the unused ones
  320.  * @return the number of cached converters successfully deleted
  321.  */
  322. static   int32_t flushCache(void);
  323. };
  324. #endif
  325.