• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 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
300