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