icuSources/i18n/unicode/ulocdata.h

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