/* ***************************************************************************************** * Copyright (C) 2014-2015 Apple Inc. All Rights Reserved. ***************************************************************************************** */ #ifndef UAMEASUREFORMAT_H #define UAMEASUREFORMAT_H #include "unicode/utypes.h" #if !UCONFIG_NO_FORMATTING #ifndef U_HIDE_DRAFT_API #include "unicode/localpointer.h" #include "unicode/unum.h" #include "unicode/umisc.h" /** * \file * \brief C API: Format combinations of measurement units and numeric values. * * This is a somewhat temporary Apple-specific wrapper for using C++ MeasureFormat * to format Measure objects, until the official ICU C API is available. */ /** * Opaque UAMeasureFormat object for use in C programs. * @draft ICU 53 */ struct UAMeasureFormat; typedef struct UAMeasureFormat UAMeasureFormat; /**< C typedef for struct UAMeasureFormat. @draft ICU 53 */ /** * Constants for various widths. * @draft ICU 53 */ typedef enum UAMeasureFormatWidth { /** * Full unit names, e.g. "5 hours, 37 minutes" * @draft ICU 53 */ UAMEASFMT_WIDTH_WIDE, /** * Abbreviated unit names, e.g. "5 hrs, 37 mins" * @draft ICU 53 */ UAMEASFMT_WIDTH_SHORT, /** * Use unit symbols if possible, e.g. "5 h, 37 m" * @draft ICU 53 */ UAMEASFMT_WIDTH_NARROW, /** * Completely omit unit designatins if possible, e.g. "5:37" * @draft ICU 53 */ UAMEASFMT_WIDTH_NUMERIC, /** * Count of values in this enum. * @draft ICU 53 */ UAMEASFMT_WIDTH_COUNT } UAMeasureFormatWidth; /** * Measurement units * @draft ICU 54 */ typedef enum UAMeasureUnit { UAMEASUNIT_ACCELERATION_G_FORCE = (0 << 8) + 0, UAMEASUNIT_ACCELERATION_METER_PER_SECOND_SQUARED = (0 << 8) + 1, // (CLDR 26, ICU-541) // UAMEASUNIT_ANGLE_DEGREE = (1 << 8) + 0, UAMEASUNIT_ANGLE_ARC_MINUTE = (1 << 8) + 1, UAMEASUNIT_ANGLE_ARC_SECOND = (1 << 8) + 2, UAMEASUNIT_ANGLE_RADIAN = (1 << 8) + 3, // (CLDR 26, ICU-541) // UAMEASUNIT_AREA_SQUARE_METER = (2 << 8) + 0, UAMEASUNIT_AREA_SQUARE_KILOMETER = (2 << 8) + 1, UAMEASUNIT_AREA_SQUARE_FOOT = (2 << 8) + 2, UAMEASUNIT_AREA_SQUARE_MILE = (2 << 8) + 3, UAMEASUNIT_AREA_ACRE = (2 << 8) + 4, UAMEASUNIT_AREA_HECTARE = (2 << 8) + 5, UAMEASUNIT_AREA_SQUARE_CENTIMETER = (2 << 8) + 6, // (CLDR 26, ICU-541) UAMEASUNIT_AREA_SQUARE_INCH = (2 << 8) + 7, // (CLDR 26, ICU-541) UAMEASUNIT_AREA_SQUARE_YARD = (2 << 8) + 8, // (CLDR 26, ICU-541) // // (3 reserved for currency, handled separately) // UAMEASUNIT_DURATION_YEAR = (4 << 8) + 0, UAMEASUNIT_DURATION_MONTH = (4 << 8) + 1, UAMEASUNIT_DURATION_WEEK = (4 << 8) + 2, UAMEASUNIT_DURATION_DAY = (4 << 8) + 3, UAMEASUNIT_DURATION_HOUR = (4 << 8) + 4, UAMEASUNIT_DURATION_MINUTE = (4 << 8) + 5, UAMEASUNIT_DURATION_SECOND = (4 << 8) + 6, UAMEASUNIT_DURATION_MILLISECOND = (4 << 8) + 7, UAMEASUNIT_DURATION_MICROSECOND = (4 << 8) + 8, // (CLDR 26, ICU-541) UAMEASUNIT_DURATION_NANOSECOND = (4 << 8) + 9, // (CLDR 26, ICU-541) // UAMEASUNIT_LENGTH_METER = (5 << 8) + 0, UAMEASUNIT_LENGTH_CENTIMETER = (5 << 8) + 1, UAMEASUNIT_LENGTH_KILOMETER = (5 << 8) + 2, UAMEASUNIT_LENGTH_MILLIMETER = (5 << 8) + 3, UAMEASUNIT_LENGTH_PICOMETER = (5 << 8) + 4, UAMEASUNIT_LENGTH_FOOT = (5 << 8) + 5, UAMEASUNIT_LENGTH_INCH = (5 << 8) + 6, UAMEASUNIT_LENGTH_MILE = (5 << 8) + 7, UAMEASUNIT_LENGTH_YARD = (5 << 8) + 8, UAMEASUNIT_LENGTH_LIGHT_YEAR = (5 << 8) + 9, UAMEASUNIT_LENGTH_DECIMETER = (5 << 8) + 10, // (CLDR 26, ICU-541) UAMEASUNIT_LENGTH_MICROMETER = (5 << 8) + 11, // (CLDR 26, ICU-541) UAMEASUNIT_LENGTH_NANOMETER = (5 << 8) + 12, // (CLDR 26, ICU-541) UAMEASUNIT_LENGTH_NAUTICAL_MILE = (5 << 8) + 13, // (CLDR 26, ICU-541) UAMEASUNIT_LENGTH_FATHOM = (5 << 8) + 14, // (CLDR 26, ICU-541) UAMEASUNIT_LENGTH_FURLONG = (5 << 8) + 15, // (CLDR 26, ICU-541) UAMEASUNIT_LENGTH_ASTRONOMICAL_UNIT = (5 << 8) + 16, // (CLDR 26, ICU-541) UAMEASUNIT_LENGTH_PARSEC = (5 << 8) + 17, // (CLDR 26, ICU-541) // UAMEASUNIT_MASS_GRAM = (6 << 8) + 0, UAMEASUNIT_MASS_KILOGRAM = (6 << 8) + 1, UAMEASUNIT_MASS_OUNCE = (6 << 8) + 2, UAMEASUNIT_MASS_POUND = (6 << 8) + 3, UAMEASUNIT_MASS_STONE = (6 << 8) + 4, // = 14 pounds / 6.35 kg, abbr "st", used in UK/Ireland for body weight (CLDR 26) UAMEASUNIT_MASS_MICROGRAM = (6 << 8) + 5, // (CLDR 26, ICU-541) UAMEASUNIT_MASS_MILLIGRAM = (6 << 8) + 6, // (CLDR 26, ICU-541) UAMEASUNIT_MASS_METRIC_TON = (6 << 8) + 7, // = "tonne" (CLDR 26, ICU-541) UAMEASUNIT_MASS_TON = (6 << 8) + 8, // = "short ton", U.S. ton (CLDR 26, ICU-541) UAMEASUNIT_MASS_CARAT = (6 << 8) + 9, // (CLDR 26, ICU-541) UAMEASUNIT_MASS_OUNCE_TROY = (6 << 8) + 10, // (CLDR 26, ICU-541) // UAMEASUNIT_POWER_WATT = (7 << 8) + 0, UAMEASUNIT_POWER_KILOWATT = (7 << 8) + 1, UAMEASUNIT_POWER_HORSEPOWER = (7 << 8) + 2, UAMEASUNIT_POWER_MILLIWATT = (7 << 8) + 3, // (CLDR 26, ICU-541) UAMEASUNIT_POWER_MEGAWATT = (7 << 8) + 4, // (CLDR 26, ICU-541) UAMEASUNIT_POWER_GIGAWATT = (7 << 8) + 5, // (CLDR 26, ICU-541) // UAMEASUNIT_PRESSURE_HECTOPASCAL = (8 << 8) + 0, UAMEASUNIT_PRESSURE_INCH_HG = (8 << 8) + 1, UAMEASUNIT_PRESSURE_MILLIBAR = (8 << 8) + 2, UAMEASUNIT_PRESSURE_MILLIMETER_OF_MERCURY = (8 << 8) + 3, // (CLDR 26, ICU-541) UAMEASUNIT_PRESSURE_POUND_PER_SQUARE_INCH = (8 << 8) + 4, // (CLDR 26, ICU-541) // UAMEASUNIT_SPEED_METER_PER_SECOND = (9 << 8) + 0, UAMEASUNIT_SPEED_KILOMETER_PER_HOUR = (9 << 8) + 1, UAMEASUNIT_SPEED_MILE_PER_HOUR = (9 << 8) + 2, // UAMEASUNIT_TEMPERATURE_CELSIUS = (10 << 8) + 0, UAMEASUNIT_TEMPERATURE_FAHRENHEIT = (10 << 8) + 1, UAMEASUNIT_TEMPERATURE_KELVIN = (10 << 8) + 2, // (CLDR 26, ICU-541) UAMEASUNIT_TEMPERATURE_GENERIC = (10 << 8) + 3, // (CLDR 27, ICU-550.2) // UAMEASUNIT_VOLUME_LITER = (11 << 8) + 0, UAMEASUNIT_VOLUME_CUBIC_KILOMETER = (11 << 8) + 1, UAMEASUNIT_VOLUME_CUBIC_MILE = (11 << 8) + 2, UAMEASUNIT_VOLUME_MILLILITER = (11 << 8) + 3, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_CENTILITER = (11 << 8) + 4, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_DECILITER = (11 << 8) + 5, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_HECTOLITER = (11 << 8) + 6, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_MEGALITER = (11 << 8) + 7, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_CUBIC_CENTIMETER = (11 << 8) + 8, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_CUBIC_METER = (11 << 8) + 9, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_CUBIC_INCH = (11 << 8) + 10, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_CUBIC_FOOT = (11 << 8) + 11, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_CUBIC_YARD = (11 << 8) + 12, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_ACRE_FOOT = (11 << 8) + 13, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_BUSHEL = (11 << 8) + 14, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_TEASPOON = (11 << 8) + 15, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_TABLESPOON = (11 << 8) + 16, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_FLUID_OUNCE = (11 << 8) + 17, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_CUP = (11 << 8) + 18, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_PINT = (11 << 8) + 19, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_QUART = (11 << 8) + 20, // (CLDR 26, ICU-541) UAMEASUNIT_VOLUME_GALLON = (11 << 8) + 21, // (CLDR 26, ICU-541) // // new categories/values in CLDR 26 // UAMEASUNIT_ENERGY_JOULE = (12 << 8) + 2, UAMEASUNIT_ENERGY_KILOJOULE = (12 << 8) + 4, UAMEASUNIT_ENERGY_CALORIE = (12 << 8) + 0, // chemistry "calories", abbr "cal" UAMEASUNIT_ENERGY_KILOCALORIE = (12 << 8) + 3, // kilocalories in general (chemistry, food), abbr "kcal" UAMEASUNIT_ENERGY_FOODCALORIE = (12 << 8) + 1, // kilocalories specifically for food; in US/UK/? "Calories" abbr "C", elsewhere same as "kcal" UAMEASUNIT_ENERGY_KILOWATT_HOUR = (12 << 8) + 5, // (ICU-541) // // new categories/values in CLDR 26 & ICU-541 // UAMEASUNIT_CONSUMPTION_LITER_PER_KILOMETER = (13 << 8) + 0, UAMEASUNIT_CONSUMPTION_MILE_PER_GALLON = (13 << 8) + 1, // UAMEASUNIT_DIGITAL_BIT = (14 << 8) + 0, UAMEASUNIT_DIGITAL_BYTE = (14 << 8) + 1, UAMEASUNIT_DIGITAL_GIGABIT = (14 << 8) + 2, UAMEASUNIT_DIGITAL_GIGABYTE = (14 << 8) + 3, UAMEASUNIT_DIGITAL_KILOBIT = (14 << 8) + 4, UAMEASUNIT_DIGITAL_KILOBYTE = (14 << 8) + 5, UAMEASUNIT_DIGITAL_MEGABIT = (14 << 8) + 6, UAMEASUNIT_DIGITAL_MEGABYTE = (14 << 8) + 7, UAMEASUNIT_DIGITAL_TERABIT = (14 << 8) + 8, UAMEASUNIT_DIGITAL_TERABYTE = (14 << 8) + 9, // UAMEASUNIT_ELECTRIC_AMPERE = (15 << 8) + 0, UAMEASUNIT_ELECTRIC_MILLIAMPERE = (15 << 8) + 1, UAMEASUNIT_ELECTRIC_OHM = (15 << 8) + 2, UAMEASUNIT_ELECTRIC_VOLT = (15 << 8) + 3, // UAMEASUNIT_FREQUENCY_HERTZ = (16 << 8) + 0, UAMEASUNIT_FREQUENCY_KILOHERTZ = (16 << 8) + 1, UAMEASUNIT_FREQUENCY_MEGAHERTZ = (16 << 8) + 2, UAMEASUNIT_FREQUENCY_GIGAHERTZ = (16 << 8) + 3, // UAMEASUNIT_LIGHT_LUX = (17 << 8) + 0, // //UAMEASUNIT_PROPORTION_KARAT = (18 << 8) + 0, // wait on this one } UAMeasureUnit; /** * Structure that combines value and UAMeasureUnit, * for use with uameasfmt_formatMultiple to specify a * list of value/unit combinations to format. * @draft ICU 54 */ typedef struct UAMeasure { double value; UAMeasureUnit unit; } UAMeasure; /** * Open a new UAMeasureFormat object for a given locale using the specified width, * along with a number formatter (if desired) to override the default formatter * that would be used for the numeric part of the unit in uameasfmt_format, or the * numeric part of the *last unit* (only) in uameasfmt_formatMultiple. The default * formatter uses zero decimal places and rounds toward 0; an alternate number formatter * can be used to produce (e.g.) "37.2 mins" instead of "37 mins", or * "5 hours, 37.2 minutes" instead of "5 hours, 37 minutes". * * @param locale * The locale * @param style * The width - wide, short, narrow, etc. * @param nfToAdopt * A number formatter to set for this UAMeasureFormat object (instead of * the default decimal formatter). Ownership of this UNumberFormat object * will pass to the UAMeasureFormat object (the UAMeasureFormat adopts the * UNumberFormat), which becomes responsible for closing it. If the caller * wishes to retain ownership of the UNumberFormat object, the caller must * clone it (with unum_clone) and pass the clone to * uatmufmt_openWithNumberFormat. May be NULL to use the default decimal * formatter. * @param status * A pointer to a UErrorCode to receive any errors. * @return * A pointer to a UAMeasureFormat object for the specified locale, * or NULL if an error occurred. * @draft ICU 54 */ U_DRAFT UAMeasureFormat* U_EXPORT2 uameasfmt_open( const char* locale, UAMeasureFormatWidth width, UNumberFormat* nfToAdopt, UErrorCode* status ); /** * Close a UAMeasureFormat object. Once closed it may no longer be used. * @param measfmt * The UATimeUnitFormat object to close. * @draft ICU 54 */ U_DRAFT void U_EXPORT2 uameasfmt_close(UAMeasureFormat *measfmt); #if U_SHOW_CPLUSPLUS_API U_NAMESPACE_BEGIN /** * \class LocalUAMeasureFormatPointer * "Smart pointer" class, closes a UAMeasureFormat via uameasfmt_close(). * For most methods see the LocalPointerBase base class. * * @see LocalPointerBase * @see LocalPointer * @draft ICU 54 */ U_DEFINE_LOCAL_OPEN_POINTER(LocalUAMeasureFormatPointer, UAMeasureFormat, uameasfmt_close); U_NAMESPACE_END #endif /** * Format a value like 1.0 and a field like UAMEASUNIT_DURATION_MINUTE to e.g. "1.0 minutes". * * @param measfmt * The UAMeasureFormat object specifying the format conventions. * @param value * The numeric value to format * @param unit * The unit to format with the specified numeric value * @param result * A pointer to a buffer to receive the formatted result. * @param resultCapacity * The maximum size of result. * @param status * A pointer to a UErrorCode to receive any errors. In case of error status, * the contents of result are undefined. * @return * The length of the formatted result; may be greater than resultCapacity, * in which case an error is returned. * @draft ICU 54 */ U_DRAFT int32_t U_EXPORT2 uameasfmt_format( const UAMeasureFormat* measfmt, double value, UAMeasureUnit unit, UChar* result, int32_t resultCapacity, UErrorCode* status ); /** * Format a value like 1.0 and a field like UAMEASUNIT_DURATION_MINUTE to e.g. "1.0 minutes", * and get the position in the formatted result for certain types for fields. * * @param measfmt * The UAMeasureFormat object specifying the format conventions. * @param value * The numeric value to format * @param unit * The unit to format with the specified numeric value * @param result * A pointer to a buffer to receive the formatted result. * @param resultCapacity * The maximum size of result. * @param pos * A pointer to a UFieldPosition. On input, pos->field is read; this should * be a value from the UNumberFormatFields enum in unum.h. On output, * pos->beginIndex and pos->endIndex indicate the beginning and ending offsets * of that field in the formatted output, if relevant. This parameter may be * NULL if no position information is desired. * @param status * A pointer to a UErrorCode to receive any errors. In case of error status, * the contents of result are undefined. * @return * The length of the formatted result; may be greater than resultCapacity, * in which case an error is returned. * @draft ICU 54 */ U_DRAFT int32_t U_EXPORT2 uameasfmt_formatGetPosition( const UAMeasureFormat* measfmt, double value, UAMeasureUnit unit, UChar* result, int32_t resultCapacity, UFieldPosition* pos, UErrorCode* status ); /** * Format a list of value and unit combinations, using locale-appropriate * conventions for the list. Each combination is represented by a UAMeasure * that combines a value and unit, such as 5.3 + UAMEASUNIT_DURATION_HOUR or * 37.2 + UAMEASUNIT_DURATION_MINUTE. For all except the last UAMeasure in the * list, the numeric part will be formatted using the default formatter (zero * decimal places, rounds toward 0); for the last UAMeasure, the default may * be overriden by passing a number formatter in uameasfmt_open. The result * can thus be something like "5 hours, 37.2 minutes" or "5 hrs, 37.2 mins". * * @param measfmt * The UAMeasureFormat object specifying the format conventions. * @param measures * A list of UAMeasure structs each specifying a numeric value * and a UAMeasureUnit. * @param measureCount * The count of UAMeasureUnits in measures. Currently this has a limit of 8. * @param result * A pointer to a buffer to receive the formatted result. * @param resultCapacity * The maximum size of result. * @param status * A pointer to a UErrorCode to receive any errors. In case of error status, * the contents of result are undefined. * @return * The length of the formatted result; may be greater than resultCapacity, * in which case an error is returned. * @draft ICU 54 */ U_DRAFT int32_t U_EXPORT2 uameasfmt_formatMultiple( const UAMeasureFormat* measfmt, const UAMeasure* measures, int32_t measureCount, UChar* result, int32_t resultCapacity, UErrorCode* status ); #endif /* U_HIDE_DRAFT_API */ #endif /* #if !UCONFIG_NO_FORMATTING */ #endif /* #ifndef UAMEASUREFORMAT_H */