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 namespace number {
  31 namespace impl {
  32 class NumberStringBuilder;
  33 }
  34 }
  35
  36 /**
  37  * A plural aware formatter that is good for expressing a single quantity and
  38  * a unit.
  39  * <p>
  40  * First use the add() methods to add a pattern for each plural variant.
  41  * There must be a pattern for the "other" variant.
  42  * Then use the format() method.
  43  * <p>
  44  * Concurrent calls only to const methods on a QuantityFormatter object are
  45  * safe, but concurrent const and non-const method calls on a QuantityFormatter
  46  * object are not safe and require synchronization.
  47  *
  48  */
  49 class U_I18N_API QuantityFormatter : public UMemory {
  50 public:
  51     /**
  52      * Default constructor.
  53      */
  54     QuantityFormatter();
  55
  56     /**
  57      * Copy constructor.
  58      */
  59     QuantityFormatter(const QuantityFormatter& other);
  60
  61     /**
  62      * Assignment operator
  63      */
  64     QuantityFormatter &operator=(const QuantityFormatter& other);
  65
  66     /**
  67      * Destructor.
  68      */
  69     ~QuantityFormatter();
  70
  71     /**
  72      * Removes all variants from this object including the "other" variant.
  73      */
  74     void reset();
  75
  76     /**
  77      * Adds a plural variant if there is none yet for the plural form.
  78      *
  79      * @param variant "zero", "one", "two", "few", "many", "other"
  80      * @param rawPattern the pattern for the variant e.g "{0} meters"
  81      * @param status any error returned here.
  82      * @return TRUE on success; FALSE if status was set to a non zero error.
  83      */
  84     UBool addIfAbsent(const char *variant, const UnicodeString &rawPattern, UErrorCode &status);
  85
  86     /**
  87      * returns TRUE if this object has at least the "other" variant.
  88      */
  89     UBool isValid() const;
  90
  91     /**
  92      * Gets the pattern formatter that would be used for a particular variant.
  93      * If isValid() returns TRUE, this method is guaranteed to return a
  94      * non-NULL value.
  95      */
  96     const SimpleFormatter *getByVariant(const char *variant) const;
  97
  98     /**
  99      * Formats a number with this object appending the result to appendTo.
 100      * At least the "other" variant must be added to this object for this
 101      * method to work.
 102      *
 103      * @param number the single number.
 104      * @param fmt formats the number
 105      * @param rules computes the plural variant to use.
 106      * @param appendTo result appended here.
 107      * @param status any error returned here.
 108      * @return appendTo
 109      */
 110     UnicodeString &format(
 111             const Formattable &number,
 112             const NumberFormat &fmt,
 113             const PluralRules &rules,
 114             UnicodeString &appendTo,
 115             FieldPosition &pos,
 116             UErrorCode &status) const;
 117
 118     /**
 119      * Selects the standard plural form for the number/formatter/rules.
 120      * TODO(13591): Remove this method.
 121      */
 122     static StandardPlural::Form selectPlural(
 123             const Formattable &number,
 124             const NumberFormat &fmt,
 125             const PluralRules &rules,
 126             UnicodeString &formattedNumber,
 127             FieldPosition &pos,
 128             UErrorCode &status);
 129
 130     /**
 131      * Formats a quantity and selects its plural form. The output is appended
 132      * to a NumberStringBuilder in order to retain field information.
 133      *
 134      * @param quantity The number to format.
 135      * @param fmt The formatter to use to format the number.
 136      * @param rules The rules to use to select the plural form of the
 137      *              formatted number.
 138      * @param output Where to append the result of the format operation.
 139      * @param pluralForm Output variable populated with the plural form of the
 140      *                   formatted number.
 141      * @param status Set if an error occurs.
 142      */
 143     static void formatAndSelect(
 144             double quantity,
 145             const NumberFormat& fmt,
 146             const PluralRules& rules,
 147             number::impl::NumberStringBuilder& output,
 148             StandardPlural::Form& pluralForm,
 149             UErrorCode& status);
 150
 151     /**
 152      * Formats the pattern with the value and adjusts the FieldPosition.
 153      * TODO: Remove?
 154      */
 155     static UnicodeString &format(
 156             const SimpleFormatter &pattern,
 157             const UnicodeString &value,
 158             UnicodeString &appendTo,
 159             FieldPosition &pos,
 160             UErrorCode &status);
 161
 162 private:
 163     SimpleFormatter *formatters[StandardPlural::COUNT];
 164 };
 165
 166 U_NAMESPACE_END
 167
 168 #endif
 169
 170 #endif