ulocdata.h (11568B)
1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ****************************************************************************** 5 * * 6 * Copyright (C) 2003-2015, International Business Machines * 7 * Corporation and others. All Rights Reserved. * 8 * * 9 ****************************************************************************** 10 * file name: ulocdata.h 11 * encoding: UTF-8 12 * tab size: 8 (not used) 13 * indentation:4 14 * 15 * created on: 2003Oct21 16 * created by: Ram Viswanadha 17 */ 18 19 #ifndef __ULOCDATA_H__ 20 #define __ULOCDATA_H__ 21 22 #include "unicode/ures.h" 23 #include "unicode/uloc.h" 24 #include "unicode/uset.h" 25 26 #if U_SHOW_CPLUSPLUS_API 27 #include "unicode/localpointer.h" 28 #endif // U_SHOW_CPLUSPLUS_API 29 30 /** 31 * \file 32 * \brief C API: Provides access to locale data. 33 */ 34 35 /** Forward declaration of the ULocaleData structure. @stable ICU 3.6 */ 36 struct ULocaleData; 37 38 /** A locale data object. @stable ICU 3.6 */ 39 typedef struct ULocaleData ULocaleData; 40 41 42 43 /** The possible types of exemplar character sets. 44 * @stable ICU 3.4 45 */ 46 typedef enum ULocaleDataExemplarSetType { 47 /** Basic set @stable ICU 3.4 */ 48 ULOCDATA_ES_STANDARD=0, 49 /** Auxiliary set @stable ICU 3.4 */ 50 ULOCDATA_ES_AUXILIARY=1, 51 /** Index Character set @stable ICU 4.8 */ 52 ULOCDATA_ES_INDEX=2, 53 /** Punctuation set @stable ICU 51 */ 54 ULOCDATA_ES_PUNCTUATION=3, 55 #ifndef U_HIDE_DEPRECATED_API 56 /** 57 * One more than the highest normal ULocaleDataExemplarSetType value. 58 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 59 */ 60 ULOCDATA_ES_COUNT=4 61 #endif /* U_HIDE_DEPRECATED_API */ 62 } ULocaleDataExemplarSetType; 63 64 /** The possible types of delimiters. 65 * @stable ICU 3.4 66 */ 67 typedef enum ULocaleDataDelimiterType { 68 /** Quotation start @stable ICU 3.4 */ 69 ULOCDATA_QUOTATION_START = 0, 70 /** Quotation end @stable ICU 3.4 */ 71 ULOCDATA_QUOTATION_END = 1, 72 /** Alternate quotation start @stable ICU 3.4 */ 73 ULOCDATA_ALT_QUOTATION_START = 2, 74 /** Alternate quotation end @stable ICU 3.4 */ 75 ULOCDATA_ALT_QUOTATION_END = 3, 76 #ifndef U_HIDE_DEPRECATED_API 77 /** 78 * One more than the highest normal ULocaleDataDelimiterType value. 79 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 80 */ 81 ULOCDATA_DELIMITER_COUNT = 4 82 #endif /* U_HIDE_DEPRECATED_API */ 83 } ULocaleDataDelimiterType; 84 85 /** 86 * Opens a locale data object for the given locale 87 * 88 * @param localeID Specifies the locale associated with this locale 89 * data object. 90 * @param status Pointer to error status code. 91 * @stable ICU 3.4 92 */ 93 U_CAPI ULocaleData* U_EXPORT2 94 ulocdata_open(const char *localeID, UErrorCode *status); 95 96 /** 97 * Closes a locale data object. 98 * 99 * @param uld The locale data object to close 100 * @stable ICU 3.4 101 */ 102 U_CAPI void U_EXPORT2 103 ulocdata_close(ULocaleData *uld); 104 105 #if U_SHOW_CPLUSPLUS_API 106 107 U_NAMESPACE_BEGIN 108 109 /** 110 * \class LocalULocaleDataPointer 111 * "Smart pointer" class, closes a ULocaleData via ulocdata_close(). 112 * For most methods see the LocalPointerBase base class. 113 * 114 * @see LocalPointerBase 115 * @see LocalPointer 116 * @stable ICU 4.4 117 */ 118 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDataPointer, ULocaleData, ulocdata_close); 119 120 U_NAMESPACE_END 121 122 #endif 123 124 /** 125 * Sets the "no Substitute" attribute of the locale data 126 * object. If true, then any methods associated with the 127 * locale data object will return null when there is no 128 * data available for that method, given the locale ID 129 * supplied to ulocdata_open(). 130 * 131 * @param uld The locale data object to set. 132 * @param setting Value of the "no substitute" attribute. 133 * @stable ICU 3.4 134 */ 135 U_CAPI void U_EXPORT2 136 ulocdata_setNoSubstitute(ULocaleData *uld, UBool setting); 137 138 /** 139 * Retrieves the current "no Substitute" value of the locale data 140 * object. If true, then any methods associated with the 141 * locale data object will return null when there is no 142 * data available for that method, given the locale ID 143 * supplied to ulocdata_open(). 144 * 145 * @param uld Pointer to the locale data object to set. 146 * @return UBool Value of the "no substitute" attribute. 147 * @stable ICU 3.4 148 */ 149 U_CAPI UBool U_EXPORT2 150 ulocdata_getNoSubstitute(ULocaleData *uld); 151 152 /** 153 * Returns the set of exemplar characters for a locale. 154 * 155 * @param uld Pointer to the locale data object from which the 156 * exemplar character set is to be retrieved. 157 * @param fillIn Pointer to a USet object to receive the 158 * exemplar character set for the given locale. Previous 159 * contents of fillIn are lost. <em>If fillIn is NULL, 160 * then a new USet is created and returned. The caller 161 * owns the result and must dispose of it by calling 162 * uset_close.</em> 163 * @param options Bitmask for options to apply to the exemplar pattern. 164 * Specify zero to retrieve the exemplar set as it is 165 * defined in the locale data. Specify 166 * USET_CASE_INSENSITIVE to retrieve a case-folded 167 * exemplar set. See uset_applyPattern for a complete 168 * list of valid options. The USET_IGNORE_SPACE bit is 169 * always set, regardless of the value of 'options'. 170 * @param extype Specifies the type of exemplar set to be retrieved. 171 * @param status Pointer to an input-output error code value; 172 * must not be NULL. Will be set to U_MISSING_RESOURCE_ERROR 173 * if the requested data is not available. 174 * @return USet* Either fillIn, or if fillIn is NULL, a pointer to 175 * a newly-allocated USet that the user must close. 176 * In case of error, NULL is returned. 177 * @stable ICU 3.4 178 */ 179 U_CAPI USet* U_EXPORT2 180 ulocdata_getExemplarSet(ULocaleData *uld, USet *fillIn, 181 uint32_t options, ULocaleDataExemplarSetType extype, UErrorCode *status); 182 183 /** 184 * Returns one of the delimiter strings associated with a locale. 185 * 186 * @param uld Pointer to the locale data object from which the 187 * delimiter string is to be retrieved. 188 * @param type the type of delimiter to be retrieved. 189 * @param result A pointer to a buffer to receive the result. 190 * @param resultLength The maximum size of result. 191 * @param status Pointer to an error code value 192 * @return int32_t The total buffer size needed; if greater than resultLength, 193 * the output was truncated. 194 * @stable ICU 3.4 195 */ 196 U_CAPI int32_t U_EXPORT2 197 ulocdata_getDelimiter(ULocaleData *uld, ULocaleDataDelimiterType type, UChar *result, int32_t resultLength, UErrorCode *status); 198 199 /** 200 * Enumeration for representing the measurement systems. 201 * @stable ICU 2.8 202 */ 203 typedef enum UMeasurementSystem { 204 UMS_SI, /**< Measurement system specified by SI otherwise known as Metric system. @stable ICU 2.8 */ 205 UMS_US, /**< Measurement system followed in the United States of America. @stable ICU 2.8 */ 206 UMS_UK, /**< Mix of metric and imperial units used in Great Britain. @stable ICU 55 */ 207 #ifndef U_HIDE_DEPRECATED_API 208 /** 209 * One more than the highest normal UMeasurementSystem value. 210 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. 211 */ 212 UMS_LIMIT 213 #endif /* U_HIDE_DEPRECATED_API */ 214 } UMeasurementSystem; 215 216 /** 217 * Returns the measurement system used in the locale specified by the localeID. 218 * Please note that this API will change in ICU 3.6 and will use an ulocdata object. 219 * 220 * @param localeID The id of the locale for which the measurement system to be retrieved. 221 * @param status Must be a valid pointer to an error code value, 222 * which must not indicate a failure before the function call. 223 * @return UMeasurementSystem the measurement system used in the locale. 224 * @stable ICU 2.8 225 */ 226 U_CAPI UMeasurementSystem U_EXPORT2 227 ulocdata_getMeasurementSystem(const char *localeID, UErrorCode *status); 228 229 /** 230 * Returns the element gives the normal business letter size, and customary units. 231 * The units for the numbers are always in <em>milli-meters</em>. 232 * For US since 8.5 and 11 do not yield an integral value when converted to milli-meters, 233 * the values are rounded off. 234 * So for A4 size paper the height and width are 297 mm and 210 mm respectively, 235 * and for US letter size the height and width are 279 mm and 216 mm respectively. 236 * Please note that this API will change in ICU 3.6 and will use an ulocdata object. 237 * 238 * @param localeID The id of the locale for which the paper size information to be retrieved. 239 * @param height A pointer to int to receive the height information. 240 * @param width A pointer to int to receive the width information. 241 * @param status Must be a valid pointer to an error code value, 242 * which must not indicate a failure before the function call. 243 * @stable ICU 2.8 244 */ 245 U_CAPI void U_EXPORT2 246 ulocdata_getPaperSize(const char *localeID, int32_t *height, int32_t *width, UErrorCode *status); 247 248 /** 249 * Return the current CLDR version used by the library. 250 * @param versionArray fill-in that will receive the version number 251 * @param status error code - could be U_MISSING_RESOURCE_ERROR if the version was not found. 252 * @stable ICU 4.2 253 */ 254 U_CAPI void U_EXPORT2 255 ulocdata_getCLDRVersion(UVersionInfo versionArray, UErrorCode *status); 256 257 /** 258 * Returns locale display pattern associated with a locale. 259 * 260 * @param uld Pointer to the locale data object from which the 261 * exemplar character set is to be retrieved. 262 * @param pattern locale display pattern for locale. 263 * @param patternCapacity the size of the buffer to store the locale display 264 * pattern with. 265 * @param status Must be a valid pointer to an error code value, 266 * which must not indicate a failure before the function call. 267 * @return the actual buffer size needed for localeDisplayPattern. If it's greater 268 * than patternCapacity, the returned pattern will be truncated. 269 * 270 * @stable ICU 4.2 271 */ 272 U_CAPI int32_t U_EXPORT2 273 ulocdata_getLocaleDisplayPattern(ULocaleData *uld, 274 UChar *pattern, 275 int32_t patternCapacity, 276 UErrorCode *status); 277 278 279 /** 280 * Returns locale separator associated with a locale. 281 * 282 * @param uld Pointer to the locale data object from which the 283 * exemplar character set is to be retrieved. 284 * @param separator locale separator for locale. 285 * @param separatorCapacity the size of the buffer to store the locale 286 * separator with. 287 * @param status Must be a valid pointer to an error code value, 288 * which must not indicate a failure before the function call. 289 * @return the actual buffer size needed for localeSeparator. If it's greater 290 * than separatorCapacity, the returned separator will be truncated. 291 * 292 * @stable ICU 4.2 293 */ 294 U_CAPI int32_t U_EXPORT2 295 ulocdata_getLocaleSeparator(ULocaleData *uld, 296 UChar *separator, 297 int32_t separatorCapacity, 298 UErrorCode *status); 299 #endif