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: Compatibility APIs for measure formatting.
  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  * <p><strong>IMPORTANT:</strong> New users are strongly encouraged to see if
 104  * numberformatter.h fits their use case.  Although not deprecated, this header
 105  * is provided for backwards compatibility only.
 106  *
 107  * @see Format
 108  * @author Alan Liu
 109  * @stable ICU 3.0
 110  */
 111 class U_I18N_API MeasureFormat : public Format {
 112  public:
 113     using Format::parseObject;
 114     using Format::format;
 115
 116     /**
 117      * Constructor.
 118      * <p>
 119      * <strong>NOTE:</strong> New users are strongly encouraged to use
 120      * {@link icu::number::NumberFormatter} instead of NumberFormat.
 121      * @stable ICU 53
 122      */
 123     MeasureFormat(
 124             const Locale &locale, UMeasureFormatWidth width, UErrorCode &status);
 125
 126     /**
 127      * Constructor.
 128      * <p>
 129      * <strong>NOTE:</strong> New users are strongly encouraged to use
 130      * {@link icu::number::NumberFormatter} instead of NumberFormat.
 131      * @stable ICU 53
 132      */
 133     MeasureFormat(
 134             const Locale &locale,
 135             UMeasureFormatWidth width,
 136             NumberFormat *nfToAdopt,
 137             UErrorCode &status);
 138
 139     /**
 140      * Copy constructor.
 141      * @stable ICU 3.0
 142      */
 143     MeasureFormat(const MeasureFormat &other);
 144
 145     /**
 146      * Assignment operator.
 147      * @stable ICU 3.0
 148      */
 149     MeasureFormat &operator=(const MeasureFormat &rhs);
 150
 151     /**
 152      * Destructor.
 153      * @stable ICU 3.0
 154      */
 155     virtual ~MeasureFormat();
 156
 157     /**
 158      * Return true if given Format objects are semantically equal.
 159      * @stable ICU 53
 160      */
 161     virtual UBool operator==(const Format &other) const;
 162
 163     /**
 164      * Clones this object polymorphically.
 165      * @stable ICU 53
 166      */
 167     virtual Format *clone() const;
 168
 169     /**
 170      * Formats object to produce a string.
 171      * @stable ICU 53
 172      */
 173     virtual UnicodeString &format(
 174             const Formattable &obj,
 175             UnicodeString &appendTo,
 176             FieldPosition &pos,
 177             UErrorCode &status) const;
 178
 179     /**
 180      * Parse a string to produce an object. This implementation sets
 181      * status to U_UNSUPPORTED_ERROR.
 182      *
 183      * @draft ICU 53
 184      */
 185     virtual void parseObject(
 186             const UnicodeString &source,
 187             Formattable &reslt,
 188             ParsePosition &pos) const;
 189
 190     /**
 191      * Formats measure objects to produce a string. An example of such a
 192      * formatted string is 3 meters, 3.5 centimeters. Measure objects appear
 193      * in the formatted string in the same order they appear in the "measures"
 194      * array. The NumberFormat of this object is used only to format the amount
 195      * of the very last measure. The other amounts are formatted with zero
 196      * decimal places while rounding toward zero.
 197      * @param measures array of measure objects.
 198      * @param measureCount the number of measure objects.
 199      * @param appendTo formatted string appended here.
 200      * @param pos the field position.
 201      * @param status the error.
 202      * @return appendTo reference
 203      *
 204      * @stable ICU 53
 205      */
 206     UnicodeString &formatMeasures(
 207             const Measure *measures,
 208             int32_t measureCount,
 209             UnicodeString &appendTo,
 210             FieldPosition &pos,
 211             UErrorCode &status) const;
 212
 213 #ifndef U_HIDE_INTERNAL_API
 214     /**
 215      * Apple-specific for now.
 216      * Like formatMeasures above, but with a
 217      * FieldPositionIterator* instead of a FieldPosition&
 218      *
 219      * @param measures  Array of measure objects.
 220      * @param measureCount the number of measure objects.
 221      * @param appendTo  Formatted string appended here.
 222      * @param posIter   On return, can be used to iterate over positions
 223      *                  of fields generated by this format call. Field
 224      *                  values are defined in UAMeasureUnit.
 225      * @param status    The error.
 226      * @return appendTo reference
 227      *
 228     * @internal.
 229       */
 230     UnicodeString &formatMeasures(
 231             const Measure *measures,
 232             int32_t measureCount,
 233             UnicodeString &appendTo,
 234             FieldPositionIterator* posIter,
 235             UErrorCode &status) const;
 236
 237    /**
 238      * Apple-specific for now
 239      * @internal.
 240      */
 241     UMeasureFormatWidth getWidth(void) const;
 242
 243 #endif  /* U_HIDE_INTERNAL_API */
 244
 245
 246     /**
 247      * Formats a single measure per unit. An example of such a
 248      * formatted string is 3.5 meters per second.
 249      * @param measure The measure object. In above example, 3.5 meters.
 250      * @param perUnit The per unit. In above example, it is
 251      *        `*%MeasureUnit::createSecond(status)`.
 252      * @param appendTo formatted string appended here.
 253      * @param pos the field position.
 254      * @param status the error.
 255      * @return appendTo reference
 256      *
 257      * @stable ICU 55
 258      */
 259     UnicodeString &formatMeasurePerUnit(
 260             const Measure &measure,
 261             const MeasureUnit &perUnit,
 262             UnicodeString &appendTo,
 263             FieldPosition &pos,
 264             UErrorCode &status) const;
 265
 266     /**
 267      * Gets the display name of the specified {@link MeasureUnit} corresponding to the current
 268      * locale and format width.
 269      * @param unit  The unit for which to get a display name.
 270      * @param status the error.
 271      * @return  The display name in the locale and width specified in
 272      *          the MeasureFormat constructor, or null if there is no display name available
 273      *          for the specified unit.
 274      *
 275      * @stable ICU 58
 276      */
 277     UnicodeString getUnitDisplayName(const MeasureUnit& unit, UErrorCode &status) const;
 278
 279
 280     /**
 281      * Return a formatter for CurrencyAmount objects in the given
 282      * locale.
 283      * <p>
 284      * <strong>NOTE:</strong> New users are strongly encouraged to use
 285      * {@link icu::number::NumberFormatter} instead of NumberFormat.
 286      * @param locale desired locale
 287      * @param ec input-output error code
 288      * @return a formatter object, or NULL upon error
 289      * @stable ICU 3.0
 290      */
 291     static MeasureFormat* U_EXPORT2 createCurrencyFormat(const Locale& locale,
 292                                                UErrorCode& ec);
 293
 294     /**
 295      * Return a formatter for CurrencyAmount objects in the default
 296      * locale.
 297      * <p>
 298      * <strong>NOTE:</strong> New users are strongly encouraged to use
 299      * {@link icu::number::NumberFormatter} instead of NumberFormat.
 300      * @param ec input-output error code
 301      * @return a formatter object, or NULL upon error
 302      * @stable ICU 3.0
 303      */
 304     static MeasureFormat* U_EXPORT2 createCurrencyFormat(UErrorCode& ec);
 305
 306     /**
 307      * Return the class ID for this class. This is useful only for comparing to
 308      * a return value from getDynamicClassID(). For example:
 309      * <pre>
 310      * .   Base* polymorphic_pointer = createPolymorphicObject();
 311      * .   if (polymorphic_pointer->getDynamicClassID() ==
 312      * .       erived::getStaticClassID()) ...
 313      * </pre>
 314      * @return          The class ID for all objects of this class.
 315      * @stable ICU 53
 316      */
 317     static UClassID U_EXPORT2 getStaticClassID(void);
 318
 319     /**
 320      * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
 321      * method is to implement a simple version of RTTI, since not all C++
 322      * compilers support genuine RTTI. Polymorphic operator==() and clone()
 323      * methods call this method.
 324      *
 325      * @return          The class ID for this object. All objects of a
 326      *                  given class have the same class ID.  Objects of
 327      *                  other classes have different class IDs.
 328      * @stable ICU 53
 329      */
 330     virtual UClassID getDynamicClassID(void) const;
 331
 332  protected:
 333     /**
 334      * Default constructor.
 335      * @stable ICU 3.0
 336      */
 337     MeasureFormat();
 338
 339 #ifndef U_HIDE_INTERNAL_API
 340
 341     /**
 342      * ICU use only.
 343      * Initialize or change MeasureFormat class from subclass.
 344      * @internal.
 345      */
 346     void initMeasureFormat(
 347             const Locale &locale,
 348             UMeasureFormatWidth width,
 349             NumberFormat *nfToAdopt,
 350             UErrorCode &status);
 351     /**
 352      * ICU use only.
 353      * Allows subclass to change locale. Note that this method also changes
 354      * the NumberFormat object. Returns TRUE if locale changed; FALSE if no
 355      * change was made.
 356      * @internal.
 357      */
 358     UBool setMeasureFormatLocale(const Locale &locale, UErrorCode &status);
 359
 360  public:
 361     // Apple-only, temporarily public for Apple use
 362     /**
 363      * ICU use only.
 364      * Let subclass change NumberFormat.
 365      * @internal Apple
 366      */
 367     void adoptNumberFormat(NumberFormat *nfToAdopt, UErrorCode &status);
 368
 369     /**
 370      * Gets the display name for a unit.
 371      * @param unit The unit whose display name to get.
 372      * @param result Receives the name result, if any (if none,
 373      *               length will be 0)
 374      * @return Reference to result
 375      *
 376      * @internal Apple
 377      */
 378     UnicodeString &getUnitName(
 379             const MeasureUnit* unit,
 380             UnicodeString &result ) const;
 381
 382     /**
 383      * Gets the display name for a set of  units.
 384      * @param units Array of units whose display name to get.
 385      * @param unitCount The count of units
 386      * @param listStyle The list style used for combining the unit names.
 387      * @param result Receives the name result, if any (if none,
 388      *               length will be 0)
 389      * @return Reference to result
 390      *
 391      * @internal Apple
 392      */
 393     UnicodeString &getMultipleUnitNames(
 394             const MeasureUnit** units,
 395             int32_t unitCount,
 396             UAMeasureNameListStyle listStyle,
 397             UnicodeString &result ) const;
 398
 399  protected:
 400     /**
 401      * ICU use only.
 402      * @internal.
 403      */
 404     const NumberFormat &getNumberFormatInternal() const;
 405
 406     /**
 407      * ICU use only.
 408      * Always returns the short form currency formatter.
 409      * @internal.
 410      */
 411     const NumberFormat& getCurrencyFormatInternal() const;
 412
 413     /**
 414      * ICU use only.
 415      * @internal.
 416      */
 417     const PluralRules &getPluralRules() const;
 418
 419     /**
 420      * ICU use only.
 421      * @internal.
 422      */
 423     Locale getLocale(UErrorCode &status) const;
 424
 425     /**
 426      * ICU use only.
 427      * @internal.
 428      */
 429     const char *getLocaleID(UErrorCode &status) const;
 430
 431 #endif /* U_HIDE_INTERNAL_API */
 432
 433  private:
 434     const MeasureFormatCacheData *cache;
 435     const SharedNumberFormat *numberFormat;
 436     const SharedPluralRules *pluralRules;
 437     UMeasureFormatWidth fWidth;
 438     UBool stripPatternSpaces;
 439
 440     // Declared outside of MeasureFormatSharedData because ListFormatter
 441     // objects are relatively cheap to copy; therefore, they don't need to be
 442     // shared across instances.
 443     ListFormatter *listFormatter;
 444     ListFormatter *listFormatterStd; // standard list style, option for display names; Apple specific
 445
 446     UnicodeString &formatMeasure(
 447         const Measure &measure,
 448         const NumberFormat &nf,
 449         UnicodeString &appendTo,
 450         FieldPosition &pos,
 451         UErrorCode &status) const;
 452
 453     UnicodeString &formatMeasuresSlowTrack(
 454         const Measure *measures,
 455         int32_t measureCount,
 456         UnicodeString& appendTo,
 457         FieldPosition& pos,
 458         UErrorCode& status) const;
 459
 460     UnicodeString &formatNumeric(
 461         const Formattable *hms,  // always length 3: [0] is hour; [1] is
 462                                  // minute; [2] is second.
 463         int32_t bitMap,   // 1=hour set, 2=minute set, 4=second set
 464         UnicodeString &appendTo,
 465         FieldPositionHandler& handler,
 466         UErrorCode &status) const;
 467
 468     UnicodeString &formatNumeric(
 469         UDate date,
 470         const DateFormat &dateFmt,
 471         UDateFormatField smallestField,
 472         const Formattable &smallestAmount,
 473         UnicodeString &appendTo,
 474         FieldPositionHandler& handler,
 475         UErrorCode &status) const;
 476 };
 477
 478 U_NAMESPACE_END
 479 #endif // U_SHOW_CPLUSPLUS_API
 480
 481 #endif // #if !UCONFIG_NO_FORMATTING
 482 #endif // #ifndef MEASUREFORMAT_H