A class that formats numbers according to a set of rules. This number formatter is + * The RuleBasedNumberFormat class formats numbers according to a set of rules. This number formatter is * typically used for spelling out numeric values in words (e.g., 25,3476 as * "twenty-five thousand three hundred seventy-six" or "vingt-cinq mille trois * cents soixante-seize" or * "fünfundzwanzigtausenddreihundertsechsundsiebzig"), but can also be used for * other complicated formatting tasks, such as formatting a number of seconds as hours, - * minutes and seconds (e.g., 3,730 as "1:02:10").
+ * minutes and seconds (e.g., 3,730 as "1:02:10"). * *The resources contain three predefined formatters for each locale: spellout, which * spells out a value in words (123 is "one hundred twenty-three"); ordinal, which @@ -263,17 +274,47 @@ class Collator; * *
The substitution descriptor (i.e., the text between the token characters) may take one @@ -488,14 +547,16 @@ class Collator; *
In the syntax, angle brackets '<', '>' are used to delimit the arrays, and comma ',' is used * to separate elements of an array. Whitespace is ignored, unless quoted.
*For example:
- * < < %foo, %bar, %baz >, - * < en, Foo, Bar, Baz >, - * < fr, 'le Foo', 'le Bar', 'le Baz' > + * < < %foo, %bar, %baz >, + * < en, Foo, Bar, Baz >, + * < fr, 'le Foo', 'le Bar', 'le Baz' > * < zh, \\u7532, \\u4e59, \\u4e19 > > ** @author Richard Gillam * @see NumberFormat * @see DecimalFormat + * @see PluralFormat + * @see PluralRules * @stable ICU 2.0 */ class U_I18N_API RuleBasedNumberFormat : public NumberFormat { @@ -513,13 +574,13 @@ public: * syntax. * @param perror The parse error if an error was encountered. * @param status The status indicating whether the constructor succeeded. - * @draft ICU 3.2 + * @stable ICU 3.2 */ RuleBasedNumberFormat(const UnicodeString& rules, UParseError& perror, UErrorCode& status); /** * Creates a RuleBasedNumberFormat that behaves according to the description - * passed in. The formatter uses the default locale. + * passed in. The formatter uses the default locale. *
* The localizations data provides information about the public * rule sets and their localized display names for different @@ -538,7 +599,7 @@ public: * names in the description. These will be copied by the constructor. * @param perror The parse error if an error was encountered. * @param status The status indicating whether the constructor succeeded. - * @draft ICU 3.2 + * @stable ICU 3.2 */ RuleBasedNumberFormat(const UnicodeString& rules, const UnicodeString& localizations, UParseError& perror, UErrorCode& status); @@ -563,7 +624,7 @@ public: /** * Creates a RuleBasedNumberFormat that behaves according to the description - * passed in. The formatter uses the default locale. + * passed in. The formatter uses the default locale. *
* The localizations data provides information about the public * rule sets and their localized display names for different @@ -585,7 +646,7 @@ public: * lenient parsing. * @param perror The parse error if an error was encountered. * @param status The status indicating whether the constructor succeeded. - * @draft ICU 3.2 + * @stable ICU 3.2 */ RuleBasedNumberFormat(const UnicodeString& rules, const UnicodeString& localizations, const Locale& locale, UParseError& perror, UErrorCode& status); @@ -595,10 +656,12 @@ public: * code choosed among three possible predefined formats: spellout, ordinal, * and duration. * @param tag A selector code specifying which kind of formatter to create for that - * locale. There are three legal values: URBNF_SPELLOUT, which creates a formatter that + * locale. There are four legal values: URBNF_SPELLOUT, which creates a formatter that * spells out a value in words in the desired language, URBNF_ORDINAL, which attaches * an ordinal suffix from the desired language to the end of a number (e.g. "123rd"), - * and URBNF_DURATION, which formats a duration in seconds as hours, minutes, and seconds. + * URBNF_DURATION, which formats a duration in seconds as hours, minutes, and seconds always rounding down, + * and URBNF_NUMBERING_SYSTEM, which is used to invoke rules for alternate numbering + * systems such as the Hebrew numbering system, or for Roman Numerals, etc. * @param locale The locale for the formatter. * @param status The status indicating whether the constructor succeeded. * @stable ICU 2.0 @@ -676,7 +739,7 @@ public: /** * Return the number of locales for which we have localized rule set display names. * @return the number of locales for which we have localized rule set display names. - * @draft ICU 3.2 + * @stable ICU 3.2 */ virtual int32_t getNumberOfRuleSetDisplayNameLocales(void) const; @@ -686,14 +749,14 @@ public: * @param status set to a failure code when this function fails * @return the locale * @see #getNumberOfRuleSetDisplayNameLocales - * @draft ICU 3.2 + * @stable ICU 3.2 */ virtual Locale getRuleSetDisplayNameLocale(int32_t index, UErrorCode& status) const; /** * Return the rule set display names for the provided locale. These are in the same order * as those returned by getRuleSetName. The locale is matched against the locales for - * which there is display name data, using normal fallback rules. If no locale matches, + * which there is display name data, using normal fallback rules. If no locale matches, * the default display names are returned. (These are the internal rule set names minus * the leading '%'.) * @param index the index of the rule set @@ -701,22 +764,25 @@ public: * display name is desired * @return the display name for the given index, which might be bogus if there is an error * @see #getRuleSetName - * @draft ICU 3.2 + * @stable ICU 3.2 */ - virtual UnicodeString getRuleSetDisplayName(int32_t index, + virtual UnicodeString getRuleSetDisplayName(int32_t index, const Locale& locale = Locale::getDefault()); /** - * Return the rule set display name for the provided rule set and locale. + * Return the rule set display name for the provided rule set and locale. * The locale is matched against the locales for which there is display name data, using * normal fallback rules. If no locale matches, the default display name is returned. * @return the display name for the rule set - * @draft ICU 3.2 - * @see #getRuleSetDisplayNames + * @stable ICU 3.2 + * @see #getRuleSetDisplayName */ - virtual UnicodeString getRuleSetDisplayName(const UnicodeString& ruleSetName, + virtual UnicodeString getRuleSetDisplayName(const UnicodeString& ruleSetName, const Locale& locale = Locale::getDefault()); + + using NumberFormat::format; + /** * Formats the specified 32-bit number using the default ruleset. * @param number The number to format. @@ -801,50 +867,53 @@ public: FieldPosition& pos, UErrorCode& status) const; - /** - * Formats the specified number using the default ruleset. - * @param obj The number to format. - * @param toAppendTo the string that will hold the (appended) result - * @param pos the fieldposition - * @param status the status - * @return A textual representation of the number. - * @stable ICU 2.0 - */ - virtual UnicodeString& format(const Formattable& obj, - UnicodeString& toAppendTo, - FieldPosition& pos, - UErrorCode& status) const; - /** - * Redeclared Format method. - * @param obj the object to be formatted. - * @param result Output param which will receive the formatted string. - * @param status Output param set to success/failure code - * @return A reference to 'result'. - * @stable ICU 2.0 - */ - UnicodeString& format(const Formattable& obj, - UnicodeString& result, - UErrorCode& status) const; +protected: + /** + * Format a decimal number. + * The number is a DigitList wrapper onto a floating point decimal number. + * The default implementation in NumberFormat converts the decimal number + * to a double and formats that. Subclasses of NumberFormat that want + * to specifically handle big decimal numbers must override this method. + * class DecimalFormat does so. + * + * @param number The number, a DigitList format Decimal Floating Point. + * @param appendTo Output parameter to receive result. + * Result is appended to existing contents. + * @param posIter On return, can be used to iterate over positions + * of fields generated by this format call. + * @param status Output param filled with success/failure status. + * @return Reference to 'appendTo' parameter. + * @internal + */ + virtual UnicodeString& format(const DigitList &number, + UnicodeString& appendTo, + FieldPositionIterator* posIter, + UErrorCode& status) const; - /** - * Redeclared NumberFormat method. - * @param number the double value to be formatted. - * @param output Output param which will receive the formatted string. - * @return A reference to 'output'. - * @stable ICU 2.0 - */ - UnicodeString& format(double number, - UnicodeString& output) const; + /** + * Format a decimal number. + * The number is a DigitList wrapper onto a floating point decimal number. + * The default implementation in NumberFormat converts the decimal number + * to a double and formats that. Subclasses of NumberFormat that want + * to specifically handle big decimal numbers must override this method. + * class DecimalFormat does so. + * + * @param number The number, a DigitList format Decimal Floating Point. + * @param appendTo Output parameter to receive result. + * Result is appended to existing contents. + * @param pos On input: an alignment field, if desired. + * On output: the offsets of the alignment field. + * @param status Output param filled with success/failure status. + * @return Reference to 'appendTo' parameter. + * @internal + */ + virtual UnicodeString& format(const DigitList &number, + UnicodeString& appendTo, + FieldPosition& pos, + UErrorCode& status) const; +public: - /** - * Redeclared NumberFormat method. - * @param number the long value to be formatted. - * @param output Output param which will receive the formatted string. - * @return A reference to 'output'. - * @stable ICU 2.0 - */ - UnicodeString& format(int32_t number, - UnicodeString& output) const; + using NumberFormat::parse; /** * Parses the specfied string, beginning at the specified position, according @@ -857,25 +926,13 @@ public: * @param parsePosition On entry, contains the position of the first character * in "text" to examine. On exit, has been updated to contain the position * of the first character in "text" that wasn't consumed by the parse. - * @see #setLenientParseMode + * @see #setLenient * @stable ICU 2.0 */ virtual void parse(const UnicodeString& text, Formattable& result, ParsePosition& parsePosition) const; - - /** - * Redeclared Format method. - * @param text The string to parse - * @param result the result of the parse, either a double or a long. - * @param status Output param set to failure code when a problem occurs. - * @stable ICU 2.0 - */ - virtual inline void parse(const UnicodeString& text, - Formattable& result, - UErrorCode& status) const; - #if !UCONFIG_NO_COLLATION /** @@ -917,7 +974,7 @@ public: * Returns true if lenient-parse mode is turned on. Lenient parsing is off * by default. * @return true if lenient-parse mode is turned on. - * @see #setLenientParseMode + * @see #setLenient * @stable ICU 2.0 */ virtual inline UBool isLenient(void) const; @@ -938,10 +995,22 @@ public: * Return the name of the current default rule set. If the current rule set is * not public, returns a bogus (and empty) UnicodeString. * @return the name of the current default rule set - * @draft ICU 3.0 + * @stable ICU 3.0 */ virtual UnicodeString getDefaultRuleSetName() const; + /** + * Set a particular UDisplayContext value in the formatter, such as + * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. Note: For getContext, see + * NumberFormat. + * @param value The UDisplayContext value to set. + * @param status Input/output status. If at entry this indicates a failure + * status, the function will do nothing; otherwise this will be + * updated with any new status from the function. + * @stable ICU 53 + */ + virtual void setContext(UDisplayContext value, UErrorCode& status); + public: /** * ICU "poor man's RTTI", returns a UClassID for this class. @@ -957,15 +1026,37 @@ public: */ virtual UClassID getDynamicClassID(void) const; + /** + * Sets the decimal format symbols, which is generally not changed + * by the programmer or user. The formatter takes ownership of + * symbolsToAdopt; the client must not delete it. + * + * @param symbolsToAdopt DecimalFormatSymbols to be adopted. + * @stable ICU 49 + */ + virtual void adoptDecimalFormatSymbols(DecimalFormatSymbols* symbolsToAdopt); + + /** + * Sets the decimal format symbols, which is generally not changed + * by the programmer or user. A clone of the symbols is created and + * the symbols is _not_ adopted; the client is still responsible for + * deleting it. + * + * @param symbols DecimalFormatSymbols. + * @stable ICU 49 + */ + virtual void setDecimalFormatSymbols(const DecimalFormatSymbols& symbols); + private: RuleBasedNumberFormat(); // default constructor not implemented // this will ref the localizations if they are not NULL - // caller must deref to get adoption - RuleBasedNumberFormat(const UnicodeString& description, LocalizationInfo* localizations, + // caller must deref to get adoption + RuleBasedNumberFormat(const UnicodeString& description, LocalizationInfo* localizations, const Locale& locale, UParseError& perror, UErrorCode& status); void init(const UnicodeString& rules, LocalizationInfo* localizations, UParseError& perror, UErrorCode& status); + void initCapitalizationContextInfo(const Locale& thelocale); void dispose(); void stripWhitespace(UnicodeString& src); void initDefaultRuleSet(); @@ -975,56 +1066,43 @@ private: /* friend access */ friend class NFSubstitution; friend class NFRule; + friend class NFRuleSet; friend class FractionalPartSubstitution; inline NFRuleSet * getDefaultRuleSet() const; - Collator * getCollator() const; - DecimalFormatSymbols * getDecimalFormatSymbols() const; + const RuleBasedCollator * getCollator() const; + DecimalFormatSymbols * initializeDecimalFormatSymbols(UErrorCode &status); + const DecimalFormatSymbols * getDecimalFormatSymbols() const; + NFRule * initializeDefaultInfinityRule(UErrorCode &status); + const NFRule * getDefaultInfinityRule() const; + NFRule * initializeDefaultNaNRule(UErrorCode &status); + const NFRule * getDefaultNaNRule() const; + PluralFormat *createPluralFormat(UPluralType pluralType, const UnicodeString &pattern, UErrorCode& status) const; + UnicodeString& adjustForCapitalizationContext(int32_t startPos, UnicodeString& currentResult, UErrorCode& status) const; + UnicodeString& format(int64_t number, NFRuleSet *ruleSet, UnicodeString& toAppendTo, UErrorCode& status) const; private: NFRuleSet **ruleSets; + UnicodeString* ruleSetDescriptions; + int32_t numRuleSets; NFRuleSet *defaultRuleSet; Locale locale; - Collator* collator; + RuleBasedCollator* collator; DecimalFormatSymbols* decimalFormatSymbols; + NFRule *defaultInfinityRule; + NFRule *defaultNaNRule; UBool lenient; UnicodeString* lenientParseRules; LocalizationInfo* localizations; + UnicodeString originalDescription; + UBool capitalizationInfoSet; + UBool capitalizationForUIListMenu; + UBool capitalizationForStandAlone; + BreakIterator* capitalizationBrkIter; }; // --------------- -inline UnicodeString& -RuleBasedNumberFormat::format(const Formattable& obj, - UnicodeString& result, - UErrorCode& status) const -{ - // Don't use Format:: - use immediate base class only, - // in case immediate base modifies behavior later. - // dlf - the above comment is bogus, if there were a reason to modify - // it, it would be virtual, and there's no reason because it is - // a one-line macro in NumberFormat anyway, just like this one. - return NumberFormat::format(obj, result, status); -} - -inline UnicodeString& -RuleBasedNumberFormat::format(double number, UnicodeString& output) const { - FieldPosition pos(0); - return format(number, output, pos); -} - -inline UnicodeString& -RuleBasedNumberFormat::format(int32_t number, UnicodeString& output) const { - FieldPosition pos(0); - return format(number, output, pos); -} - -inline void -RuleBasedNumberFormat::parse(const UnicodeString& text, Formattable& result, UErrorCode& status) const -{ - NumberFormat::parse(text, result, status); -} - #if !UCONFIG_NO_COLLATION inline UBool @@ -1040,6 +1118,7 @@ RuleBasedNumberFormat::getDefaultRuleSet() const { } U_NAMESPACE_END +#endif // U_SHOW_CPLUSPLUS_API /* U_HAVE_RBNF */ #endif