icuSources/i18n/unicode/measfmt.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 **********************************************************************
   5 * Copyright (c) 2004-2016, International Business Machines
   6 * Corporation and others.  All Rights Reserved.
   7 **********************************************************************
   8 * Author: Alan Liu
   9 * Created: April 20, 2004
  10 * Since: ICU 3.0
  11 **********************************************************************
  12 */
  13 #ifndef MEASUREFORMAT_H
  14 #define MEASUREFORMAT_H
  15
  16 #include "unicode/utypes.h"
  17
  18 #if !UCONFIG_NO_FORMATTING
  19
  20 #include "unicode/format.h"
  21 #include "unicode/udat.h"
  22 // Apple specific:
  23 #include "unicode/uameasureformat.h"
  24
  25 /**
  26  * \file
  27  * \brief C++ API: Formatter for measure objects.
  28  */
  29
  30 /**
  31  * Constants for various widths.
  32  * There are 4 widths: Wide, Short, Narrow, Numeric.
  33  * For example, for English, when formatting "3 hours"
  34  * Wide is "3 hours"; short is "3 hrs"; narrow is "3h";
  35  * formatting "3 hours 17 minutes" as numeric give "3:17"
  36  * @stable ICU 53
  37  */
  38 enum UMeasureFormatWidth {
  39
  40     // Wide, short, and narrow must be first and in this order.
  41     /**
  42      * Spell out measure units.
  43      * @stable ICU 53
  44      */
  45     UMEASFMT_WIDTH_WIDE,
  46
  47     /**
  48      * Abbreviate measure units.
  49      * @stable ICU 53
  50      */
  51     UMEASFMT_WIDTH_SHORT,
  52
  53     /**
  54      * Use symbols for measure units when possible.
  55      * @stable ICU 53
  56      */
  57     UMEASFMT_WIDTH_NARROW,
  58
  59     /**
  60      * Completely omit measure units when possible. For example, format
  61      * '5 hours, 37 minutes' as '5:37'
  62      * @stable ICU 53
  63      */
  64     UMEASFMT_WIDTH_NUMERIC,
  65
  66 #ifndef U_HIDE_DEPRECATED_API
  67     /**
  68      * One more than the highest normal UMeasureFormatWidth value.
  69      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
  70      */
  71     UMEASFMT_WIDTH_COUNT = 4
  72 #endif  // U_HIDE_DEPRECATED_API
  73 #ifndef U_HIDE_INTERNAL_API
  74     ,
  75     /**
  76      * Apple-specific
  77      * Shorter, between SHORT and NARROW (SHORT without space in unit pattern)
  78      * @draft ICU 57
  79      */
  80     UMEASFMT_WIDTH_SHORTER = 8
  81 #endif /* U_HIDE_INTERNAL_API */
  82 };
  83 /** @stable ICU 53 */
  84 typedef enum UMeasureFormatWidth UMeasureFormatWidth;
  85
  86 #if U_SHOW_CPLUSPLUS_API
  87 U_NAMESPACE_BEGIN
  88
  89 class Measure;
  90 class MeasureUnit;
  91 class NumberFormat;
  92 class PluralRules;
  93 class MeasureFormatCacheData;
  94 class SharedNumberFormat;
  95 class SharedPluralRules;
  96 class QuantityFormatter;
  97 class SimpleFormatter;
  98 class ListFormatter;
  99 class DateFormat;
 100 class FieldPositionHandler;
 101
 102 /**
 103  *
 104  * A formatter for measure objects.
 105  *
 106  * @see Format
 107  * @author Alan Liu
 108  * @stable ICU 3.0
 109  */
 110 class U_I18N_API MeasureFormat : public Format {
 111  public:
 112     using Format::parseObject;
 113     using Format::format;
 114
 115     /**
 116      * Constructor.
 117      * @stable ICU 53
 118      */
 119     MeasureFormat(
 120             const Locale &locale, UMeasureFormatWidth width, UErrorCode &status);
 121
 122     /**
 123      * Constructor.
 124      * @stable ICU 53
 125      */
 126     MeasureFormat(
 127             const Locale &locale,
 128             UMeasureFormatWidth width,
 129             NumberFormat *nfToAdopt,
 130             UErrorCode &status);
 131
 132     /**
 133      * Copy constructor.
 134      * @stable ICU 3.0
 135      */
 136     MeasureFormat(const MeasureFormat &other);
 137
 138     /**
 139      * Assignment operator.
 140      * @stable ICU 3.0
 141      */
 142     MeasureFormat &operator=(const MeasureFormat &rhs);
 143
 144     /**
 145      * Destructor.
 146      * @stable ICU 3.0
 147      */
 148     virtual ~MeasureFormat();
 149
 150     /**
 151      * Return true if given Format objects are semantically equal.
 152      * @stable ICU 53
 153      */
 154     virtual UBool operator==(const Format &other) const;
 155
 156     /**
 157      * Clones this object polymorphically.
 158      * @stable ICU 53
 159      */
 160     virtual Format *clone() const;
 161
 162     /**
 163      * Formats object to produce a string.
 164      * @stable ICU 53
 165      */
 166     virtual UnicodeString &format(
 167             const Formattable &obj,
 168             UnicodeString &appendTo,
 169             FieldPosition &pos,
 170             UErrorCode &status) const;
 171
 172     /**
 173      * Parse a string to produce an object. This implementation sets
 174      * status to U_UNSUPPORTED_ERROR.
 175      *
 176      * @draft ICU 53
 177      */
 178     virtual void parseObject(
 179             const UnicodeString &source,
 180             Formattable &reslt,
 181             ParsePosition &pos) const;
 182
 183     /**
 184      * Formats measure objects to produce a string. An example of such a
 185      * formatted string is 3 meters, 3.5 centimeters. Measure objects appear
 186      * in the formatted string in the same order they appear in the "measures"
 187      * array. The NumberFormat of this object is used only to format the amount
 188      * of the very last measure. The other amounts are formatted with zero
 189      * decimal places while rounding toward zero.
 190      * @param measures array of measure objects.
 191      * @param measureCount the number of measure objects.
 192      * @param appendTo formatted string appended here.
 193      * @param pos the field position.
 194      * @param status the error.
 195      * @return appendTo reference
 196      *
 197      * @stable ICU 53
 198      */
 199     UnicodeString &formatMeasures(
 200             const Measure *measures,
 201             int32_t measureCount,
 202             UnicodeString &appendTo,
 203             FieldPosition &pos,
 204             UErrorCode &status) const;
 205
 206 #ifndef U_HIDE_INTERNAL_API
 207     /**
 208      * Apple-specific for now.
 209      * Like formatMeasures above, but with a
 210      * FieldPositionIterator* instead of a FieldPosition&
 211      *
 212      * @param measures  Array of measure objects.
 213      * @param measureCount the number of measure objects.
 214      * @param appendTo  Formatted string appended here.
 215      * @param posIter   On return, can be used to iterate over positions
 216      *                  of fields generated by this format call. Field
 217      *                  values are defined in UAMeasureUnit.
 218      * @param status    The error.
 219      * @return appendTo reference
 220      *
 221     * @internal.
 222       */
 223     UnicodeString &formatMeasures(
 224             const Measure *measures,
 225             int32_t measureCount,
 226             UnicodeString &appendTo,
 227             FieldPositionIterator* posIter,
 228             UErrorCode &status) const;
 229
 230    /**
 231      * Apple-specific for now
 232      * @internal.
 233      */
 234     UMeasureFormatWidth getWidth(void) const;
 235
 236 #endif  /* U_HIDE_INTERNAL_API */
 237
 238
 239     /**
 240      * Formats a single measure per unit. An example of such a
 241      * formatted string is 3.5 meters per second.
 242      * @param measure The measure object. In above example, 3.5 meters.
 243      * @param perUnit The per unit. In above example, it is
 244      *        *MeasureUnit::createSecond(status).
 245      * @param appendTo formatted string appended here.
 246      * @param pos the field position.
 247      * @param status the error.
 248      * @return appendTo reference
 249      *
 250      * @stable ICU 55
 251      */
 252     UnicodeString &formatMeasurePerUnit(
 253             const Measure &measure,
 254             const MeasureUnit &perUnit,
 255             UnicodeString &appendTo,
 256             FieldPosition &pos,
 257             UErrorCode &status) const;
 258
 259 #ifndef U_HIDE_DRAFT_API
 260     /**
 261      * Gets the display name of the specified {@link MeasureUnit} corresponding to the current
 262      * locale and format width.
 263      * @param unit  The unit for which to get a display name.
 264      * @param status the error.
 265      * @return  The display name in the locale and width specified in
 266      *          {@link MeasureFormat#getInstance}, or null if there is no display name available
 267      *          for the specified unit.
 268      *
 269      * @draft ICU 58
 270      */
 271     UnicodeString getUnitDisplayName(const MeasureUnit& unit, UErrorCode &status) const;
 272 #endif /* U_HIDE_DRAFT_API */
 273
 274
 275     /**
 276      * Return a formatter for CurrencyAmount objects in the given
 277      * locale.
 278      * @param locale desired locale
 279      * @param ec input-output error code
 280      * @return a formatter object, or NULL upon error
 281      * @stable ICU 3.0
 282      */
 283     static MeasureFormat* U_EXPORT2 createCurrencyFormat(const Locale& locale,
 284                                                UErrorCode& ec);
 285
 286     /**
 287      * Return a formatter for CurrencyAmount objects in the default
 288      * locale.
 289      * @param ec input-output error code
 290      * @return a formatter object, or NULL upon error
 291      * @stable ICU 3.0
 292      */
 293     static MeasureFormat* U_EXPORT2 createCurrencyFormat(UErrorCode& ec);
 294
 295     /**
 296      * Return the class ID for this class. This is useful only for comparing to
 297      * a return value from getDynamicClassID(). For example:
 298      * <pre>
 299      * .   Base* polymorphic_pointer = createPolymorphicObject();
 300      * .   if (polymorphic_pointer->getDynamicClassID() ==
 301      * .       erived::getStaticClassID()) ...
 302      * </pre>
 303      * @return          The class ID for all objects of this class.
 304      * @stable ICU 53
 305      */
 306     static UClassID U_EXPORT2 getStaticClassID(void);
 307
 308     /**
 309      * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
 310      * method is to implement a simple version of RTTI, since not all C++
 311      * compilers support genuine RTTI. Polymorphic operator==() and clone()
 312      * methods call this method.
 313      *
 314      * @return          The class ID for this object. All objects of a
 315      *                  given class have the same class ID.  Objects of
 316      *                  other classes have different class IDs.
 317      * @stable ICU 53
 318      */
 319     virtual UClassID getDynamicClassID(void) const;
 320
 321  protected:
 322     /**
 323      * Default constructor.
 324      * @stable ICU 3.0
 325      */
 326     MeasureFormat();
 327
 328 #ifndef U_HIDE_INTERNAL_API
 329
 330     /**
 331      * ICU use only.
 332      * Initialize or change MeasureFormat class from subclass.
 333      * @internal.
 334      */
 335     void initMeasureFormat(
 336             const Locale &locale,
 337             UMeasureFormatWidth width,
 338             NumberFormat *nfToAdopt,
 339             UErrorCode &status);
 340     /**
 341      * ICU use only.
 342      * Allows subclass to change locale. Note that this method also changes
 343      * the NumberFormat object. Returns TRUE if locale changed; FALSE if no
 344      * change was made.
 345      * @internal.
 346      */
 347     UBool setMeasureFormatLocale(const Locale &locale, UErrorCode &status);
 348
 349  public:
 350     // Apple-only, temporarily public for Apple use
 351     /**
 352      * ICU use only.
 353      * Let subclass change NumberFormat.
 354      * @internal Apple
 355      */
 356     void adoptNumberFormat(NumberFormat *nfToAdopt, UErrorCode &status);
 357
 358     /**
 359      * Gets the display name for a unit.
 360      * @param unit The unit whose display name to get.
 361      * @param result Receives the name result, if any (if none,
 362      *               length will be 0)
 363      * @return Reference to result
 364      *
 365      * @internal Apple
 366      */
 367     UnicodeString &getUnitName(
 368             const MeasureUnit* unit,
 369             UnicodeString &result ) const;
 370
 371     /**
 372      * Gets the display name for a set of  units.
 373      * @param units Array of units whose display name to get.
 374      * @param unitCount The count of units
 375      * @param listStyle The list style used for combining the unit names.
 376      * @param result Receives the name result, if any (if none,
 377      *               length will be 0)
 378      * @return Reference to result
 379      *
 380      * @internal Apple
 381      */
 382     UnicodeString &getMultipleUnitNames(
 383             const MeasureUnit** units,
 384             int32_t unitCount,
 385             UAMeasureNameListStyle listStyle,
 386             UnicodeString &result ) const;
 387
 388  protected:
 389     /**
 390      * ICU use only.
 391      * @internal.
 392      */
 393     const NumberFormat &getNumberFormat() const;
 394
 395     /**
 396      * ICU use only.
 397      * @internal.
 398      */
 399     const PluralRules &getPluralRules() const;
 400
 401     /**
 402      * ICU use only.
 403      * @internal.
 404      */
 405     Locale getLocale(UErrorCode &status) const;
 406
 407     /**
 408      * ICU use only.
 409      * @internal.
 410      */
 411     const char *getLocaleID(UErrorCode &status) const;
 412
 413 #endif /* U_HIDE_INTERNAL_API */
 414
 415  private:
 416     const MeasureFormatCacheData *cache;
 417     const SharedNumberFormat *numberFormat;
 418     const SharedPluralRules *pluralRules;
 419     UMeasureFormatWidth width;
 420     UBool stripPatternSpaces;
 421
 422     // Declared outside of MeasureFormatSharedData because ListFormatter
 423     // objects are relatively cheap to copy; therefore, they don't need to be
 424     // shared across instances.
 425     ListFormatter *listFormatter;
 426     ListFormatter *listFormatterStd; // standard list style, option for display names; Apple specific
 427
 428     const SimpleFormatter *getFormatterOrNull(
 429             const MeasureUnit &unit, UMeasureFormatWidth width, int32_t index) const;
 430
 431     const SimpleFormatter *getFormatter(
 432             const MeasureUnit &unit, UMeasureFormatWidth width, int32_t index,
 433             UErrorCode &errorCode) const;
 434
 435     const SimpleFormatter *getPluralFormatter(
 436             const MeasureUnit &unit, UMeasureFormatWidth width, int32_t index,
 437             UErrorCode &errorCode) const;
 438
 439     const SimpleFormatter *getPerFormatter(
 440             UMeasureFormatWidth width,
 441             UErrorCode &status) const;
 442
 443     int32_t withPerUnitAndAppend(
 444         const UnicodeString &formatted,
 445         const MeasureUnit &perUnit,
 446         UnicodeString &appendTo,
 447         UErrorCode &status) const;
 448
 449     UnicodeString &formatMeasure(
 450         const Measure &measure,
 451         const NumberFormat &nf,
 452         UnicodeString &appendTo,
 453         FieldPosition &pos,
 454         UErrorCode &status) const;
 455
 456     UnicodeString &formatMeasuresSlowTrack(
 457         const Measure *measures,
 458         int32_t measureCount,
 459         UnicodeString& appendTo,
 460         FieldPosition& pos,
 461         UErrorCode& status) const;
 462
 463     UnicodeString &formatNumeric(
 464         const Formattable *hms,  // always length 3: [0] is hour; [1] is
 465                                  // minute; [2] is second.
 466         int32_t bitMap,   // 1=hour set, 2=minute set, 4=second set
 467         UnicodeString &appendTo,
 468         FieldPositionHandler& handler,
 469         UErrorCode &status) const;
 470
 471     UnicodeString &formatNumeric(
 472         UDate date,
 473         const DateFormat &dateFmt,
 474         UDateFormatField smallestField,
 475         const Formattable &smallestAmount,
 476         UnicodeString &appendTo,
 477         FieldPositionHandler& handler,
 478         UErrorCode &status) const;
 479 };
 480
 481 U_NAMESPACE_END
 482 #endif // U_SHOW_CPLUSPLUS_API
 483
 484 #endif // #if !UCONFIG_NO_FORMATTING
 485 #endif // #ifndef MEASUREFORMAT_H