icuSources/i18n/unicode/measfmt.h

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