icuSources/i18n/unicode/uameasureformat.h

   1 /*
   2 *****************************************************************************************
   3 * Copyright (C) 2014-2015 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
  19 /**
  20  * \file
  21  * \brief C API: Format combinations of measurement units and numeric values.
  22  *
  23  * This is a somewhat temporary Apple-specific wrapper for using C++ MeasureFormat
  24  * to format Measure objects, until the official ICU C API is available.
  25  */
  26
  27 /**
  28  * Opaque UAMeasureFormat object for use in C programs.
  29  * @draft ICU 53
  30  */
  31 struct UAMeasureFormat;
  32 typedef struct UAMeasureFormat UAMeasureFormat;  /**< C typedef for struct UAMeasureFormat. @draft ICU 53 */
  33
  34 /**
  35  * Constants for various widths.
  36  * @draft ICU 53
  37  */
  38 typedef enum UAMeasureFormatWidth {
  39     /**
  40      * Full unit names, e.g. "5 hours, 37 minutes"
  41      * @draft ICU 53
  42      */
  43     UAMEASFMT_WIDTH_WIDE,
  44
  45     /**
  46      * Abbreviated unit names, e.g. "5 hrs, 37 mins"
  47      * @draft ICU 53
  48      */
  49     UAMEASFMT_WIDTH_SHORT,
  50
  51     /**
  52      * Use unit symbols if possible, e.g. "5 h, 37 m"
  53      * @draft ICU 53
  54      */
  55     UAMEASFMT_WIDTH_NARROW,
  56
  57     /**
  58      * Completely omit unit designatins if possible, e.g. "5:37"
  59      * @draft ICU 53
  60      */
  61     UAMEASFMT_WIDTH_NUMERIC,
  62
  63     /**
  64      * Count of values in this enum.
  65      * @draft ICU 53
  66      */
  67     UAMEASFMT_WIDTH_COUNT
  68 } UAMeasureFormatWidth;
  69
  70 /**
  71  * Measurement units
  72  * @draft ICU 54
  73  */
  74 typedef enum UAMeasureUnit {
  75     UAMEASUNIT_ACCELERATION_G_FORCE = (0 << 8) + 0,
  76     UAMEASUNIT_ACCELERATION_METER_PER_SECOND_SQUARED = (0 << 8) + 1, // (CLDR 26, ICU-541)
  77     //
  78     UAMEASUNIT_ANGLE_DEGREE         = (1 << 8) + 0,
  79     UAMEASUNIT_ANGLE_ARC_MINUTE     = (1 << 8) + 1,
  80     UAMEASUNIT_ANGLE_ARC_SECOND     = (1 << 8) + 2,
  81     UAMEASUNIT_ANGLE_RADIAN         = (1 << 8) + 3,     // (CLDR 26, ICU-541)
  82     //
  83     UAMEASUNIT_AREA_SQUARE_METER     = (2 << 8) + 0,
  84     UAMEASUNIT_AREA_SQUARE_KILOMETER = (2 << 8) + 1,
  85     UAMEASUNIT_AREA_SQUARE_FOOT      = (2 << 8) + 2,
  86     UAMEASUNIT_AREA_SQUARE_MILE      = (2 << 8) + 3,
  87     UAMEASUNIT_AREA_ACRE             = (2 << 8) + 4,
  88     UAMEASUNIT_AREA_HECTARE          = (2 << 8) + 5,
  89     UAMEASUNIT_AREA_SQUARE_CENTIMETER = (2 << 8) + 6,   // (CLDR 26, ICU-541)
  90     UAMEASUNIT_AREA_SQUARE_INCH      = (2 << 8) + 7,    // (CLDR 26, ICU-541)
  91     UAMEASUNIT_AREA_SQUARE_YARD      = (2 << 8) + 8,    // (CLDR 26, ICU-541)
  92     //
  93     // (3 reserved for currency, handled separately)
  94     //
  95     UAMEASUNIT_DURATION_YEAR        = (4 << 8) + 0,
  96     UAMEASUNIT_DURATION_MONTH       = (4 << 8) + 1,
  97     UAMEASUNIT_DURATION_WEEK        = (4 << 8) + 2,
  98     UAMEASUNIT_DURATION_DAY         = (4 << 8) + 3,
  99     UAMEASUNIT_DURATION_HOUR        = (4 << 8) + 4,
 100     UAMEASUNIT_DURATION_MINUTE      = (4 << 8) + 5,
 101     UAMEASUNIT_DURATION_SECOND      = (4 << 8) + 6,
 102     UAMEASUNIT_DURATION_MILLISECOND = (4 << 8) + 7,
 103     UAMEASUNIT_DURATION_MICROSECOND = (4 << 8) + 8,     // (CLDR 26, ICU-541)
 104     UAMEASUNIT_DURATION_NANOSECOND  = (4 << 8) + 9,     // (CLDR 26, ICU-541)
 105     //
 106     UAMEASUNIT_LENGTH_METER         = (5 << 8) + 0,
 107     UAMEASUNIT_LENGTH_CENTIMETER    = (5 << 8) + 1,
 108     UAMEASUNIT_LENGTH_KILOMETER     = (5 << 8) + 2,
 109     UAMEASUNIT_LENGTH_MILLIMETER    = (5 << 8) + 3,
 110     UAMEASUNIT_LENGTH_PICOMETER     = (5 << 8) + 4,
 111     UAMEASUNIT_LENGTH_FOOT          = (5 << 8) + 5,
 112     UAMEASUNIT_LENGTH_INCH          = (5 << 8) + 6,
 113     UAMEASUNIT_LENGTH_MILE          = (5 << 8) + 7,
 114     UAMEASUNIT_LENGTH_YARD          = (5 << 8) + 8,
 115     UAMEASUNIT_LENGTH_LIGHT_YEAR    = (5 << 8) + 9,
 116     UAMEASUNIT_LENGTH_DECIMETER     = (5 << 8) + 10,    // (CLDR 26, ICU-541)
 117     UAMEASUNIT_LENGTH_MICROMETER    = (5 << 8) + 11,    // (CLDR 26, ICU-541)
 118     UAMEASUNIT_LENGTH_NANOMETER     = (5 << 8) + 12,    // (CLDR 26, ICU-541)
 119     UAMEASUNIT_LENGTH_NAUTICAL_MILE = (5 << 8) + 13,    // (CLDR 26, ICU-541)
 120     UAMEASUNIT_LENGTH_FATHOM        = (5 << 8) + 14,    // (CLDR 26, ICU-541)
 121     UAMEASUNIT_LENGTH_FURLONG       = (5 << 8) + 15,    // (CLDR 26, ICU-541)
 122     UAMEASUNIT_LENGTH_ASTRONOMICAL_UNIT = (5 << 8) + 16, // (CLDR 26, ICU-541)
 123     UAMEASUNIT_LENGTH_PARSEC        = (5 << 8) + 17,    // (CLDR 26, ICU-541)
 124     //
 125     UAMEASUNIT_MASS_GRAM            = (6 << 8) + 0,
 126     UAMEASUNIT_MASS_KILOGRAM        = (6 << 8) + 1,
 127     UAMEASUNIT_MASS_OUNCE           = (6 << 8) + 2,
 128     UAMEASUNIT_MASS_POUND           = (6 << 8) + 3,
 129     UAMEASUNIT_MASS_STONE           = (6 << 8) + 4,     // = 14 pounds / 6.35 kg, abbr "st", used in UK/Ireland for body weight (CLDR 26)
 130     UAMEASUNIT_MASS_MICROGRAM       = (6 << 8) + 5,     // (CLDR 26, ICU-541)
 131     UAMEASUNIT_MASS_MILLIGRAM       = (6 << 8) + 6,     // (CLDR 26, ICU-541)
 132     UAMEASUNIT_MASS_METRIC_TON      = (6 << 8) + 7,     // = "tonne" (CLDR 26, ICU-541)
 133     UAMEASUNIT_MASS_TON             = (6 << 8) + 8,     // = "short ton", U.S. ton (CLDR 26, ICU-541)
 134     UAMEASUNIT_MASS_CARAT           = (6 << 8) + 9,     // (CLDR 26, ICU-541)
 135     UAMEASUNIT_MASS_OUNCE_TROY      = (6 << 8) + 10,    // (CLDR 26, ICU-541)
 136     //
 137     UAMEASUNIT_POWER_WATT           = (7 << 8) + 0,
 138     UAMEASUNIT_POWER_KILOWATT       = (7 << 8) + 1,
 139     UAMEASUNIT_POWER_HORSEPOWER     = (7 << 8) + 2,
 140     UAMEASUNIT_POWER_MILLIWATT      = (7 << 8) + 3,     // (CLDR 26, ICU-541)
 141     UAMEASUNIT_POWER_MEGAWATT       = (7 << 8) + 4,     // (CLDR 26, ICU-541)
 142     UAMEASUNIT_POWER_GIGAWATT       = (7 << 8) + 5,     // (CLDR 26, ICU-541)
 143     //
 144     UAMEASUNIT_PRESSURE_HECTOPASCAL = (8 << 8) + 0,
 145     UAMEASUNIT_PRESSURE_INCH_HG     = (8 << 8) + 1,
 146     UAMEASUNIT_PRESSURE_MILLIBAR    = (8 << 8) + 2,
 147     UAMEASUNIT_PRESSURE_MILLIMETER_OF_MERCURY = (8 << 8) + 3, // (CLDR 26, ICU-541)
 148     UAMEASUNIT_PRESSURE_POUND_PER_SQUARE_INCH = (8 << 8) + 4, // (CLDR 26, ICU-541)
 149     //
 150     UAMEASUNIT_SPEED_METER_PER_SECOND   = (9 << 8) + 0,
 151     UAMEASUNIT_SPEED_KILOMETER_PER_HOUR = (9 << 8) + 1,
 152     UAMEASUNIT_SPEED_MILE_PER_HOUR      = (9 << 8) + 2,
 153     //
 154     UAMEASUNIT_TEMPERATURE_CELSIUS      = (10 << 8) + 0,
 155     UAMEASUNIT_TEMPERATURE_FAHRENHEIT   = (10 << 8) + 1,
 156     UAMEASUNIT_TEMPERATURE_KELVIN       = (10 << 8) + 2,    // (CLDR 26, ICU-541)
 157     UAMEASUNIT_TEMPERATURE_GENERIC      = (10 << 8) + 3,    // (CLDR 27, ICU-550.2)
 158     //
 159     UAMEASUNIT_VOLUME_LITER             = (11 << 8) + 0,
 160     UAMEASUNIT_VOLUME_CUBIC_KILOMETER   = (11 << 8) + 1,
 161     UAMEASUNIT_VOLUME_CUBIC_MILE        = (11 << 8) + 2,
 162     UAMEASUNIT_VOLUME_MILLILITER        = (11 << 8) + 3,    // (CLDR 26, ICU-541)
 163     UAMEASUNIT_VOLUME_CENTILITER        = (11 << 8) + 4,    // (CLDR 26, ICU-541)
 164     UAMEASUNIT_VOLUME_DECILITER         = (11 << 8) + 5,    // (CLDR 26, ICU-541)
 165     UAMEASUNIT_VOLUME_HECTOLITER        = (11 << 8) + 6,    // (CLDR 26, ICU-541)
 166     UAMEASUNIT_VOLUME_MEGALITER         = (11 << 8) + 7,    // (CLDR 26, ICU-541)
 167     UAMEASUNIT_VOLUME_CUBIC_CENTIMETER  = (11 << 8) + 8,    // (CLDR 26, ICU-541)
 168     UAMEASUNIT_VOLUME_CUBIC_METER       = (11 << 8) + 9,    // (CLDR 26, ICU-541)
 169     UAMEASUNIT_VOLUME_CUBIC_INCH        = (11 << 8) + 10,   // (CLDR 26, ICU-541)
 170     UAMEASUNIT_VOLUME_CUBIC_FOOT        = (11 << 8) + 11,   // (CLDR 26, ICU-541)
 171     UAMEASUNIT_VOLUME_CUBIC_YARD        = (11 << 8) + 12,   // (CLDR 26, ICU-541)
 172     UAMEASUNIT_VOLUME_ACRE_FOOT         = (11 << 8) + 13,   // (CLDR 26, ICU-541)
 173     UAMEASUNIT_VOLUME_BUSHEL            = (11 << 8) + 14,   // (CLDR 26, ICU-541)
 174     UAMEASUNIT_VOLUME_TEASPOON          = (11 << 8) + 15,   // (CLDR 26, ICU-541)
 175     UAMEASUNIT_VOLUME_TABLESPOON        = (11 << 8) + 16,   // (CLDR 26, ICU-541)
 176     UAMEASUNIT_VOLUME_FLUID_OUNCE       = (11 << 8) + 17,   // (CLDR 26, ICU-541)
 177     UAMEASUNIT_VOLUME_CUP               = (11 << 8) + 18,   // (CLDR 26, ICU-541)
 178     UAMEASUNIT_VOLUME_PINT              = (11 << 8) + 19,   // (CLDR 26, ICU-541)
 179     UAMEASUNIT_VOLUME_QUART             = (11 << 8) + 20,   // (CLDR 26, ICU-541)
 180     UAMEASUNIT_VOLUME_GALLON            = (11 << 8) + 21,   // (CLDR 26, ICU-541)
 181     //
 182     // new categories/values in CLDR 26
 183     //
 184     UAMEASUNIT_ENERGY_JOULE             = (12 << 8) + 2,
 185     UAMEASUNIT_ENERGY_KILOJOULE         = (12 << 8) + 4,
 186     UAMEASUNIT_ENERGY_CALORIE           = (12 << 8) + 0,    // chemistry "calories", abbr "cal"
 187     UAMEASUNIT_ENERGY_KILOCALORIE       = (12 << 8) + 3,    // kilocalories in general (chemistry, food), abbr "kcal"
 188     UAMEASUNIT_ENERGY_FOODCALORIE       = (12 << 8) + 1,    // kilocalories specifically for food; in US/UK/? "Calories" abbr "C", elsewhere same as "kcal"
 189     UAMEASUNIT_ENERGY_KILOWATT_HOUR     = (12 << 8) + 5,    // (ICU-541)
 190     //
 191     // new categories/values in CLDR 26 & ICU-541
 192     //
 193     UAMEASUNIT_CONSUMPTION_LITER_PER_KILOMETER = (13 << 8) + 0,
 194     UAMEASUNIT_CONSUMPTION_MILE_PER_GALLON     = (13 << 8) + 1,
 195     //
 196     UAMEASUNIT_DIGITAL_BIT              = (14 << 8) + 0,
 197     UAMEASUNIT_DIGITAL_BYTE             = (14 << 8) + 1,
 198     UAMEASUNIT_DIGITAL_GIGABIT          = (14 << 8) + 2,
 199     UAMEASUNIT_DIGITAL_GIGABYTE         = (14 << 8) + 3,
 200     UAMEASUNIT_DIGITAL_KILOBIT          = (14 << 8) + 4,
 201     UAMEASUNIT_DIGITAL_KILOBYTE         = (14 << 8) + 5,
 202     UAMEASUNIT_DIGITAL_MEGABIT          = (14 << 8) + 6,
 203     UAMEASUNIT_DIGITAL_MEGABYTE         = (14 << 8) + 7,
 204     UAMEASUNIT_DIGITAL_TERABIT          = (14 << 8) + 8,
 205     UAMEASUNIT_DIGITAL_TERABYTE         = (14 << 8) + 9,
 206     //
 207     UAMEASUNIT_ELECTRIC_AMPERE          = (15 << 8) + 0,
 208     UAMEASUNIT_ELECTRIC_MILLIAMPERE     = (15 << 8) + 1,
 209     UAMEASUNIT_ELECTRIC_OHM             = (15 << 8) + 2,
 210     UAMEASUNIT_ELECTRIC_VOLT            = (15 << 8) + 3,
 211     //
 212     UAMEASUNIT_FREQUENCY_HERTZ          = (16 << 8) + 0,
 213     UAMEASUNIT_FREQUENCY_KILOHERTZ      = (16 << 8) + 1,
 214     UAMEASUNIT_FREQUENCY_MEGAHERTZ      = (16 << 8) + 2,
 215     UAMEASUNIT_FREQUENCY_GIGAHERTZ      = (16 << 8) + 3,
 216     //
 217     UAMEASUNIT_LIGHT_LUX                = (17 << 8) + 0,
 218     //
 219     //UAMEASUNIT_PROPORTION_KARAT       = (18 << 8) + 0,    // wait on this one
 220 } UAMeasureUnit;
 221
 222 /**
 223  * Structure that combines value and UAMeasureUnit,
 224  * for use with uameasfmt_formatMultiple to specify a
 225  * list of value/unit combinations to format.
 226  * @draft ICU 54
 227  */
 228 typedef struct UAMeasure {
 229     double          value;
 230     UAMeasureUnit   unit;
 231 } UAMeasure;
 232
 233
 234 /**
 235  * Open a new UAMeasureFormat object for a given locale using the specified width,
 236  * along with a number formatter (if desired) to override the default formatter
 237  * that would be used for the numeric part of the unit in uameasfmt_format, or the
 238  * numeric part of the *last unit* (only) in uameasfmt_formatMultiple. The default
 239  * formatter uses zero decimal places and rounds toward 0; an alternate number formatter
 240  * can be used to produce (e.g.) "37.2 mins" instead of "37 mins", or
 241  * "5 hours, 37.2 minutes" instead of "5 hours, 37 minutes".
 242  *
 243  * @param locale
 244  *          The locale
 245  * @param style
 246  *          The width - wide, short, narrow, etc.
 247  * @param nfToAdopt
 248  *          A number formatter to set for this UAMeasureFormat object (instead of
 249  *          the default decimal formatter). Ownership of this UNumberFormat object
 250  *          will pass to the UAMeasureFormat object (the UAMeasureFormat adopts the
 251  *          UNumberFormat), which becomes responsible for closing it. If the caller
 252  *          wishes to retain ownership of the UNumberFormat object, the caller must
 253  *          clone it (with unum_clone) and pass the clone to
 254  *          uatmufmt_openWithNumberFormat. May be NULL to use the default decimal
 255  *          formatter.
 256  * @param status
 257  *          A pointer to a UErrorCode to receive any errors.
 258  * @return
 259  *          A pointer to a UAMeasureFormat object for the specified locale,
 260  *          or NULL if an error occurred.
 261  * @draft ICU 54
 262  */
 263 U_DRAFT UAMeasureFormat* U_EXPORT2
 264 uameasfmt_open( const char*          locale,
 265                 UAMeasureFormatWidth width,
 266                 UNumberFormat*       nfToAdopt,
 267                 UErrorCode*          status );
 268
 269 /**
 270  * Close a UAMeasureFormat object. Once closed it may no longer be used.
 271  * @param measfmt
 272  *            The UATimeUnitFormat object to close.
 273  * @draft ICU 54
 274  */
 275 U_DRAFT void U_EXPORT2
 276 uameasfmt_close(UAMeasureFormat *measfmt);
 277
 278 #if U_SHOW_CPLUSPLUS_API
 279
 280 U_NAMESPACE_BEGIN
 281
 282 /**
 283  * \class LocalUAMeasureFormatPointer
 284  * "Smart pointer" class, closes a UAMeasureFormat via uameasfmt_close().
 285  * For most methods see the LocalPointerBase base class.
 286  *
 287  * @see LocalPointerBase
 288  * @see LocalPointer
 289  * @draft ICU 54
 290  */
 291 U_DEFINE_LOCAL_OPEN_POINTER(LocalUAMeasureFormatPointer, UAMeasureFormat, uameasfmt_close);
 292
 293 U_NAMESPACE_END
 294
 295 #endif
 296
 297
 298 /**
 299  * Format a value like 1.0 and a field like UAMEASUNIT_DURATION_MINUTE to e.g. "1.0 minutes".
 300  *
 301  * @param measfmt
 302  *          The UAMeasureFormat object specifying the format conventions.
 303  * @param value
 304  *          The numeric value to format
 305  * @param unit
 306  *          The unit to format with the specified numeric value
 307  * @param result
 308  *          A pointer to a buffer to receive the formatted result.
 309  * @param resultCapacity
 310  *          The maximum size of result.
 311  * @param status
 312  *          A pointer to a UErrorCode to receive any errors. In case of error status,
 313  *          the contents of result are undefined.
 314  * @return
 315  *          The length of the formatted result; may be greater than resultCapacity,
 316  *          in which case an error is returned.
 317  * @draft ICU 54
 318  */
 319 U_DRAFT int32_t U_EXPORT2
 320 uameasfmt_format( const UAMeasureFormat* measfmt,
 321                   double            value,
 322                   UAMeasureUnit     unit,
 323                   UChar*            result,
 324                   int32_t           resultCapacity,
 325                   UErrorCode*       status );
 326
 327 /**
 328  * Format a value like 1.0 and a field like UAMEASUNIT_DURATION_MINUTE to e.g. "1.0 minutes",
 329  * and get the position in the formatted result for certain types for fields.
 330  *
 331  * @param measfmt
 332  *          The UAMeasureFormat object specifying the format conventions.
 333  * @param value
 334  *          The numeric value to format
 335  * @param unit
 336  *          The unit to format with the specified numeric value
 337  * @param result
 338  *          A pointer to a buffer to receive the formatted result.
 339  * @param resultCapacity
 340  *          The maximum size of result.
 341  * @param pos
 342  *          A pointer to a UFieldPosition. On input, pos->field is read; this should
 343  *          be a value from the UNumberFormatFields enum in unum.h. On output,
 344  *          pos->beginIndex and pos->endIndex indicate the beginning and ending offsets
 345  *          of that field in the formatted output, if relevant. This parameter may be
 346  *          NULL if no position information is desired.
 347  * @param status
 348  *          A pointer to a UErrorCode to receive any errors. In case of error status,
 349  *          the contents of result are undefined.
 350  * @return
 351  *          The length of the formatted result; may be greater than resultCapacity,
 352  *          in which case an error is returned.
 353  * @draft ICU 54
 354  */
 355 U_DRAFT int32_t U_EXPORT2
 356 uameasfmt_formatGetPosition( const UAMeasureFormat* measfmt,
 357                             double            value,
 358                             UAMeasureUnit     unit,
 359                             UChar*            result,
 360                             int32_t           resultCapacity,
 361                             UFieldPosition*   pos,
 362                             UErrorCode*       status );
 363
 364 /**
 365  * Format a list of value and unit combinations, using locale-appropriate
 366  * conventions for the list. Each combination is represented by a UAMeasure
 367  * that combines a value and unit, such as 5.3 + UAMEASUNIT_DURATION_HOUR or
 368  * 37.2 + UAMEASUNIT_DURATION_MINUTE. For all except the last UAMeasure in the
 369  * list, the numeric part will be formatted using the default formatter (zero
 370  * decimal places, rounds toward 0); for the last UAMeasure, the default may
 371  * be overriden by passing a number formatter in uameasfmt_open. The result
 372  * can thus be something like "5 hours, 37.2 minutes" or "5 hrs, 37.2 mins".
 373  *
 374  * @param measfmt
 375  *            The UAMeasureFormat object specifying the format conventions.
 376  * @param measures
 377  *            A list of UAMeasure structs each specifying a numeric value
 378  *            and a UAMeasureUnit.
 379  * @param measureCount
 380  *            The count of UAMeasureUnits in measures. Currently this has a limit of 8.
 381  * @param result
 382  *            A pointer to a buffer to receive the formatted result.
 383  * @param resultCapacity
 384  *            The maximum size of result.
 385  * @param status
 386  *            A pointer to a UErrorCode to receive any errors. In case of error status,
 387  *            the contents of result are undefined.
 388  * @return
 389  *            The length of the formatted result; may be greater than resultCapacity,
 390  *            in which case an error is returned.
 391  * @draft ICU 54
 392  */
 393 U_DRAFT int32_t U_EXPORT2
 394 uameasfmt_formatMultiple( const UAMeasureFormat* measfmt,
 395                           const UAMeasure*  measures,
 396                           int32_t           measureCount,
 397                           UChar*            result,
 398                           int32_t           resultCapacity,
 399                           UErrorCode*       status );
 400
 401
 402 #endif /* U_HIDE_DRAFT_API */
 403 #endif /* #if !UCONFIG_NO_FORMATTING */
 404
 405 #endif /* #ifndef UAMEASUREFORMAT_H */