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