icuSources/i18n/unicode/measfmt.h

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