util/X86MAC64/include/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
  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 };
  74 /** @stable ICU 53 */
  75 typedef enum UMeasureFormatWidth UMeasureFormatWidth;
  76
  77 U_NAMESPACE_BEGIN
  78
  79 class Measure;
  80 class MeasureUnit;
  81 class NumberFormat;
  82 class PluralRules;
  83 class MeasureFormatCacheData;
  84 class SharedNumberFormat;
  85 class SharedPluralRules;
  86 class QuantityFormatter;
  87 class SimpleFormatter;
  88 class ListFormatter;
  89 class DateFormat;
  90
  91 /**
  92  * <p><strong>IMPORTANT:</strong> New users are strongly encouraged to see if
  93  * numberformatter.h fits their use case.  Although not deprecated, this header
  94  * is provided for backwards compatibility only, and has much more limited
  95  * capabilities.
  96  *
  97  * @see Format
  98  * @author Alan Liu
  99  * @stable ICU 3.0
 100  */
 101 class U_I18N_API MeasureFormat : public Format {
 102  public:
 103     using Format::parseObject;
 104     using Format::format;
 105
 106     /**
 107      * Constructor.
 108      * <p>
 109      * <strong>NOTE:</strong> New users are strongly encouraged to use
 110      * {@link icu::number::NumberFormatter} instead of NumberFormat.
 111      * @stable ICU 53
 112      */
 113     MeasureFormat(
 114             const Locale &locale, UMeasureFormatWidth width, UErrorCode &status);
 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,
 125             UMeasureFormatWidth width,
 126             NumberFormat *nfToAdopt,
 127             UErrorCode &status);
 128
 129     /**
 130      * Copy constructor.
 131      * @stable ICU 3.0
 132      */
 133     MeasureFormat(const MeasureFormat &other);
 134
 135     /**
 136      * Assignment operator.
 137      * @stable ICU 3.0
 138      */
 139     MeasureFormat &operator=(const MeasureFormat &rhs);
 140
 141     /**
 142      * Destructor.
 143      * @stable ICU 3.0
 144      */
 145     virtual ~MeasureFormat();
 146
 147     /**
 148      * Return true if given Format objects are semantically equal.
 149      * @stable ICU 53
 150      */
 151     virtual bool operator==(const Format &other) const override;
 152
 153     /**
 154      * Clones this object polymorphically.
 155      * @stable ICU 53
 156      */
 157     virtual MeasureFormat *clone() const override;
 158
 159     /**
 160      * Formats object to produce a string.
 161      * @stable ICU 53
 162      */
 163     virtual UnicodeString &format(
 164             const Formattable &obj,
 165             UnicodeString &appendTo,
 166             FieldPosition &pos,
 167             UErrorCode &status) const override;
 168
 169 #ifndef U_FORCE_HIDE_DRAFT_API
 170     /**
 171      * Parse a string to produce an object. This implementation sets
 172      * status to U_UNSUPPORTED_ERROR.
 173      *
 174      * @draft ICU 53
 175      */
 176     virtual void parseObject(
 177             const UnicodeString &source,
 178             Formattable &reslt,
 179             ParsePosition &pos) const override;
 180 #endif  // U_FORCE_HIDE_DRAFT_API
 181
 182     /**
 183      * Formats measure objects to produce a string. An example of such a
 184      * formatted string is 3 meters, 3.5 centimeters. Measure objects appear
 185      * in the formatted string in the same order they appear in the "measures"
 186      * array. The NumberFormat of this object is used only to format the amount
 187      * of the very last measure. The other amounts are formatted with zero
 188      * decimal places while rounding toward zero.
 189      * @param measures array of measure objects.
 190      * @param measureCount the number of measure objects.
 191      * @param appendTo formatted string appended here.
 192      * @param pos the field position.
 193      * @param status the error.
 194      * @return appendTo reference
 195      *
 196      * @stable ICU 53
 197      */
 198     UnicodeString &formatMeasures(
 199             const Measure *measures,
 200             int32_t measureCount,
 201             UnicodeString &appendTo,
 202             FieldPosition &pos,
 203             UErrorCode &status) const;
 204
 205     /**
 206      * Formats a single measure per unit. An example of such a
 207      * formatted string is 3.5 meters per second.
 208      * @param measure The measure object. In above example, 3.5 meters.
 209      * @param perUnit The per unit. In above example, it is
 210      *        `*%MeasureUnit::createSecond(status)`.
 211      * @param appendTo formatted string appended here.
 212      * @param pos the field position.
 213      * @param status the error.
 214      * @return appendTo reference
 215      *
 216      * @stable ICU 55
 217      */
 218     UnicodeString &formatMeasurePerUnit(
 219             const Measure &measure,
 220             const MeasureUnit &perUnit,
 221             UnicodeString &appendTo,
 222             FieldPosition &pos,
 223             UErrorCode &status) const;
 224
 225     /**
 226      * Gets the display name of the specified {@link MeasureUnit} corresponding to the current
 227      * locale and format width.
 228      * @param unit  The unit for which to get a display name.
 229      * @param status the error.
 230      * @return  The display name in the locale and width specified in
 231      *          the MeasureFormat constructor, or null if there is no display name available
 232      *          for the specified unit.
 233      *
 234      * @stable ICU 58
 235      */
 236     UnicodeString getUnitDisplayName(const MeasureUnit& unit, UErrorCode &status) const;
 237
 238
 239     /**
 240      * Return a formatter for CurrencyAmount objects in the given
 241      * locale.
 242      * <p>
 243      * <strong>NOTE:</strong> New users are strongly encouraged to use
 244      * {@link icu::number::NumberFormatter} instead of NumberFormat.
 245      * @param locale desired locale
 246      * @param ec input-output error code
 247      * @return a formatter object, or NULL upon error
 248      * @stable ICU 3.0
 249      */
 250     static MeasureFormat* U_EXPORT2 createCurrencyFormat(const Locale& locale,
 251                                                UErrorCode& ec);
 252
 253     /**
 254      * Return a formatter for CurrencyAmount objects in the default
 255      * locale.
 256      * <p>
 257      * <strong>NOTE:</strong> New users are strongly encouraged to use
 258      * {@link icu::number::NumberFormatter} instead of NumberFormat.
 259      * @param ec input-output error code
 260      * @return a formatter object, or NULL upon error
 261      * @stable ICU 3.0
 262      */
 263     static MeasureFormat* U_EXPORT2 createCurrencyFormat(UErrorCode& ec);
 264
 265     /**
 266      * Return the class ID for this class. This is useful only for comparing to
 267      * a return value from getDynamicClassID(). For example:
 268      * <pre>
 269      * .   Base* polymorphic_pointer = createPolymorphicObject();
 270      * .   if (polymorphic_pointer->getDynamicClassID() ==
 271      * .       erived::getStaticClassID()) ...
 272      * </pre>
 273      * @return          The class ID for all objects of this class.
 274      * @stable ICU 53
 275      */
 276     static UClassID U_EXPORT2 getStaticClassID(void);
 277
 278     /**
 279      * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
 280      * method is to implement a simple version of RTTI, since not all C++
 281      * compilers support genuine RTTI. Polymorphic operator==() and clone()
 282      * methods call this method.
 283      *
 284      * @return          The class ID for this object. All objects of a
 285      *                  given class have the same class ID.  Objects of
 286      *                  other classes have different class IDs.
 287      * @stable ICU 53
 288      */
 289     virtual UClassID getDynamicClassID(void) const override;
 290
 291  protected:
 292     /**
 293      * Default constructor.
 294      * @stable ICU 3.0
 295      */
 296     MeasureFormat();
 297
 298 #ifndef U_HIDE_INTERNAL_API
 299
 300     /**
 301      * ICU use only.
 302      * Initialize or change MeasureFormat class from subclass.
 303      * @internal.
 304      */
 305     void initMeasureFormat(
 306             const Locale &locale,
 307             UMeasureFormatWidth width,
 308             NumberFormat *nfToAdopt,
 309             UErrorCode &status);
 310     /**
 311      * ICU use only.
 312      * Allows subclass to change locale. Note that this method also changes
 313      * the NumberFormat object. Returns true if locale changed; false if no
 314      * change was made.
 315      * @internal.
 316      */
 317     UBool setMeasureFormatLocale(const Locale &locale, UErrorCode &status);
 318
 319     /**
 320      * ICU use only.
 321      * Let subclass change NumberFormat.
 322      * @internal.
 323      */
 324     void adoptNumberFormat(NumberFormat *nfToAdopt, UErrorCode &status);
 325
 326     /**
 327      * ICU use only.
 328      * @internal.
 329      */
 330     const NumberFormat &getNumberFormatInternal() const;
 331
 332     /**
 333      * ICU use only.
 334      * Always returns the short form currency formatter.
 335      * @internal.
 336      */
 337     const NumberFormat& getCurrencyFormatInternal() const;
 338
 339     /**
 340      * ICU use only.
 341      * @internal.
 342      */
 343     const PluralRules &getPluralRules() const;
 344
 345     /**
 346      * ICU use only.
 347      * @internal.
 348      */
 349     Locale getLocale(UErrorCode &status) const;
 350
 351     /**
 352      * ICU use only.
 353      * @internal.
 354      */
 355     const char *getLocaleID(UErrorCode &status) const;
 356
 357 #endif /* U_HIDE_INTERNAL_API */
 358
 359  private:
 360     const MeasureFormatCacheData *cache;
 361     const SharedNumberFormat *numberFormat;
 362     const SharedPluralRules *pluralRules;
 363     UMeasureFormatWidth fWidth;
 364
 365     // Declared outside of MeasureFormatSharedData because ListFormatter
 366     // objects are relatively cheap to copy; therefore, they don't need to be
 367     // shared across instances.
 368     ListFormatter *listFormatter;
 369
 370     UnicodeString &formatMeasure(
 371         const Measure &measure,
 372         const NumberFormat &nf,
 373         UnicodeString &appendTo,
 374         FieldPosition &pos,
 375         UErrorCode &status) const;
 376
 377     UnicodeString &formatMeasuresSlowTrack(
 378         const Measure *measures,
 379         int32_t measureCount,
 380         UnicodeString& appendTo,
 381         FieldPosition& pos,
 382         UErrorCode& status) const;
 383
 384     UnicodeString &formatNumeric(
 385         const Formattable *hms,  // always length 3: [0] is hour; [1] is
 386                                  // minute; [2] is second.
 387         int32_t bitMap,   // 1=hour set, 2=minute set, 4=second set
 388         UnicodeString &appendTo,
 389         UErrorCode &status) const;
 390 };
 391
 392 U_NAMESPACE_END
 393
 394 #endif // #if !UCONFIG_NO_FORMATTING
 395
 396 #endif /* U_SHOW_CPLUSPLUS_API */
 397
 398 #endif // #ifndef MEASUREFORMAT_H