icuSources/i18n/quantityformatter.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) 2014-2016, International Business Machines
   6 * Corporation and others.  All Rights Reserved.
   7 ******************************************************************************
   8 * quantityformatter.h
   9 */
  10
  11 #ifndef __QUANTITY_FORMATTER_H__
  12 #define __QUANTITY_FORMATTER_H__
  13
  14 #include "unicode/utypes.h"
  15 #include "unicode/uobject.h"
  16
  17 #if !UCONFIG_NO_FORMATTING
  18
  19 #include "standardplural.h"
  20
  21 U_NAMESPACE_BEGIN
  22
  23 class SimpleFormatter;
  24 class UnicodeString;
  25 class PluralRules;
  26 class NumberFormat;
  27 class Formattable;
  28 class FieldPosition;
  29
  30 /**
  31  * A plural aware formatter that is good for expressing a single quantity and
  32  * a unit.
  33  * <p>
  34  * First use the add() methods to add a pattern for each plural variant.
  35  * There must be a pattern for the "other" variant.
  36  * Then use the format() method.
  37  * <p>
  38  * Concurrent calls only to const methods on a QuantityFormatter object are
  39  * safe, but concurrent const and non-const method calls on a QuantityFormatter
  40  * object are not safe and require synchronization.
  41  *
  42  */
  43 class U_I18N_API QuantityFormatter : public UMemory {
  44 public:
  45     /**
  46      * Default constructor.
  47      */
  48     QuantityFormatter();
  49
  50     /**
  51      * Copy constructor.
  52      */
  53     QuantityFormatter(const QuantityFormatter& other);
  54
  55     /**
  56      * Assignment operator
  57      */
  58     QuantityFormatter &operator=(const QuantityFormatter& other);
  59
  60     /**
  61      * Destructor.
  62      */
  63     ~QuantityFormatter();
  64
  65     /**
  66      * Removes all variants from this object including the "other" variant.
  67      */
  68     void reset();
  69
  70     /**
  71      * Adds a plural variant if there is none yet for the plural form.
  72      *
  73      * @param variant "zero", "one", "two", "few", "many", "other"
  74      * @param rawPattern the pattern for the variant e.g "{0} meters"
  75      * @param status any error returned here.
  76      * @return TRUE on success; FALSE if status was set to a non zero error.
  77      */
  78     UBool addIfAbsent(const char *variant, const UnicodeString &rawPattern, UErrorCode &status);
  79
  80     /**
  81      * returns TRUE if this object has at least the "other" variant.
  82      */
  83     UBool isValid() const;
  84
  85     /**
  86      * Gets the pattern formatter that would be used for a particular variant.
  87      * If isValid() returns TRUE, this method is guaranteed to return a
  88      * non-NULL value.
  89      */
  90     const SimpleFormatter *getByVariant(const char *variant) const;
  91
  92     /**
  93      * Formats a number with this object appending the result to appendTo.
  94      * At least the "other" variant must be added to this object for this
  95      * method to work.
  96      *
  97      * @param number the single number.
  98      * @param fmt formats the number
  99      * @param rules computes the plural variant to use.
 100      * @param appendTo result appended here.
 101      * @param status any error returned here.
 102      * @return appendTo
 103      */
 104     UnicodeString &format(
 105             const Formattable &number,
 106             const NumberFormat &fmt,
 107             const PluralRules &rules,
 108             UnicodeString &appendTo,
 109             FieldPosition &pos,
 110             UErrorCode &status) const;
 111
 112     /**
 113      * Selects the standard plural form for the number/formatter/rules.
 114      */
 115     static StandardPlural::Form selectPlural(
 116             const Formattable &number,
 117             const NumberFormat &fmt,
 118             const PluralRules &rules,
 119             UnicodeString &formattedNumber,
 120             FieldPosition &pos,
 121             UErrorCode &status);
 122
 123     /**
 124      * Formats the pattern with the value and adjusts the FieldPosition.
 125      */
 126     static UnicodeString &format(
 127             const SimpleFormatter &pattern,
 128             const UnicodeString &value,
 129             UnicodeString &appendTo,
 130             FieldPosition &pos,
 131             UErrorCode &status);
 132
 133 private:
 134     SimpleFormatter *formatters[StandardPlural::COUNT];
 135 };
 136
 137 U_NAMESPACE_END
 138
 139 #endif
 140
 141 #endif