1 /*

     2 *******************************************************************************

     3 *

     4 *   Copyright (C) 2005, International Business Machines

     5 *   Corporation and others.  All Rights Reserved.

     6 *

     7 *******************************************************************************

     8 *   file name:  ucasemap.h

     9 *   encoding:   US-ASCII

    10 *   tab size:   8 (not used)

    11 *   indentation:4

    12 *

    13 *   created on: 2005may06

    14 *   created by: Markus W. Scherer

    15 *

    16 *   Case mapping service object and functions using it.

    17 */

    18 

    19 #ifndef __UCASEMAP_H__

    20 #define __UCASEMAP_H__

    21 

    22 #include "unicode/utypes.h"

    23 #include "unicode/ustring.h"

    24 

    25 /**

    26  * \file

    27  * \brief C API: Unicode case mapping functions using a UCaseMap service object.

    28  *

    29  * The service object takes care of memory allocations, data loading, and setup

    30  * for the attributes, as usual.

    31  *

    32  * Currently, the functionality provided here does not overlap with uchar.h

    33  * and ustring.h.

    34  *

    35  * ucasemap_utf8ToLower() and ucasemap_utf8ToUpper() operate directly on

    36  * UTF-8 strings.

    37  */

    38 

    39 /**

    40  * UCaseMap is an opaque service object for newer ICU case mapping functions.

    41  * Older functions did not use a service object.

    42  * @draft ICU 3.4

    43  */

    44 struct UCaseMap;

    45 typedef struct UCaseMap UCaseMap; /**< C typedef for struct UCaseMap. @draft ICU 3.4 */

    46 

    47 /**

    48  * Open a UCaseMap service object for a locale and a set of options.

    49  * The locale ID and options are preprocessed so that functions using the

    50  * service object need not process them in each call.

    51  *

    52  * @param locale ICU locale ID, used for language-dependent

    53  *               upper-/lower-/title-casing according to the Unicode standard.

    54  *               Usual semantics: ""=root, NULL=default locale, etc.

    55  * @param options Options bit set, used for case folding and string comparisons.

    56  *                Same flags as for u_foldCase(), u_strFoldCase(),

    57  *                u_strCaseCompare(), etc.

    58  *                Use 0 or U_FOLD_CASE_DEFAULT for default behavior.

    59  * @param pErrorCode Must be a valid pointer to an error code value,

    60  *                   which must not indicate a failure before the function call.

    61  * @return Pointer to a UCaseMap service object, if successful.

    62  *

    63  * @draft ICU 3.4

    64  */

    65 U_DRAFT UCaseMap * U_EXPORT2

    66 ucasemap_open(const char *locale, uint32_t options, UErrorCode *pErrorCode);

    67 

    68 /**

    69  * Close a UCaseMap service object.

    70  * @param csm Object to be closed.

    71  * @draft ICU 3.4

    72  */

    73 U_DRAFT void U_EXPORT2

    74 ucasemap_close(UCaseMap *csm);

    75 

    76 /**

    77  * Get the locale ID that is used for language-dependent case mappings.

    78  * @param csm UCaseMap service object.

    79  * @return locale ID

    80  * @draft ICU 3.4

    81  */

    82 U_DRAFT const char * U_EXPORT2

    83 ucasemap_getLocale(const UCaseMap *csm);

    84 

    85 /**

    86  * Get the options bit set that is used for case folding and string comparisons.

    87  * @param csm UCaseMap service object.

    88  * @return options bit set

    89  * @draft ICU 3.4

    90  */

    91 U_DRAFT uint32_t U_EXPORT2

    92 ucasemap_getOptions(const UCaseMap *csm);

    93 

    94 /**

    95  * Set the locale ID that is used for language-dependent case mappings.

    96  *

    97  * @param csm UCaseMap service object.

    98  * @param locale Locale ID, see ucasemap_open().

    99  * @param pErrorCode Must be a valid pointer to an error code value,

   100  *                   which must not indicate a failure before the function call.

   101  *

   102  * @see ucasemap_open

   103  * @draft ICU 3.4

   104  */

   105 U_DRAFT void U_EXPORT2

   106 ucasemap_setLocale(UCaseMap *csm, const char *locale, UErrorCode *pErrorCode);

   107 

   108 /**

   109  * Set the options bit set that is used for case folding and string comparisons.

   110  *

   111  * @param csm UCaseMap service object.

   112  * @param options Options bit set, see ucasemap_open().

   113  * @param pErrorCode Must be a valid pointer to an error code value,

   114  *                   which must not indicate a failure before the function call.

   115  *

   116  * @see ucasemap_open

   117  * @draft ICU 3.4

   118  */

   119 U_DRAFT void U_EXPORT2

   120 ucasemap_setOptions(UCaseMap *csm, uint32_t options, UErrorCode *pErrorCode);

   121 

   122 /**

   123  * Lowercase the characters in a UTF-8 string.

   124  * Casing is locale-dependent and context-sensitive.

   125  * The result may be longer or shorter than the original.

   126  * The source string and the destination buffer must not overlap.

   127  *

   128  * @param csm       UCaseMap service object.

   129  * @param dest      A buffer for the result string. The result will be NUL-terminated if

   130  *                  the buffer is large enough.

   131  *                  The contents is undefined in case of failure.

   132  * @param destCapacity The size of the buffer (number of bytes). If it is 0, then

   133  *                  dest may be NULL and the function will only return the length of the result

   134  *                  without writing any of the result string.

   135  * @param src       The original string

   136  * @param srcLength The length of the original string. If -1, then src must be NUL-terminated.

   137  * @param pErrorCode Must be a valid pointer to an error code value,

   138  *                  which must not indicate a failure before the function call.

   139  * @return The length of the result string, if successful - or in case of a buffer overflow,

   140  *         in which case it will be greater than destCapacity.

   141  *

   142  * @see u_strToLower

   143  * @draft ICU 3.4

   144  */

   145 U_DRAFT int32_t U_EXPORT2

   146 ucasemap_utf8ToLower(const UCaseMap *csm,

   147                      char *dest, int32_t destCapacity,

   148                      const char *src, int32_t srcLength,

   149                      UErrorCode *pErrorCode);

   150 

   151 /**

   152  * Uppercase the characters in a UTF-8 string.

   153  * Casing is locale-dependent and context-sensitive.

   154  * The result may be longer or shorter than the original.

   155  * The source string and the destination buffer must not overlap.

   156  *

   157  * @param csm       UCaseMap service object.

   158  * @param dest      A buffer for the result string. The result will be NUL-terminated if

   159  *                  the buffer is large enough.

   160  *                  The contents is undefined in case of failure.

   161  * @param destCapacity The size of the buffer (number of bytes). If it is 0, then

   162  *                  dest may be NULL and the function will only return the length of the result

   163  *                  without writing any of the result string.

   164  * @param src       The original string

   165  * @param srcLength The length of the original string. If -1, then src must be NUL-terminated.

   166  * @param pErrorCode Must be a valid pointer to an error code value,

   167  *                  which must not indicate a failure before the function call.

   168  * @return The length of the result string, if successful - or in case of a buffer overflow,

   169  *         in which case it will be greater than destCapacity.

   170  *

   171  * @see u_strToUpper

   172  * @draft ICU 3.4

   173  */

   174 U_DRAFT int32_t U_EXPORT2

   175 ucasemap_utf8ToUpper(const UCaseMap *csm,

   176                      char *dest, int32_t destCapacity,

   177                      const char *src, int32_t srcLength,

   178                      UErrorCode *pErrorCode);

   179 

   180 #endif