icuSources/common/unicode/ucasemap.h

   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