icuSources/i18n/unicode/ulocdata.h

   1 /*
   2 ******************************************************************************
   3 *                                                                            *
   4 * Copyright (C) 2003-2007, International Business Machines                   *
   5 *                Corporation and others. All Rights Reserved.                *
   6 *                                                                            *
   7 ******************************************************************************
   8 *   file name:  ulocdata.h
   9 *   encoding:   US-ASCII
  10 *   tab size:   8 (not used)
  11 *   indentation:4
  12 *
  13 *   created on: 2003Oct21
  14 *   created by: Ram Viswanadha
  15 */
  16
  17 #ifndef __ULOCDATA_H__
  18 #define __ULOCDATA_H__
  19
  20 #include "unicode/ures.h"
  21 #include "unicode/uloc.h"
  22 #include "unicode/uset.h"
  23
  24 /**
  25  * \file
  26  * \brief C API: Provides access to locale data.
  27  */
  28
  29 /** Forward declaration of the ULocaleData structure. @stable ICU 3.6 */
  30 struct ULocaleData;
  31
  32 /** A locale data object. @stable ICU 3.6 */
  33 typedef struct ULocaleData ULocaleData;
  34
  35
  36
  37 /** The possible types of exemplar character sets.
  38   * @stable ICU 3.4
  39   */
  40 typedef enum ULocaleDataExemplarSetType  {
  41      ULOCDATA_ES_STANDARD=0,      /* Basic set */
  42      ULOCDATA_ES_AUXILIARY=1,     /* Auxiliary set */
  43      ULOCDATA_ES_COUNT=2
  44 } ULocaleDataExemplarSetType;
  45
  46 /** The possible types of delimiters.
  47   * @stable ICU 3.4
  48   */
  49 typedef enum ULocaleDataDelimiterType {
  50     ULOCDATA_QUOTATION_START = 0,     /* Quotation start */
  51      ULOCDATA_QUOTATION_END = 1,       /* Quotation end */
  52      ULOCDATA_ALT_QUOTATION_START = 2, /* Alternate quotation start */
  53      ULOCDATA_ALT_QUOTATION_END = 3,   /* Alternate quotation end */
  54      ULOCDATA_DELIMITER_COUNT = 4
  55 } ULocaleDataDelimiterType;
  56
  57 /**
  58  * Opens a locale data object for the given locale
  59  *
  60  * @param localeID  Specifies the locale associated with this locale
  61  *                  data object.
  62  * @param status    Pointer to error status code.
  63  * @stable ICU 3.4
  64  */
  65 U_STABLE ULocaleData* U_EXPORT2
  66 ulocdata_open(const char *localeID, UErrorCode *status);
  67
  68 /**
  69  * Closes a locale data object.
  70  *
  71  * @param uld       The locale data object to close
  72  * @stable ICU 3.4
  73  */
  74 U_STABLE void U_EXPORT2
  75 ulocdata_close(ULocaleData *uld);
  76
  77 /**
  78  * Sets the "no Substitute" attribute of the locale data
  79  * object.  If true, then any methods associated with the
  80  * locale data object will return null when there is no
  81  * data available for that method, given the locale ID
  82  * supplied to ulocdata_open().
  83  *
  84  * @param uld       The locale data object to set.
  85  * @param setting   Value of the "no substitute" attribute.
  86  * @stable ICU 3.4
  87  */
  88 U_STABLE void U_EXPORT2
  89 ulocdata_setNoSubstitute(ULocaleData *uld, UBool setting);
  90
  91 /**
  92  * Retrieves the current "no Substitute" value of the locale data
  93  * object.  If true, then any methods associated with the
  94  * locale data object will return null when there is no
  95  * data available for that method, given the locale ID
  96  * supplied to ulocdata_open().
  97  *
  98  * @param uld       Pointer to the The locale data object to set.
  99  * @return UBool    Value of the "no substitute" attribute.
 100  * @stable ICU 3.4
 101  */
 102 U_STABLE UBool U_EXPORT2
 103 ulocdata_getNoSubstitute(ULocaleData *uld);
 104
 105 /**
 106  * Returns the set of exemplar characters for a locale.
 107  *
 108  * @param uld       Pointer to the locale data object from which the
 109  *                  exemplar character set is to be retrieved.
 110  * @param fillIn    Pointer to a USet object to receive the
 111  *                  exemplar character set for the given locale.  Previous
 112  *                  contents of fillIn are lost.  <em>If fillIn is NULL,
 113  *                  then a new USet is created and returned.  The caller
 114  *                  owns the result and must dispose of it by calling
 115  *                  uset_close.</em>
 116  * @param options   Bitmask for options to apply to the exemplar pattern.
 117  *                  Specify zero to retrieve the exemplar set as it is
 118  *                  defined in the locale data.  Specify
 119  *                  USET_CASE_INSENSITIVE to retrieve a case-folded
 120  *                  exemplar set.  See uset_applyPattern for a complete
 121  *                  list of valid options.  The USET_IGNORE_SPACE bit is
 122  *                  always set, regardless of the value of 'options'.
 123  * @param extype    Specifies the type of exemplar set to be retrieved.
 124  * @param status    Pointer to an input-output error code value;
 125  *                  must not be NULL.
 126  * @return USet*    Either fillIn, or if fillIn is NULL, a pointer to
 127  *                  a newly-allocated USet that the user must close.
 128  * @stable ICU 3.4
 129  */
 130 U_STABLE USet* U_EXPORT2
 131 ulocdata_getExemplarSet(ULocaleData *uld, USet *fillIn,
 132                         uint32_t options, ULocaleDataExemplarSetType extype, UErrorCode *status);
 133
 134 /**
 135  * Returns one of the delimiter strings associated with a locale.
 136  *
 137  * @param uld           Pointer to the locale data object from which the
 138  *                      delimiter string is to be retrieved.
 139  * @param type          the type of delimiter to be retrieved.
 140  * @param result        A pointer to a buffer to receive the result.
 141  * @param resultLength  The maximum size of result.
 142  * @param status        Pointer to an error code value
 143  * @return int32_t      The total buffer size needed; if greater than resultLength,
 144  *                      the output was truncated.
 145  * @stable ICU 3.4
 146  */
 147 U_STABLE int32_t U_EXPORT2
 148 ulocdata_getDelimiter(ULocaleData *uld, ULocaleDataDelimiterType type, UChar *result, int32_t resultLength, UErrorCode *status);
 149
 150 /**
 151  * Enumeration for representing the measurement systems.
 152  * @stable ICU 2.8
 153  */
 154 typedef enum UMeasurementSystem {
 155     UMS_SI,     /** Measurement system specified by SI otherwise known as Metric system. */
 156     UMS_US,     /** Measurement system followed in the United States of America. */
 157     UMS_LIMIT
 158 } UMeasurementSystem;
 159
 160 /**
 161  * Returns the measurement system used in the locale specified by the localeID.
 162  * Please note that this API will change in ICU 3.6 and will use an ulocdata object.
 163  *
 164  * @param localeID      The id of the locale for which the measurement system to be retrieved.
 165  * @param status        Must be a valid pointer to an error code value,
 166  *                      which must not indicate a failure before the function call.
 167  * @return UMeasurementSystem the measurement system used in the locale.
 168  * @stable ICU 2.8
 169  */
 170 U_STABLE UMeasurementSystem U_EXPORT2
 171 ulocdata_getMeasurementSystem(const char *localeID, UErrorCode *status);
 172
 173 /**
 174  * Returns the element gives the normal business letter size, and customary units.
 175  * The units for the numbers are always in <em>milli-meters</em>.
 176  * For US since 8.5 and 11 do not yeild an integral value when converted to milli-meters,
 177  * the values are rounded off.
 178  * So for A4 size paper the height and width are 297 mm and 210 mm repectively,
 179  * and for US letter size the height and width are 279 mm and 216 mm respectively.
 180  * Please note that this API will change in ICU 3.6 and will use an ulocdata object.
 181  *
 182  * @param localeID      The id of the locale for which the paper size information to be retrieved.
 183  * @param height        A pointer to int to recieve the height information.
 184  * @param width         A pointer to int to recieve the width information.
 185  * @param status        Must be a valid pointer to an error code value,
 186  *                      which must not indicate a failure before the function call.
 187  * @stable ICU 2.8
 188  */
 189 U_STABLE void U_EXPORT2
 190 ulocdata_getPaperSize(const char *localeID, int32_t *height, int32_t *width, UErrorCode *status);
 191
 192 #endif