icuSources/i18n/unicode/uameasureformat.h

   1 /*
   2 *****************************************************************************************
   3 * Copyright (C) 2014-2017 Apple Inc. All Rights Reserved.
   4 *****************************************************************************************
   5 */
   6
   7 #ifndef UAMEASUREFORMAT_H
   8 #define UAMEASUREFORMAT_H
   9
  10 #include "unicode/utypes.h"
  11
  12 #if !UCONFIG_NO_FORMATTING
  13 #ifndef U_HIDE_DRAFT_API
  14
  15 #include "unicode/localpointer.h"
  16 #include "unicode/unum.h"
  17 #include "unicode/umisc.h"
  18 #include "unicode/ufieldpositer.h"
  19
  20 /**
  21  * \file
  22  * \brief C API: Format combinations of measurement units and numeric values.
  23  *
  24  * This is a somewhat temporary Apple-specific wrapper for using C++ MeasureFormat
  25  * to format Measure objects, until the official ICU C API is available.
  26  */
  27
  28 /**
  29  * Opaque UAMeasureFormat object for use in C programs.
  30  * @draft ICU 53
  31  */
  32 struct UAMeasureFormat;
  33 typedef struct UAMeasureFormat UAMeasureFormat;  /**< C typedef for struct UAMeasureFormat. @draft ICU 53 */
  34
  35 /**
  36  * Constants for various widths.
  37  * @draft ICU 53
  38  */
  39 typedef enum UAMeasureFormatWidth {
  40     /**
  41      * Full unit names, e.g. "5 hours, 37 minutes"
  42      * @draft ICU 53
  43      */
  44     UAMEASFMT_WIDTH_WIDE,
  45
  46     /**
  47      * Abbreviated unit names, e.g. "5 hr, 37 min"
  48      * @draft ICU 53
  49      */
  50     UAMEASFMT_WIDTH_SHORT,
  51
  52     /**
  53      * Use unit symbols if possible, e.g. "5h 37m"
  54      * @draft ICU 53
  55      */
  56     UAMEASFMT_WIDTH_NARROW,
  57
  58     /**
  59      * Completely omit unit designatins if possible, e.g. "5:37"
  60      * @draft ICU 53
  61      */
  62     UAMEASFMT_WIDTH_NUMERIC,
  63
  64     /**
  65      * Shorter, between SHORT and NARROW, e.g. "5hr 37min"
  66      * @draft ICU 57
  67      */
  68     UAMEASFMT_WIDTH_SHORTER,
  69
  70     /**
  71      * Count of values in this enum.
  72      * @draft ICU 53
  73      */
  74     UAMEASFMT_WIDTH_COUNT
  75 } UAMeasureFormatWidth;
  76
  77 /**
  78  * Measurement units
  79  * @draft ICU 54
  80  */
  81 typedef enum UAMeasureUnit {
  82     UAMEASUNIT_ACCELERATION_G_FORCE = (0 << 8) + 0,
  83     UAMEASUNIT_ACCELERATION_METER_PER_SECOND_SQUARED = (0 << 8) + 1, // (CLDR 26, ICU-541)
  84     //
  85     UAMEASUNIT_ANGLE_DEGREE         = (1 << 8) + 0,
  86     UAMEASUNIT_ANGLE_ARC_MINUTE     = (1 << 8) + 1,
  87     UAMEASUNIT_ANGLE_ARC_SECOND     = (1 << 8) + 2,
  88     UAMEASUNIT_ANGLE_RADIAN         = (1 << 8) + 3,     // (CLDR 26, ICU-541)
  89     UAMEASUNIT_ANGLE_REVOLUTION     = (1 << 8) + 4,     // (CLDR 28, ICU-561.3)
  90     //
  91     UAMEASUNIT_AREA_SQUARE_METER     = (2 << 8) + 0,
  92     UAMEASUNIT_AREA_SQUARE_KILOMETER = (2 << 8) + 1,
  93     UAMEASUNIT_AREA_SQUARE_FOOT      = (2 << 8) + 2,
  94     UAMEASUNIT_AREA_SQUARE_MILE      = (2 << 8) + 3,
  95     UAMEASUNIT_AREA_ACRE             = (2 << 8) + 4,
  96     UAMEASUNIT_AREA_HECTARE          = (2 << 8) + 5,
  97     UAMEASUNIT_AREA_SQUARE_CENTIMETER = (2 << 8) + 6,   // (CLDR 26, ICU-541)
  98     UAMEASUNIT_AREA_SQUARE_INCH      = (2 << 8) + 7,    // (CLDR 26, ICU-541)
  99     UAMEASUNIT_AREA_SQUARE_YARD      = (2 << 8) + 8,    // (CLDR 26, ICU-541)
 100     //
 101     // (3 reserved for currency, handled separately)
 102     //
 103     UAMEASUNIT_DURATION_YEAR        = (4 << 8) + 0,
 104     UAMEASUNIT_DURATION_MONTH       = (4 << 8) + 1,
 105     UAMEASUNIT_DURATION_WEEK        = (4 << 8) + 2,
 106     UAMEASUNIT_DURATION_DAY         = (4 << 8) + 3,
 107     UAMEASUNIT_DURATION_HOUR        = (4 << 8) + 4,
 108     UAMEASUNIT_DURATION_MINUTE      = (4 << 8) + 5,
 109     UAMEASUNIT_DURATION_SECOND      = (4 << 8) + 6,
 110     UAMEASUNIT_DURATION_MILLISECOND = (4 << 8) + 7,
 111     UAMEASUNIT_DURATION_MICROSECOND = (4 << 8) + 8,     // (CLDR 26, ICU-541)
 112     UAMEASUNIT_DURATION_NANOSECOND  = (4 << 8) + 9,     // (CLDR 26, ICU-541)
 113     UAMEASUNIT_DURATION_CENTURY     = (4 << 8) + 10,    // (CLDR 28, ICU-561.3)
 114     //
 115     UAMEASUNIT_LENGTH_METER         = (5 << 8) + 0,
 116     UAMEASUNIT_LENGTH_CENTIMETER    = (5 << 8) + 1,
 117     UAMEASUNIT_LENGTH_KILOMETER     = (5 << 8) + 2,
 118     UAMEASUNIT_LENGTH_MILLIMETER    = (5 << 8) + 3,
 119     UAMEASUNIT_LENGTH_PICOMETER     = (5 << 8) + 4,
 120     UAMEASUNIT_LENGTH_FOOT          = (5 << 8) + 5,
 121     UAMEASUNIT_LENGTH_INCH          = (5 << 8) + 6,
 122     UAMEASUNIT_LENGTH_MILE          = (5 << 8) + 7,
 123     UAMEASUNIT_LENGTH_YARD          = (5 << 8) + 8,
 124     UAMEASUNIT_LENGTH_LIGHT_YEAR    = (5 << 8) + 9,
 125     UAMEASUNIT_LENGTH_DECIMETER     = (5 << 8) + 10,    // (CLDR 26, ICU-541)
 126     UAMEASUNIT_LENGTH_MICROMETER    = (5 << 8) + 11,    // (CLDR 26, ICU-541)
 127     UAMEASUNIT_LENGTH_NANOMETER     = (5 << 8) + 12,    // (CLDR 26, ICU-541)
 128     UAMEASUNIT_LENGTH_NAUTICAL_MILE = (5 << 8) + 13,    // (CLDR 26, ICU-541)
 129     UAMEASUNIT_LENGTH_FATHOM        = (5 << 8) + 14,    // (CLDR 26, ICU-541)
 130     UAMEASUNIT_LENGTH_FURLONG       = (5 << 8) + 15,    // (CLDR 26, ICU-541)
 131     UAMEASUNIT_LENGTH_ASTRONOMICAL_UNIT = (5 << 8) + 16, // (CLDR 26, ICU-541)
 132     UAMEASUNIT_LENGTH_PARSEC        = (5 << 8) + 17,    // (CLDR 26, ICU-541)
 133     UAMEASUNIT_LENGTH_MILE_SCANDINAVIAN = (5 << 8) + 18, // (CLDR 28, ICU-561.3)
 134     UAMEASUNIT_LENGTH_POINT         = (5 << 8) + 19,    // (CLDR 31, ICU-590)
 135     //
 136     UAMEASUNIT_MASS_GRAM            = (6 << 8) + 0,
 137     UAMEASUNIT_MASS_KILOGRAM        = (6 << 8) + 1,
 138     UAMEASUNIT_MASS_OUNCE           = (6 << 8) + 2,
 139     UAMEASUNIT_MASS_POUND           = (6 << 8) + 3,
 140     UAMEASUNIT_MASS_STONE           = (6 << 8) + 4,     // = 14 pounds / 6.35 kg, abbr "st", used in UK/Ireland for body weight (CLDR 26)
 141     UAMEASUNIT_MASS_MICROGRAM       = (6 << 8) + 5,     // (CLDR 26, ICU-541)
 142     UAMEASUNIT_MASS_MILLIGRAM       = (6 << 8) + 6,     // (CLDR 26, ICU-541)
 143     UAMEASUNIT_MASS_METRIC_TON      = (6 << 8) + 7,     // = "tonne" (CLDR 26, ICU-541)
 144     UAMEASUNIT_MASS_TON             = (6 << 8) + 8,     // = "short ton", U.S. ton (CLDR 26, ICU-541)
 145     UAMEASUNIT_MASS_CARAT           = (6 << 8) + 9,     // (CLDR 26, ICU-541)
 146     UAMEASUNIT_MASS_OUNCE_TROY      = (6 << 8) + 10,    // (CLDR 26, ICU-541)
 147     //
 148     UAMEASUNIT_POWER_WATT           = (7 << 8) + 0,
 149     UAMEASUNIT_POWER_KILOWATT       = (7 << 8) + 1,
 150     UAMEASUNIT_POWER_HORSEPOWER     = (7 << 8) + 2,
 151     UAMEASUNIT_POWER_MILLIWATT      = (7 << 8) + 3,     // (CLDR 26, ICU-541)
 152     UAMEASUNIT_POWER_MEGAWATT       = (7 << 8) + 4,     // (CLDR 26, ICU-541)
 153     UAMEASUNIT_POWER_GIGAWATT       = (7 << 8) + 5,     // (CLDR 26, ICU-541)
 154     //
 155     UAMEASUNIT_PRESSURE_HECTOPASCAL = (8 << 8) + 0,
 156     UAMEASUNIT_PRESSURE_INCH_HG     = (8 << 8) + 1,
 157     UAMEASUNIT_PRESSURE_MILLIBAR    = (8 << 8) + 2,
 158     UAMEASUNIT_PRESSURE_MILLIMETER_OF_MERCURY = (8 << 8) + 3, // (CLDR 26, ICU-541)
 159     UAMEASUNIT_PRESSURE_POUND_PER_SQUARE_INCH = (8 << 8) + 4, // (CLDR 26, ICU-541)
 160     //
 161     UAMEASUNIT_SPEED_METER_PER_SECOND   = (9 << 8) + 0,
 162     UAMEASUNIT_SPEED_KILOMETER_PER_HOUR = (9 << 8) + 1,
 163     UAMEASUNIT_SPEED_MILE_PER_HOUR      = (9 << 8) + 2,
 164     UAMEASUNIT_SPEED_KNOT               = (9 << 8) + 3,     // (CLDR 28, ICU-561.3)
 165     //
 166     UAMEASUNIT_TEMPERATURE_CELSIUS      = (10 << 8) + 0,
 167     UAMEASUNIT_TEMPERATURE_FAHRENHEIT   = (10 << 8) + 1,
 168     UAMEASUNIT_TEMPERATURE_KELVIN       = (10 << 8) + 2,    // (CLDR 26, ICU-541)
 169     UAMEASUNIT_TEMPERATURE_GENERIC      = (10 << 8) + 3,    // (CLDR 27, ICU-550.2)
 170     //
 171     UAMEASUNIT_VOLUME_LITER             = (11 << 8) + 0,
 172     UAMEASUNIT_VOLUME_CUBIC_KILOMETER   = (11 << 8) + 1,
 173     UAMEASUNIT_VOLUME_CUBIC_MILE        = (11 << 8) + 2,
 174     UAMEASUNIT_VOLUME_MILLILITER        = (11 << 8) + 3,    // (CLDR 26, ICU-541)
 175     UAMEASUNIT_VOLUME_CENTILITER        = (11 << 8) + 4,    // (CLDR 26, ICU-541)
 176     UAMEASUNIT_VOLUME_DECILITER         = (11 << 8) + 5,    // (CLDR 26, ICU-541)
 177     UAMEASUNIT_VOLUME_HECTOLITER        = (11 << 8) + 6,    // (CLDR 26, ICU-541)
 178     UAMEASUNIT_VOLUME_MEGALITER         = (11 << 8) + 7,    // (CLDR 26, ICU-541)
 179     UAMEASUNIT_VOLUME_CUBIC_CENTIMETER  = (11 << 8) + 8,    // (CLDR 26, ICU-541)
 180     UAMEASUNIT_VOLUME_CUBIC_METER       = (11 << 8) + 9,    // (CLDR 26, ICU-541)
 181     UAMEASUNIT_VOLUME_CUBIC_INCH        = (11 << 8) + 10,   // (CLDR 26, ICU-541)
 182     UAMEASUNIT_VOLUME_CUBIC_FOOT        = (11 << 8) + 11,   // (CLDR 26, ICU-541)
 183     UAMEASUNIT_VOLUME_CUBIC_YARD        = (11 << 8) + 12,   // (CLDR 26, ICU-541)
 184     UAMEASUNIT_VOLUME_ACRE_FOOT         = (11 << 8) + 13,   // (CLDR 26, ICU-541)
 185     UAMEASUNIT_VOLUME_BUSHEL            = (11 << 8) + 14,   // (CLDR 26, ICU-541)
 186     UAMEASUNIT_VOLUME_TEASPOON          = (11 << 8) + 15,   // (CLDR 26, ICU-541)
 187     UAMEASUNIT_VOLUME_TABLESPOON        = (11 << 8) + 16,   // (CLDR 26, ICU-541)
 188     UAMEASUNIT_VOLUME_FLUID_OUNCE       = (11 << 8) + 17,   // (CLDR 26, ICU-541)
 189     UAMEASUNIT_VOLUME_CUP               = (11 << 8) + 18,   // (CLDR 26, ICU-541)
 190     UAMEASUNIT_VOLUME_PINT              = (11 << 8) + 19,   // (CLDR 26, ICU-541)
 191     UAMEASUNIT_VOLUME_QUART             = (11 << 8) + 20,   // (CLDR 26, ICU-541)
 192     UAMEASUNIT_VOLUME_GALLON            = (11 << 8) + 21,   // (CLDR 26, ICU-541)
 193     UAMEASUNIT_VOLUME_CUP_METRIC        = (11 << 8) + 22,   // (CLDR 28, ICU-561.3)
 194     UAMEASUNIT_VOLUME_PINT_METRIC       = (11 << 8) + 23,   // (CLDR 28, ICU-561.3)
 195     UAMEASUNIT_VOLUME_GALLON_IMPERIAL   = (11 << 8) + 24,   // (CLDR 29, ICU-561.8+)
 196     //
 197     // new categories/values in CLDR 26
 198     //
 199     UAMEASUNIT_ENERGY_JOULE             = (12 << 8) + 2,
 200     UAMEASUNIT_ENERGY_KILOJOULE         = (12 << 8) + 4,
 201     UAMEASUNIT_ENERGY_CALORIE           = (12 << 8) + 0,    // chemistry "calories", abbr "cal"
 202     UAMEASUNIT_ENERGY_KILOCALORIE       = (12 << 8) + 3,    // kilocalories in general (chemistry, food), abbr "kcal"
 203     UAMEASUNIT_ENERGY_FOODCALORIE       = (12 << 8) + 1,    // kilocalories specifically for food; in US/UK/? "Calories" abbr "C", elsewhere same as "kcal"
 204     UAMEASUNIT_ENERGY_KILOWATT_HOUR     = (12 << 8) + 5,    // (ICU-541)
 205     //
 206     // new categories/values in CLDR 26 & ICU-541
 207     //
 208     UAMEASUNIT_CONSUMPTION_LITER_PER_KILOMETER = (13 << 8) + 0,
 209     UAMEASUNIT_CONSUMPTION_MILE_PER_GALLON     = (13 << 8) + 1,
 210     UAMEASUNIT_CONSUMPTION_LITER_PER_100_KILOMETERs = (13 << 8) + 2, // (CLDR 28, ICU-561.3)
 211     UAMEASUNIT_CONSUMPTION_MILE_PER_GALLON_IMPERIAL = (13 << 8) + 3, // (CLDR 29, ICU-561.8+)
 212     //
 213     UAMEASUNIT_DIGITAL_BIT              = (14 << 8) + 0,
 214     UAMEASUNIT_DIGITAL_BYTE             = (14 << 8) + 1,
 215     UAMEASUNIT_DIGITAL_GIGABIT          = (14 << 8) + 2,
 216     UAMEASUNIT_DIGITAL_GIGABYTE         = (14 << 8) + 3,
 217     UAMEASUNIT_DIGITAL_KILOBIT          = (14 << 8) + 4,
 218     UAMEASUNIT_DIGITAL_KILOBYTE         = (14 << 8) + 5,
 219     UAMEASUNIT_DIGITAL_MEGABIT          = (14 << 8) + 6,
 220     UAMEASUNIT_DIGITAL_MEGABYTE         = (14 << 8) + 7,
 221     UAMEASUNIT_DIGITAL_TERABIT          = (14 << 8) + 8,
 222     UAMEASUNIT_DIGITAL_TERABYTE         = (14 << 8) + 9,
 223     //
 224     UAMEASUNIT_ELECTRIC_AMPERE          = (15 << 8) + 0,
 225     UAMEASUNIT_ELECTRIC_MILLIAMPERE     = (15 << 8) + 1,
 226     UAMEASUNIT_ELECTRIC_OHM             = (15 << 8) + 2,
 227     UAMEASUNIT_ELECTRIC_VOLT            = (15 << 8) + 3,
 228     //
 229     UAMEASUNIT_FREQUENCY_HERTZ          = (16 << 8) + 0,
 230     UAMEASUNIT_FREQUENCY_KILOHERTZ      = (16 << 8) + 1,
 231     UAMEASUNIT_FREQUENCY_MEGAHERTZ      = (16 << 8) + 2,
 232     UAMEASUNIT_FREQUENCY_GIGAHERTZ      = (16 << 8) + 3,
 233     //
 234     UAMEASUNIT_LIGHT_LUX                = (17 << 8) + 0,
 235     //
 236     // new categories/values in CLDR 29, ICU-561.8+
 237     //
 238     UAMEASUNIT_CONCENTRATION_KARAT      = (18 << 8) + 0,    // (CLDR 29, ICU-561.8+)
 239     UAMEASUNIT_CONCENTRATION_MILLIGRAM_PER_DECILITER = (18 << 8) + 1, // (CLDR 29, ICU-561.8+)
 240     UAMEASUNIT_CONCENTRATION_MILLIMOLE_PER_LITER = (18 << 8) + 2, // (CLDR 29, ICU-561.8+)
 241     UAMEASUNIT_CONCENTRATION_PART_PER_MILLION = (18 << 8) + 3, // (CLDR 29, ICU-561.8+)
 242     //
 243 } UAMeasureUnit;
 244
 245 enum {
 246     // Mask bit set in UFieldPosition, in addition to a UAMeasureUnit value,
 247     // to indicate the numeric portion of the field corresponding to the UAMeasureUnit.
 248     UAMEASFMT_NUMERIC_FIELD_FLAG = (1 << 30)
 249 };
 250
 251 /**
 252  * Structure that combines value and UAMeasureUnit,
 253  * for use with uameasfmt_formatMultiple to specify a
 254  * list of value/unit combinations to format.
 255  * @draft ICU 54
 256  */
 257 typedef struct UAMeasure {
 258     double          value;
 259     UAMeasureUnit   unit;
 260 } UAMeasure;
 261
 262
 263 /**
 264  * Open a new UAMeasureFormat object for a given locale using the specified width,
 265  * along with a number formatter (if desired) to override the default formatter
 266  * that would be used for the numeric part of the unit in uameasfmt_format, or the
 267  * numeric part of the *last unit* (only) in uameasfmt_formatMultiple. The default
 268  * formatter typically rounds toward 0 and has a minimum of 0 fraction digits and a
 269  * maximum of 3 fraction digits (i.e. it will show as many decimal places as
 270  * necessary up to 3, without showing trailing 0s). An alternate number formatter
 271  * can be used to produce (e.g.) "37.0 mins" instead of "37 mins", or
 272  * "5 hours, 37.2 minutes" instead of "5 hours, 37.217 minutes".
 273  *
 274  * @param locale
 275  *          The locale
 276  * @param style
 277  *          The width - wide, short, narrow, etc.
 278  * @param nfToAdopt
 279  *          A number formatter to set for this UAMeasureFormat object (instead of
 280  *          the default decimal formatter). Ownership of this UNumberFormat object
 281  *          will pass to the UAMeasureFormat object (the UAMeasureFormat adopts the
 282  *          UNumberFormat), which becomes responsible for closing it. If the caller
 283  *          wishes to retain ownership of the UNumberFormat object, the caller must
 284  *          clone it (with unum_clone) and pass the clone to
 285  *          uatmufmt_openWithNumberFormat. May be NULL to use the default decimal
 286  *          formatter.
 287  * @param status
 288  *          A pointer to a UErrorCode to receive any errors.
 289  * @return
 290  *          A pointer to a UAMeasureFormat object for the specified locale,
 291  *          or NULL if an error occurred.
 292  * @draft ICU 54
 293  */
 294 U_DRAFT UAMeasureFormat* U_EXPORT2
 295 uameasfmt_open( const char*          locale,
 296                 UAMeasureFormatWidth width,
 297                 UNumberFormat*       nfToAdopt,
 298                 UErrorCode*          status );
 299
 300 /**
 301  * Close a UAMeasureFormat object. Once closed it may no longer be used.
 302  * @param measfmt
 303  *            The UATimeUnitFormat object to close.
 304  * @draft ICU 54
 305  */
 306 U_DRAFT void U_EXPORT2
 307 uameasfmt_close(UAMeasureFormat *measfmt);
 308
 309 #if U_SHOW_CPLUSPLUS_API
 310
 311 U_NAMESPACE_BEGIN
 312
 313 /**
 314  * \class LocalUAMeasureFormatPointer
 315  * "Smart pointer" class, closes a UAMeasureFormat via uameasfmt_close().
 316  * For most methods see the LocalPointerBase base class.
 317  *
 318  * @see LocalPointerBase
 319  * @see LocalPointer
 320  * @draft ICU 54
 321  */
 322 U_DEFINE_LOCAL_OPEN_POINTER(LocalUAMeasureFormatPointer, UAMeasureFormat, uameasfmt_close);
 323
 324 U_NAMESPACE_END
 325
 326 #endif // U_SHOW_CPLUSPLUS_API
 327
 328
 329 /**
 330  * Format a value like 1.0 and a field like UAMEASUNIT_DURATION_MINUTE to e.g. "1.0 minutes".
 331  *
 332  * @param measfmt
 333  *          The UAMeasureFormat object specifying the format conventions.
 334  * @param value
 335  *          The numeric value to format
 336  * @param unit
 337  *          The unit to format with the specified numeric value
 338  * @param result
 339  *          A pointer to a buffer to receive the formatted result.
 340  * @param resultCapacity
 341  *          The maximum size of result.
 342  * @param status
 343  *          A pointer to a UErrorCode to receive any errors. In case of error status,
 344  *          the contents of result are undefined.
 345  * @return
 346  *          The length of the formatted result; may be greater than resultCapacity,
 347  *          in which case an error is returned.
 348  * @draft ICU 54
 349  */
 350 U_DRAFT int32_t U_EXPORT2
 351 uameasfmt_format( const UAMeasureFormat* measfmt,
 352                   double            value,
 353                   UAMeasureUnit     unit,
 354                   UChar*            result,
 355                   int32_t           resultCapacity,
 356                   UErrorCode*       status );
 357
 358 /**
 359  * Format a value like 1.0 and a field like UAMEASUNIT_DURATION_MINUTE to e.g. "1.0 minutes",
 360  * and get the position in the formatted result for certain types for fields.
 361  *
 362  * @param measfmt
 363  *          The UAMeasureFormat object specifying the format conventions.
 364  * @param value
 365  *          The numeric value to format
 366  * @param unit
 367  *          The unit to format with the specified numeric value
 368  * @param result
 369  *          A pointer to a buffer to receive the formatted result.
 370  * @param resultCapacity
 371  *          The maximum size of result.
 372  * @param pos
 373  *          A pointer to a UFieldPosition. On input, pos->field is read; this should
 374  *          be a value from the UNumberFormatFields enum in unum.h. On output,
 375  *          pos->beginIndex and pos->endIndex indicate the beginning and ending offsets
 376  *          of that field in the formatted output, if relevant. This parameter may be
 377  *          NULL if no position information is desired.
 378  * @param status
 379  *          A pointer to a UErrorCode to receive any errors. In case of error status,
 380  *          the contents of result are undefined.
 381  * @return
 382  *          The length of the formatted result; may be greater than resultCapacity,
 383  *          in which case an error is returned.
 384  * @draft ICU 54
 385  */
 386 U_DRAFT int32_t U_EXPORT2
 387 uameasfmt_formatGetPosition( const UAMeasureFormat* measfmt,
 388                             double            value,
 389                             UAMeasureUnit     unit,
 390                             UChar*            result,
 391                             int32_t           resultCapacity,
 392                             UFieldPosition*   pos,
 393                             UErrorCode*       status );
 394
 395 /**
 396  * Format a list of value and unit combinations, using locale-appropriate
 397  * conventions for the list. Each combination is represented by a UAMeasure
 398  * that combines a value and unit, such as 5.3 + UAMEASUNIT_DURATION_HOUR or
 399  * 37.2 + UAMEASUNIT_DURATION_MINUTE. For all except the last UAMeasure in the
 400  * list, the numeric part will be formatted using the default formatter (zero
 401  * decimal places, rounds toward 0); for the last UAMeasure, the default may
 402  * be overriden by passing a number formatter in uameasfmt_open. The result
 403  * can thus be something like "5 hours, 37.2 minutes" or "5 hrs, 37.2 mins".
 404  *
 405  * @param measfmt
 406  *            The UAMeasureFormat object specifying the format conventions.
 407  * @param measures
 408  *            A list of UAMeasure structs each specifying a numeric value
 409  *            and a UAMeasureUnit.
 410  * @param measureCount
 411  *            The count of UAMeasureUnits in measures. Currently this has a limit of 8.
 412  * @param result
 413  *            A pointer to a buffer to receive the formatted result.
 414  * @param resultCapacity
 415  *            The maximum size of result.
 416  * @param status
 417  *            A pointer to a UErrorCode to receive any errors. In case of error status,
 418  *            the contents of result are undefined.
 419  * @return
 420  *            The length of the formatted result; may be greater than resultCapacity,
 421  *            in which case an error is returned.
 422  * @draft ICU 54
 423  */
 424 U_DRAFT int32_t U_EXPORT2
 425 uameasfmt_formatMultiple( const UAMeasureFormat* measfmt,
 426                           const UAMeasure*  measures,
 427                           int32_t           measureCount,
 428                           UChar*            result,
 429                           int32_t           resultCapacity,
 430                           UErrorCode*       status );
 431
 432 /**
 433  * Format a list of value and unit combinations, using locale-appropriate
 434  * conventions for the list. This has the same format behavior as
 435  * uameasfmt_formatMultiple but adds the fpositer parameter.
 436  *
 437  * @param measfmt
 438  *            The UAMeasureFormat object specifying the format conventions.
 439  * @param measures
 440  *            A list of UAMeasure structs each specifying a numeric value
 441  *            and a UAMeasureUnit.
 442  * @param measureCount
 443  *            The count of UAMeasureUnits in measures. Currently this has a limit of 8.
 444  * @param result
 445  *            A pointer to a buffer to receive the formatted result.
 446  * @param resultCapacity
 447  *            The maximum size of result.
 448  * @param fpositer
 449  *            A pointer to a UFieldPositionIterator created by ufieldpositer_open
 450  *            (may be NULL if field position information is not needed). Any
 451  *            iteration information already present in the UFieldPositionIterator
 452  *            will be deleted, and the iterator will be reset to apply to the
 453  *            fields in the formatted string created by this function call. In the
 454  *            the formatted result, each unit field (unit name or symbol plus any
 455  *            associated numeric value) will correspond to one or two results from
 456  *            ufieldpositer_next. The first result returns a UAMeasureUnit value and
 457  *            indicates the begin and end index for the complete field. If there is
 458  *            a numeric value contained in the field, then a subsequent call to
 459  *            ufieldpositer_next returns a value with UAMEASFMT_NUMERIC_FIELD_FLAG
 460  *            set and the same UAMeasureUnit value in the low-order bits, and
 461  *            indicates the begin and end index for the numeric portion of the field.
 462  *            For example with the string "3 hours, dualminute" the sequence of
 463  *            calls to ufieldpositer_next would result in:
 464  *            (1) return UAMEASUNIT_DURATION_HOUR, begin index 0, end index 7
 465  *            (2) return UAMEASUNIT_DURATION_HOUR | UAMEASFMT_NUMERIC_FIELD_FLAG, begin index 0, end index 1
 466  *            (3) return UAMEASUNIT_DURATION_MINUTE, begin index 9, end index 19
 467  *            (4) return -1 to indicate end of interation
 468  * @param status
 469  *            A pointer to a UErrorCode to receive any errors. In case of error status,
 470  *            the contents of result are undefined.
 471  * @return
 472  *            The length of the formatted result; may be greater than resultCapacity,
 473  *            in which case an error is returned.
 474  * @draft ICU 58
 475  */
 476 U_DRAFT int32_t U_EXPORT2
 477 uameasfmt_formatMultipleForFields( const UAMeasureFormat* measfmt,
 478                                    const UAMeasure*  measures,
 479                                    int32_t           measureCount,
 480                                    UChar*            result,
 481                                    int32_t           resultCapacity,
 482                                    UFieldPositionIterator* fpositer,
 483                                    UErrorCode*       status );
 484
 485 /**
 486  * Get the display name for a unit, such as "minutes" or "kilometers".
 487  *
 488  * @param measfmt
 489  *          The UAMeasureFormat object specifying the format conventions.
 490  * @param unit
 491  *          The unit whose localized name to get
 492  * @param result
 493  *          A pointer to a buffer to receive the name.
 494  * @param resultCapacity
 495  *          The maximum size of result.
 496  * @param status
 497  *          A pointer to a UErrorCode to receive any errors. In case of error status,
 498  *          the contents of result are undefined.
 499  * @return
 500  *          The length of the name; may be greater than resultCapacity,
 501  *          in which case an error is returned.
 502  * @draft ICU 57
 503  */
 504 U_DRAFT int32_t U_EXPORT2
 505 uameasfmt_getUnitName( const UAMeasureFormat* measfmt,
 506                        UAMeasureUnit unit,
 507                        UChar* result,
 508                        int32_t resultCapacity,
 509                        UErrorCode* status );
 510
 511 /**
 512  * Constants for unit display name list styles
 513  * @draft ICU 57
 514  */
 515 typedef enum UAMeasureNameListStyle {
 516     /**
 517      * Use standard (linguistic) list style, the same for all unit widths; e.g.
 518      *   wide:    "hours, minutes, and seconds"
 519      *   short:   "hours, min, and secs"
 520      *   narrow:  "hour, min, and sec"
 521      * @draft ICU 57
 522      */
 523     UAMEASNAME_LIST_STANDARD,
 524
 525     /**
 526       * Use the same list style as used by the formatted units, depends on width; e.g.
 527      *   wide:    "hours, minutes, seconds"
 528      *   short:   "hours, min, secs"
 529      *   narrow:  "hour min sec"
 530      * @draft ICU 57
 531      */
 532     UAMEASNAME_LIST_MATCHUNITS,
 533 } UAMeasureNameListStyle;
 534
 535 /**
 536  * Get a list of display names for multiple units
 537  *
 538  * @param measfmt
 539  *          The UAMeasureFormat object specifying the format conventions.
 540  * @param units
 541  *          The array of unit types whose names to get.
 542  * @param unitCount
 543  *          The number of unit types in the units array.
 544  * @param listStyle
 545  *          The list style used for combining the unit names.
 546  * @param result
 547  *          A pointer to a buffer to receive the list of names.
 548  * @param resultCapacity
 549  *          The maximum size of result.
 550  * @param status
 551  *          A pointer to a UErrorCode to receive any errors. In case of error status,
 552  *          the contents of result are undefined.
 553  * @return
 554  *          The length of the list of names; may be greater than resultCapacity,
 555  *          in which case an error is returned.
 556  * @draft ICU 57
 557  */
 558 U_DRAFT int32_t U_EXPORT2
 559 uameasfmt_getMultipleUnitNames( const UAMeasureFormat* measfmt,
 560                                 const UAMeasureUnit* units,
 561                                 int32_t unitCount,
 562                                 UAMeasureNameListStyle listStyle,
 563                                 UChar* result,
 564                                 int32_t resultCapacity,
 565                                 UErrorCode* status );
 566
 567 /**
 568  * Get the units used for a particular usage. This low-level function depends
 569  * one some knowledge of the relevant CLDR keys. After more experience with
 570  * usage, enums for relevant usage values may be created.
 571  *
 572  * This is sensitive to two locale keywords.
 573  * If the "ms" keyword is present, then the measurement system specified by its
 574  * value is used (except for certain categories like duration and concentr).
 575  * Else if the "rg" keyword is present, then the region specified by its value
 576  * determines the unit usage.
 577  * Else if the locale has a region subtag, it determines the unit usage.
 578  * Otherwise the likely region for the language determines the usage.
 579  *
 580  * @param locale
 581  *          The locale, which determines the usage as specified above.
 582  * @param category
 583  *          A string representing the CLDR category key for the desired usage,
 584  *          such as "length" or "mass". Must not be NULL.
 585  * @param usage
 586  *          A string representing the CLDR usage subkey for the desired usage,
 587  *          such as "person", "person-small" (for infants), "person-informal"
 588  *          (for conversational/informal usage), etc. To get the general unit
 589  *          for the category (not for a specific usage), this may be NULL, or
 590  *          may be just "large" or "small" to indicate a variant of the general
 591  *          unit for larger or smaller ranges than normal.
 592  * @param units
 593  *          Array to be filled in with UAMeasureUnit values; the size is
 594  *          specified by unitsCapacity (which in general should be at least 3).
 595  *          The number of array elements actually filled in is indicated by
 596  *          the return value; if no error status is set then this will be
 597  *          non-zero.
 598  *
 599  *          If the return value is positive then units represents an ordered
 600  *          list of one or more units that should be used in combination for
 601  *          the desired usage (e.g. the values UAMEASUNIT_LENGTH_FOOT,
 602  *          UAMEASUNIT_LENGTH_INCH to indicate a height expressed as a
 603  *          combination of feet and inches, or just UAMEASUNIT_LENGTH_CENTIMETER
 604  *          to indicate height expressed in centimeters alone).
 605  *
 606  *          Negative return values may be used for future uses (such as
 607  *          indicating an X-per-Y relationship among the returned units).
 608  *
 609  *          The units parameter may be NULL if unitsCapacity is 0, for
 610  *          pre-flighting (i.e. to determine the size of the units array that
 611  *          woud be required for the given category and usage).
 612  * @param unitsCapacity
 613  *          The maximum capacity of the passed-in units array.
 614  * @param status
 615  *          A pointer to a UErrorCode to receive any errors. In case of error status,
 616  *          the contents of result are undefined.
 617  * @return
 618  *          Positive values indicate the number of units require for the usage;
 619  *          may be greater than resultCapacity, in which case an error is returned.
 620  *          If no error, than this number of units are actually provided in the
 621  *          units array. Negative return values are reserved for future uses.
 622  * @draft ICU 57
 623  */
 624 U_DRAFT int32_t U_EXPORT2
 625 uameasfmt_getUnitsForUsage( const char*     locale,
 626                             const char*     category,
 627                             const char*     usage,
 628                             UAMeasureUnit*  units,
 629                             int32_t         unitsCapacity,
 630                             UErrorCode*     status );
 631
 632 /**
 633  * Get the (non-localized) category name for a unit. For example, for
 634  * UAMEASUNIT_VOLUME_LITER, returns "volume".
 635  *
 636  * @param unit
 637  *          The unit whose category name to get
 638  * @param status
 639  *          A pointer to a UErrorCode to receive any errors. In case of error status,
 640  *          the return value is undefined.
 641  * @return
 642  *          Pointer to a zero-terminated string giving the
 643  *          (non-localized) category name.
 644  * @draft ICU 58
 645  */
 646 U_DRAFT const char * U_EXPORT2
 647 uameasfmt_getUnitCategory(UAMeasureUnit unit,
 648                           UErrorCode* status );
 649
 650
 651 #endif /* U_HIDE_DRAFT_API */
 652 #endif /* #if !UCONFIG_NO_FORMATTING */
 653
 654 #endif /* #ifndef UAMEASUREFORMAT_H */