ICU 72.1 72.1
Public Member Functions | Static Public Member Functions | Friends
icu::ChoiceFormat Class Reference

ChoiceFormat converts between ranges of numeric values and strings for those ranges. More...

#include <choicfmt.h>

Inheritance diagram for icu::ChoiceFormat:
icu::NumberFormat icu::Format icu::UObject icu::UMemory

Public Member Functions

 ChoiceFormat (const UnicodeString &pattern, UErrorCode &status)
 Constructs a new ChoiceFormat from the pattern string. More...
 
 ChoiceFormat (const double *limits, const UnicodeString *formats, int32_t count)
 Constructs a new ChoiceFormat with the given limits and message strings. More...
 
 ChoiceFormat (const double *limits, const UBool *closures, const UnicodeString *formats, int32_t count)
 Constructs a new ChoiceFormat with the given limits, closure flags and message strings. More...
 
 ChoiceFormat (const ChoiceFormat &that)
 Copy constructor. More...
 
const ChoiceFormatoperator= (const ChoiceFormat &that)
 Assignment operator. More...
 
virtual ~ChoiceFormat ()
 Destructor. More...
 
virtual ChoiceFormatclone () const override
 Clones this Format object. More...
 
virtual bool operator== (const Format &other) const override
 Returns true if the given Format objects are semantically equal. More...
 
virtual void applyPattern (const UnicodeString &pattern, UErrorCode &status)
 Sets the pattern. More...
 
virtual void applyPattern (const UnicodeString &pattern, UParseError &parseError, UErrorCode &status)
 Sets the pattern. More...
 
virtual UnicodeStringtoPattern (UnicodeString &pattern) const
 Gets the pattern. More...
 
virtual void setChoices (const double *limitsToCopy, const UnicodeString *formatsToCopy, int32_t count)
 Sets the choices to be used in formatting. More...
 
virtual void setChoices (const double *limits, const UBool *closures, const UnicodeString *formats, int32_t count)
 Sets the choices to be used in formatting. More...
 
virtual const double * getLimits (int32_t &count) const
 Returns NULL and 0. More...
 
virtual const UBoolgetClosures (int32_t &count) const
 Returns NULL and 0. More...
 
virtual const UnicodeStringgetFormats (int32_t &count) const
 Returns NULL and 0. More...
 
virtual UnicodeStringformat (double number, UnicodeString &appendTo, FieldPosition &pos) const override
 Formats a double number using this object's choices. More...
 
virtual UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPosition &pos) const override
 Formats an int32_t number using this object's choices. More...
 
virtual UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPosition &pos) const override
 Formats an int64_t number using this object's choices. More...
 
virtual UnicodeStringformat (const Formattable *objs, int32_t cnt, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &success) const
 Formats an array of objects using this object's choices. More...
 
virtual void parse (const UnicodeString &text, Formattable &result, ParsePosition &parsePosition) const override
 Looks for the longest match of any message string on the input text and, if there is a match, sets the result object to the corresponding range's number. More...
 
virtual UClassID getDynamicClassID (void) const override
 Returns a unique class ID POLYMORPHICALLY. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const override
 Format an object to produce a string. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const override
 Format an object to produce a string. More...
 
UnicodeStringformat (double number, UnicodeString &appendTo) const
 Format a double number. More...
 
UnicodeStringformat (int32_t number, UnicodeString &appendTo) const
 Format a long number. More...
 
UnicodeStringformat (int64_t number, UnicodeString &appendTo) const
 Format an int64 number. More...
 
virtual UnicodeStringformat (double number, UnicodeString &appendTo, FieldPosition &pos) const=0
 Format a double number. More...
 
virtual UnicodeStringformat (double number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format a double number. More...
 
virtual UnicodeStringformat (double number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format a double number. More...
 
virtual UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPosition &pos) const=0
 Format a long number. More...
 
virtual UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format a long number. More...
 
virtual UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format an int32 number. More...
 
virtual UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPosition &pos) const
 Format an int64 number. More...
 
virtual UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format an int64 number. More...
 
virtual UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format an int64 number. More...
 
virtual UnicodeStringformat (StringPiece number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format a decimal number. More...
 
virtual UnicodeStringformat (const number::impl::DecimalQuantity &number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format a decimal number. More...
 
virtual UnicodeStringformat (const number::impl::DecimalQuantity &number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format a decimal number. More...
 
virtual void parse (const UnicodeString &text, Formattable &result, ParsePosition &parsePosition) const=0
 Return a long if possible (e.g. More...
 
virtual void parse (const UnicodeString &text, Formattable &result, UErrorCode &status) const
 Parse a string as a numeric value, and return a Formattable numeric object. More...
 
- Public Member Functions inherited from icu::NumberFormat
virtual ~NumberFormat ()
 Destructor. More...
 
virtual NumberFormatclone () const override=0
 Clones this object polymorphically. More...
 
virtual bool operator== (const Format &other) const override
 Return true if the given Format objects are semantically equal. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const override
 Format an object to produce a string. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const override
 Format an object to produce a string. More...
 
virtual void parseObject (const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const override
 Parse a string to produce an object. More...
 
UnicodeStringformat (double number, UnicodeString &appendTo) const
 Format a double number. More...
 
UnicodeStringformat (int32_t number, UnicodeString &appendTo) const
 Format a long number. More...
 
UnicodeStringformat (int64_t number, UnicodeString &appendTo) const
 Format an int64 number. More...
 
virtual UnicodeStringformat (double number, UnicodeString &appendTo, FieldPosition &pos) const =0
 Format a double number. More...
 
virtual UnicodeStringformat (double number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format a double number. More...
 
virtual UnicodeStringformat (double number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format a double number. More...
 
virtual UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPosition &pos) const =0
 Format a long number. More...
 
virtual UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format a long number. More...
 
virtual UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format an int32 number. More...
 
virtual UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPosition &pos) const
 Format an int64 number. More...
 
virtual UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format an int64 number. More...
 
virtual UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format an int64 number. More...
 
virtual UnicodeStringformat (StringPiece number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format a decimal number. More...
 
virtual UnicodeStringformat (const number::impl::DecimalQuantity &number, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format a decimal number. More...
 
virtual UnicodeStringformat (const number::impl::DecimalQuantity &number, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format a decimal number. More...
 
virtual void parse (const UnicodeString &text, Formattable &result, ParsePosition &parsePosition) const =0
 Return a long if possible (e.g. More...
 
virtual void parse (const UnicodeString &text, Formattable &result, UErrorCode &status) const
 Parse a string as a numeric value, and return a Formattable numeric object. More...
 
virtual CurrencyAmountparseCurrency (const UnicodeString &text, ParsePosition &pos) const
 Parses text from the given string as a currency amount. More...
 
UBool isParseIntegerOnly (void) const
 Return true if this format will parse numbers as integers only. More...
 
virtual void setParseIntegerOnly (UBool value)
 Sets whether or not numbers should be parsed as integers only. More...
 
virtual void setLenient (UBool enable)
 Sets whether lenient parsing should be enabled (it is off by default). More...
 
virtual UBool isLenient (void) const
 Returns whether lenient parsing is enabled (it is off by default). More...
 
UBool isGroupingUsed (void) const
 Returns true if grouping is used in this format. More...
 
virtual void setGroupingUsed (UBool newValue)
 Set whether or not grouping will be used in this format. More...
 
int32_t getMaximumIntegerDigits (void) const
 Returns the maximum number of digits allowed in the integer portion of a number. More...
 
virtual void setMaximumIntegerDigits (int32_t newValue)
 Sets the maximum number of digits allowed in the integer portion of a number. More...
 
int32_t getMinimumIntegerDigits (void) const
 Returns the minimum number of digits allowed in the integer portion of a number. More...
 
virtual void setMinimumIntegerDigits (int32_t newValue)
 Sets the minimum number of digits allowed in the integer portion of a number. More...
 
int32_t getMaximumFractionDigits (void) const
 Returns the maximum number of digits allowed in the fraction portion of a number. More...
 
virtual void setMaximumFractionDigits (int32_t newValue)
 Sets the maximum number of digits allowed in the fraction portion of a number. More...
 
int32_t getMinimumFractionDigits (void) const
 Returns the minimum number of digits allowed in the fraction portion of a number. More...
 
virtual void setMinimumFractionDigits (int32_t newValue)
 Sets the minimum number of digits allowed in the fraction portion of a number. More...
 
virtual void setCurrency (const char16_t *theCurrency, UErrorCode &ec)
 Sets the currency used to display currency amounts. More...
 
const char16_t * getCurrency () const
 Gets the currency used to display currency amounts. More...
 
virtual void setContext (UDisplayContext value, UErrorCode &status)
 Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALONE. More...
 
virtual UDisplayContext getContext (UDisplayContextType type, UErrorCode &status) const
 Get the formatter's UDisplayContext value for the specified UDisplayContextType, such as UDISPCTX_TYPE_CAPITALIZATION. More...
 
virtual ERoundingMode getRoundingMode (void) const
 Get the rounding mode. More...
 
virtual void setRoundingMode (ERoundingMode roundingMode)
 Set the rounding mode. More...
 
virtual UClassID getDynamicClassID (void) const override=0
 Returns a unique class ID POLYMORPHICALLY. More...
 
UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
 Formats an object to produce a string. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const=0
 Format an object to produce a string. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format an object to produce a string. More...
 
- Public Member Functions inherited from icu::Format
virtual ~Format ()
 Destructor. More...
 
virtual bool operator== (const Format &other) const =0
 Return true if the given Format objects are semantically equal. More...
 
bool operator!= (const Format &other) const
 Return true if the given Format objects are not semantically equal. More...
 
virtual Formatclone () const =0
 Clone this object polymorphically. More...
 
UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
 Formats an object to produce a string. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const =0
 Format an object to produce a string. More...
 
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
 Format an object to produce a string. More...
 
virtual void parseObject (const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const =0
 Parse a string to produce an object. More...
 
void parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
 Parses a string to produce an object. More...
 
Locale getLocale (ULocDataLocaleType type, UErrorCode &status) const
 Get the locale for this format object. More...
 
const char * getLocaleID (ULocDataLocaleType type, UErrorCode &status) const
 Get the locale for this format object. More...
 
- Public Member Functions inherited from icu::UObject
virtual ~UObject ()
 Destructor. More...
 
virtual UClassID getDynamicClassID () const
 ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class. More...
 

Static Public Member Functions

static UClassID getStaticClassID (void)
 Returns the class ID for this class. More...
 
- Static Public Member Functions inherited from icu::NumberFormat
static NumberFormatcreateInstance (UErrorCode &)
 Create a default style NumberFormat for the current default locale. More...
 
static NumberFormatcreateInstance (const Locale &inLocale, UErrorCode &)
 Create a default style NumberFormat for the specified locale. More...
 
static NumberFormatcreateInstance (const Locale &desiredLocale, UNumberFormatStyle style, UErrorCode &errorCode)
 Create a specific style NumberFormat for the specified locale. More...
 
static NumberFormatinternalCreateInstance (const Locale &desiredLocale, UNumberFormatStyle style, UErrorCode &errorCode)
 ICU use only. More...
 
static const SharedNumberFormat * createSharedInstance (const Locale &inLocale, UNumberFormatStyle style, UErrorCode &status)
 ICU use only. More...
 
static NumberFormatcreateCurrencyInstance (UErrorCode &)
 Returns a currency format for the current default locale. More...
 
static NumberFormatcreateCurrencyInstance (const Locale &inLocale, UErrorCode &)
 Returns a currency format for the specified locale. More...
 
static NumberFormatcreatePercentInstance (UErrorCode &)
 Returns a percentage format for the current default locale. More...
 
static NumberFormatcreatePercentInstance (const Locale &inLocale, UErrorCode &)
 Returns a percentage format for the specified locale. More...
 
static NumberFormatcreateScientificInstance (UErrorCode &)
 Returns a scientific format for the current default locale. More...
 
static NumberFormatcreateScientificInstance (const Locale &inLocale, UErrorCode &)
 Returns a scientific format for the specified locale. More...
 
static const LocalegetAvailableLocales (int32_t &count)
 Get the set of Locales for which NumberFormats are installed. More...
 
static URegistryKey registerFactory (NumberFormatFactory *toAdopt, UErrorCode &status)
 Register a new NumberFormatFactory. More...
 
static UBool unregister (URegistryKey key, UErrorCode &status)
 Unregister a previously-registered NumberFormatFactory using the key returned from the register call. More...
 
static StringEnumerationgetAvailableLocales (void)
 Return a StringEnumeration over the locales available at the time of the call, including registered locales. More...
 
static UClassID getStaticClassID (void)
 Return the class ID for this class. More...
 

Friends

class MessageFormat
 

Additional Inherited Members

- Public Types inherited from icu::NumberFormat
enum  ERoundingMode {
  kRoundCeiling , kRoundFloor , kRoundDown , kRoundUp ,
  kRoundHalfEven , kRoundHalfDown , kRoundHalfUp , kRoundUnnecessary
}
 Rounding mode. More...
 
enum  EAlignmentFields {
  kIntegerField = UNUM_INTEGER_FIELD , kFractionField = UNUM_FRACTION_FIELD , kDecimalSeparatorField = UNUM_DECIMAL_SEPARATOR_FIELD , kExponentSymbolField = UNUM_EXPONENT_SYMBOL_FIELD ,
  kExponentSignField = UNUM_EXPONENT_SIGN_FIELD , kExponentField = UNUM_EXPONENT_FIELD , kGroupingSeparatorField = UNUM_GROUPING_SEPARATOR_FIELD , kCurrencyField = UNUM_CURRENCY_FIELD ,
  kPercentField = UNUM_PERCENT_FIELD , kPermillField = UNUM_PERMILL_FIELD , kSignField = UNUM_SIGN_FIELD , kMeasureUnitField = UNUM_MEASURE_UNIT_FIELD ,
  kCompactField = UNUM_COMPACT_FIELD , INTEGER_FIELD = UNUM_INTEGER_FIELD , FRACTION_FIELD = UNUM_FRACTION_FIELD
}
 Alignment Field constants used to construct a FieldPosition object. More...
 
- Protected Member Functions inherited from icu::NumberFormat
 NumberFormat ()
 Default constructor for subclass use only. More...
 
 NumberFormat (const NumberFormat &)
 Copy constructor. More...
 
NumberFormatoperator= (const NumberFormat &)
 Assignment operator. More...
 
virtual void getEffectiveCurrency (char16_t *result, UErrorCode &ec) const
 Returns the currency in effect for this formatter. More...
 
- Protected Member Functions inherited from icu::Format
void setLocaleIDs (const char *valid, const char *actual)
 
 Format ()
 Default constructor for subclass use only. More...
 
 Format (const Format &)
 
Formatoperator= (const Format &)
 
- Static Protected Member Functions inherited from icu::NumberFormat
static NumberFormatmakeInstance (const Locale &desiredLocale, UNumberFormatStyle style, UBool mustBeDecimalFormat, UErrorCode &errorCode)
 Creates the specified number format style of the desired locale. More...
 
- Static Protected Member Functions inherited from icu::Format
static void syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)
 Simple function for initializing a UParseError from a UnicodeString. More...
 
- Static Protected Attributes inherited from icu::NumberFormat
static const int32_t gDefaultMaxIntegerDigits
 
static const int32_t gDefaultMinIntegerDigits
 

Detailed Description

ChoiceFormat converts between ranges of numeric values and strings for those ranges.

The strings must conform to the MessageFormat pattern syntax.

ChoiceFormat is probably not what you need. Please use MessageFormat with plural arguments for proper plural selection, and select arguments for simple selection among a fixed set of choices!

A ChoiceFormat splits the real number line -∞ to +∞ into two or more contiguous ranges. Each range is mapped to a string.

ChoiceFormat was originally intended for displaying grammatically correct plurals such as "There is one file." vs. "There are 2 files." However, plural rules for many languages are too complex for the capabilities of ChoiceFormat, and its requirement of specifying the precise rules for each message is unmanageable for translators.

There are two methods of defining a ChoiceFormat; both are equivalent. The first is by using a string pattern. This is the preferred method in most cases. The second method is through direct specification of the arrays that logically make up the ChoiceFormat.

Note: Typically, choice formatting is done (if done at all) via MessageFormat with a choice argument type, rather than using a stand-alone ChoiceFormat.

Patterns and Their Interpretation

The pattern string defines the range boundaries and the strings for each number range. Syntax:

choiceStyle = number separator message ('|' number separator message)*
number = normal_number | ['-']  ∞ (U+221E, infinity)
normal_number = double value (unlocalized ASCII string)
separator = less_than | less_than_or_equal
less_than = '<'
less_than_or_equal = '#' |  ≤ (U+2264)
message: see MessageFormat

Pattern_White_Space between syntax elements is ignored, except around each range's sub-message.

Each numeric sub-range extends from the current range's number to the next range's number. The number itself is included in its range if a less_than_or_equal sign is used, and excluded from its range (and instead included in the previous range) if a less_than sign is used.

When a ChoiceFormat is constructed from arrays of numbers, closure flags and strings, they are interpreted just like the sequence of (number separator string) in an equivalent pattern string. closure[i]==true corresponds to a less_than separator sign. The equivalent pattern string will be constructed automatically.

During formatting, a number is mapped to the first range where the number is not greater than the range's upper limit. That range's message string is returned. A NaN maps to the very first range.

During parsing, a range is selected for the longest match of any range's message. That range's number is returned, ignoring the separator/closure. Only a simple string match is performed, without parsing of arguments that might be specified in the message strings.

Note that the first range's number is ignored in formatting but may be returned from parsing.

Examples

Here is an example of two arrays that map the number 1..7 to the English day of the week abbreviations Sun..Sat. No closures array is given; this is the same as specifying all closures to be false.

    {1,2,3,4,5,6,7},
    {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"}

Here is an example that maps the ranges [-Inf, 1), [1, 1], and (1, +Inf] to three strings. That is, the number line is split into three ranges: x < 1.0, x = 1.0, and x > 1.0. (The round parentheses in the notation above indicate an exclusive boundary, like the turned bracket in European notation: [-Inf, 1) == [-Inf, 1[ )

    {0, 1, 1},
    {false, false, true},
    {"no files", "one file", "many files"}

Here is an example that shows formatting and parsing:

#include <unicode/unistr.h>
#include <iostream.h>
int main(int argc, char *argv[]) {
double limits[] = {1,2,3,4,5,6,7};
UnicodeString monthNames[] = {
"Sun","Mon","Tue","Wed","Thu","Fri","Sat"};
ChoiceFormat fmt(limits, monthNames, 7);
UnicodeString str;
char buf[256];
for (double x = 1.0; x <= 8.0; x += 1.0) {
fmt.format(x, str);
str.extract(0, str.length(), buf, 256, "");
str.truncate(0);
cout << x << " -> "
<< buf << endl;
}
cout << endl;
return 0;
}
C++ API: Choice Format.
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:296
C++ API: Unicode String.

User subclasses are not supported. While clients may write subclasses, such code will not necessarily work and will not be guaranteed to work stably from release to release.

Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Definition at line 176 of file choicfmt.h.

Constructor & Destructor Documentation

◆ ChoiceFormat() [1/4]

icu::ChoiceFormat::ChoiceFormat ( const UnicodeString pattern,
UErrorCode status 
)

Constructs a new ChoiceFormat from the pattern string.

Parameters
patternPattern used to construct object.
statusOutput param to receive success code. If the pattern cannot be parsed, set to failure code.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ ChoiceFormat() [2/4]

icu::ChoiceFormat::ChoiceFormat ( const double *  limits,
const UnicodeString formats,
int32_t  count 
)

Constructs a new ChoiceFormat with the given limits and message strings.

All closure flags default to false, equivalent to less_than_or_equal separators.

Copies the limits and formats instead of adopting them.

Parameters
limitsArray of limit values.
formatsArray of formats.
countSize of 'limits' and 'formats' arrays.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ ChoiceFormat() [3/4]

icu::ChoiceFormat::ChoiceFormat ( const double *  limits,
const UBool closures,
const UnicodeString formats,
int32_t  count 
)

Constructs a new ChoiceFormat with the given limits, closure flags and message strings.

Copies the limits and formats instead of adopting them.

Parameters
limitsArray of limit values
closuresArray of booleans specifying whether each element of 'limits' is open or closed. If false, then the corresponding limit number is a member of its range. If true, then the limit number belongs to the previous range it.
formatsArray of formats
countSize of 'limits', 'closures', and 'formats' arrays
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ ChoiceFormat() [4/4]

icu::ChoiceFormat::ChoiceFormat ( const ChoiceFormat that)

Copy constructor.

Parameters
thatChoiceFormat object to be copied from
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ ~ChoiceFormat()

virtual icu::ChoiceFormat::~ChoiceFormat ( )
virtual

Destructor.

Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Member Function Documentation

◆ applyPattern() [1/2]

virtual void icu::ChoiceFormat::applyPattern ( const UnicodeString pattern,
UErrorCode status 
)
virtual

Sets the pattern.

Parameters
patternThe pattern to be applied.
statusOutput param set to success/failure code on exit. If the pattern is invalid, this will be set to a failure result.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ applyPattern() [2/2]

virtual void icu::ChoiceFormat::applyPattern ( const UnicodeString pattern,
UParseError parseError,
UErrorCode status 
)
virtual

Sets the pattern.

Parameters
patternThe pattern to be applied.
parseErrorStruct to receive information on position of error if an error is encountered
statusOutput param set to success/failure code on exit. If the pattern is invalid, this will be set to a failure result.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ clone()

virtual ChoiceFormat * icu::ChoiceFormat::clone ( ) const
overridevirtual

Clones this Format object.

The caller owns the result and must delete it when done.

Returns
a copy of this object
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Implements icu::NumberFormat.

◆ format() [1/21]

virtual UnicodeString & icu::NumberFormat::format ( const Formattable obj,
UnicodeString appendTo,
FieldPosition pos,
UErrorCode status 
) const
overridevirtual

Format an object to produce a string.

This method handles Formattable objects with numeric types. If the Formattable object type is not a numeric type, then it returns a failing UErrorCode.

Parameters
objThe object to format.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 2.0

Reimplemented from icu::NumberFormat.

◆ format() [2/21]

virtual UnicodeString & icu::NumberFormat::format ( const Formattable obj,
UnicodeString appendTo,
FieldPositionIterator posIter,
UErrorCode status 
) const
overridevirtual

Format an object to produce a string.

This method handles Formattable objects with numeric types. If the Formattable object type is not a numeric type, then it returns a failing UErrorCode.

Parameters
objThe object to format.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 4.4

Reimplemented from icu::NumberFormat.

◆ format() [3/21]

virtual UnicodeString & icu::ChoiceFormat::format ( const Formattable objs,
int32_t  cnt,
UnicodeString appendTo,
FieldPosition pos,
UErrorCode success 
) const
virtual

Formats an array of objects using this object's choices.

Parameters
objsThe array of objects to be formatted.
cntThe size of objs.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
successOutput param set to success/failure code on exit.
Returns
Reference to 'appendTo' parameter.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ format() [4/21]

virtual UnicodeString & icu::NumberFormat::format ( const number::impl::DecimalQuantity &  number,
UnicodeString appendTo,
FieldPosition pos,
UErrorCode status 
) const
virtual

Format a decimal number.

The number is a DecimalQuantity 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.

Parameters
numberThe number, a DecimalQuantity format Decimal Floating Point.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Internal:
Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

◆ format() [5/21]

virtual UnicodeString & icu::NumberFormat::format ( const number::impl::DecimalQuantity &  number,
UnicodeString appendTo,
FieldPositionIterator posIter,
UErrorCode status 
) const
virtual

Format a decimal number.

The number is a DecimalQuantity 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.

Parameters
numberThe number, a DecimalQuantity format Decimal Floating Point.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Internal:
Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

◆ format() [6/21]

UnicodeString & icu::NumberFormat::format ( double  number,
UnicodeString appendTo 
) const

Format a double number.

These methods call the NumberFormat pure virtual format() methods with the default FieldPosition.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 2.0

◆ format() [7/21]

virtual UnicodeString & icu::ChoiceFormat::format ( double  number,
UnicodeString appendTo,
FieldPosition pos 
) const
overridevirtual

Formats a double number using this object's choices.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
Returns
Reference to 'appendTo' parameter.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Implements icu::NumberFormat.

◆ format() [8/21]

virtual UnicodeString & icu::NumberFormat::format ( double  number,
UnicodeString appendTo,
FieldPosition pos 
) const
virtual

Format a double number.

Concrete subclasses must implement these pure virtual methods.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 2.0

Implements icu::NumberFormat.

◆ format() [9/21]

virtual UnicodeString & icu::NumberFormat::format ( double  number,
UnicodeString appendTo,
FieldPosition pos,
UErrorCode status 
) const
virtual

Format a double number.

By default, the parent function simply calls the base class and does not return an error status. Therefore, the status may be ignored in some subclasses.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
statuserror status
Returns
Reference to 'appendTo' parameter.
Internal:
Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

◆ format() [10/21]

virtual UnicodeString & icu::NumberFormat::format ( double  number,
UnicodeString appendTo,
FieldPositionIterator posIter,
UErrorCode status 
) const
virtual

Format a double number.

Subclasses must implement this method.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 4.4

Reimplemented from icu::NumberFormat.

◆ format() [11/21]

UnicodeString & icu::NumberFormat::format ( int32_t  number,
UnicodeString appendTo 
) const

Format a long number.

These methods call the NumberFormat pure virtual format() methods with the default FieldPosition.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 2.0

◆ format() [12/21]

virtual UnicodeString & icu::ChoiceFormat::format ( int32_t  number,
UnicodeString appendTo,
FieldPosition pos 
) const
overridevirtual

Formats an int32_t number using this object's choices.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
Returns
Reference to 'appendTo' parameter.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Implements icu::NumberFormat.

◆ format() [13/21]

virtual UnicodeString & icu::NumberFormat::format ( int32_t  number,
UnicodeString appendTo,
FieldPosition pos 
) const
virtual

Format a long number.

Concrete subclasses must implement these pure virtual methods.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 2.0

Implements icu::NumberFormat.

◆ format() [14/21]

virtual UnicodeString & icu::NumberFormat::format ( int32_t  number,
UnicodeString appendTo,
FieldPosition pos,
UErrorCode status 
) const
virtual

Format a long number.

Concrete subclasses may override this function to provide status return.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
statusthe output status.
Returns
Reference to 'appendTo' parameter.
Internal:
Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

◆ format() [15/21]

virtual UnicodeString & icu::NumberFormat::format ( int32_t  number,
UnicodeString appendTo,
FieldPositionIterator posIter,
UErrorCode status 
) const
virtual

Format an int32 number.

Subclasses must implement this method.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 4.4

Reimplemented from icu::NumberFormat.

◆ format() [16/21]

UnicodeString & icu::NumberFormat::format ( int64_t  number,
UnicodeString appendTo 
) const

Format an int64 number.

These methods call the NumberFormat pure virtual format() methods with the default FieldPosition.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 2.8

◆ format() [17/21]

virtual UnicodeString & icu::NumberFormat::format ( int64_t  number,
UnicodeString appendTo,
FieldPosition pos 
) const
virtual

Format an int64 number.

(Not abstract to retain compatibility with earlier releases, however subclasses should override this method as it just delegates to format(int32_t number...);

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 2.8

Reimplemented from icu::NumberFormat.

◆ format() [18/21]

virtual UnicodeString & icu::ChoiceFormat::format ( int64_t  number,
UnicodeString appendTo,
FieldPosition pos 
) const
overridevirtual

Formats an int64_t number using this object's choices.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
Returns
Reference to 'appendTo' parameter.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Reimplemented from icu::NumberFormat.

◆ format() [19/21]

virtual UnicodeString & icu::NumberFormat::format ( int64_t  number,
UnicodeString appendTo,
FieldPosition pos,
UErrorCode status 
) const
virtual

Format an int64 number.

(Not abstract to retain compatibility with earlier releases, however subclasses should override this method as it just delegates to format(int32_t number...);

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posOn input: an alignment field, if desired. On output: the offsets of the alignment field.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Internal:
Do not use. This API is for internal use only.

Reimplemented from icu::NumberFormat.

◆ format() [20/21]

virtual UnicodeString & icu::NumberFormat::format ( int64_t  number,
UnicodeString appendTo,
FieldPositionIterator posIter,
UErrorCode status 
) const
virtual

Format an int64 number.

Subclasses must implement this method.

Parameters
numberThe value to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 4.4

Reimplemented from icu::NumberFormat.

◆ format() [21/21]

virtual UnicodeString & icu::NumberFormat::format ( StringPiece  number,
UnicodeString appendTo,
FieldPositionIterator posIter,
UErrorCode status 
) const
virtual

Format a decimal number.

Subclasses must implement this method. The syntax of the unformatted number is a "numeric string" as defined in the Decimal Arithmetic Specification, available at http://speleotrove.com/decimal

Parameters
numberThe unformatted number, as a string, to be formatted.
appendToOutput parameter to receive result. Result is appended to existing contents.
posIterOn return, can be used to iterate over positions of fields generated by this format call. Can be NULL.
statusOutput param filled with success/failure status.
Returns
Reference to 'appendTo' parameter.
Stable:
ICU 4.4

Reimplemented from icu::NumberFormat.

◆ getClosures()

virtual const UBool * icu::ChoiceFormat::getClosures ( int32_t &  count) const
virtual

Returns NULL and 0.

Before ICU 4.8, this used to return the limit booleans array.

Parameters
countWill be set to 0.
Returns
NULL
Deprecated:
ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern.

◆ getDynamicClassID()

virtual UClassID icu::ChoiceFormat::getDynamicClassID ( void  ) const
overridevirtual

Returns a unique class ID POLYMORPHICALLY.

Part of ICU's "poor man's RTTI".

Returns
The class ID for this object. All objects of a given class have the same class ID. Objects of other classes have different class IDs.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Implements icu::NumberFormat.

◆ getFormats()

virtual const UnicodeString * icu::ChoiceFormat::getFormats ( int32_t &  count) const
virtual

Returns NULL and 0.

Before ICU 4.8, this used to return the array of choice strings.

Parameters
countWill be set to 0.
Returns
NULL
Deprecated:
ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern.

◆ getLimits()

virtual const double * icu::ChoiceFormat::getLimits ( int32_t &  count) const
virtual

Returns NULL and 0.

Before ICU 4.8, this used to return the choice limits array.

Parameters
countWill be set to 0.
Returns
NULL
Deprecated:
ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern.

◆ getStaticClassID()

static UClassID icu::ChoiceFormat::getStaticClassID ( void  )
static

Returns the class ID for this class.

This is useful only for comparing to a return value from getDynamicClassID(). For example:

.       Base* polymorphic_pointer = createPolymorphicObject();
.       if (polymorphic_pointer->getDynamicClassID() ==
.           Derived::getStaticClassID()) ...
Returns
The class ID for all objects of this class.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ operator=()

const ChoiceFormat & icu::ChoiceFormat::operator= ( const ChoiceFormat that)

Assignment operator.

Parameters
thatChoiceFormat object to be copied
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ operator==()

virtual bool icu::ChoiceFormat::operator== ( const Format other) const
overridevirtual

Returns true if the given Format objects are semantically equal.

Objects of different subclasses are considered unequal.

Parameters
otherChoiceFormat object to be compared
Returns
true if other is the same as this.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Reimplemented from icu::NumberFormat.

◆ parse() [1/3]

virtual void icu::ChoiceFormat::parse ( const UnicodeString text,
Formattable result,
ParsePosition parsePosition 
) const
overridevirtual

Looks for the longest match of any message string on the input text and, if there is a match, sets the result object to the corresponding range's number.

If no string matches, then the parsePosition is unchanged.

Parameters
textThe text to be parsed.
resultFormattable to be set to the parse result. If parse fails, return contents are undefined.
parsePositionThe position to start parsing at on input. On output, moved to after the last successfully parse character. On parse failure, does not change.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Implements icu::NumberFormat.

◆ parse() [2/3]

virtual void icu::NumberFormat::parse ( const UnicodeString text,
Formattable result,
ParsePosition parsePosition 
) const
virtual

Return a long if possible (e.g.

within range LONG_MAX, LONG_MAX], and with no decimals), otherwise a double. If IntegerOnly is set, will stop at a decimal point (or equivalent; e.g. for rational numbers "1 2/3", will stop after the 1).

If no object can be parsed, index is unchanged, and NULL is returned.

This is a pure virtual which concrete subclasses must implement.

Parameters
textThe text to be parsed.
resultFormattable to be set to the parse result. If parse fails, return contents are undefined.
parsePositionThe position to start parsing at on input. On output, moved to after the last successfully parse character. On parse failure, does not change.
Stable:
ICU 2.0

Implements icu::NumberFormat.

◆ parse() [3/3]

virtual void icu::NumberFormat::parse ( const UnicodeString text,
Formattable result,
UErrorCode status 
) const
virtual

Parse a string as a numeric value, and return a Formattable numeric object.

This method parses integers only if IntegerOnly is set.

Parameters
textThe text to be parsed.
resultFormattable to be set to the parse result. If parse fails, return contents are undefined.
statusOutput parameter set to a failure error code when a failure occurs. The error code when the string fails to parse is U_INVALID_FORMAT_ERROR, unless overridden by a subclass.
See also
NumberFormat::isParseIntegerOnly
Stable:
ICU 2.0

Reimplemented from icu::NumberFormat.

◆ setChoices() [1/2]

virtual void icu::ChoiceFormat::setChoices ( const double *  limits,
const UBool closures,
const UnicodeString formats,
int32_t  count 
)
virtual

Sets the choices to be used in formatting.

For details see the constructor with the same parameter list.

Parameters
limitsArray of limits
closuresArray of limit booleans
formatsArray of format string
countThe size of the above arrays
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ setChoices() [2/2]

virtual void icu::ChoiceFormat::setChoices ( const double *  limitsToCopy,
const UnicodeString formatsToCopy,
int32_t  count 
)
virtual

Sets the choices to be used in formatting.

For details see the constructor with the same parameter list.

Parameters
limitsToCopyContains the top value that you want parsed with that format,and should be in ascending sorted order. When formatting X, the choice will be the i, where limit[i] <= X < limit[i+1].
formatsToCopyThe format strings you want to use for each limit.
countThe size of the above arrays.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

◆ toPattern()

virtual UnicodeString & icu::ChoiceFormat::toPattern ( UnicodeString pattern) const
virtual

Gets the pattern.

Parameters
patternOutput param which will receive the pattern Previous contents are deleted.
Returns
A reference to 'pattern'
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Friends And Related Function Documentation

◆ MessageFormat

friend class MessageFormat
friend

Definition at line 497 of file choicfmt.h.


The documentation for this class was generated from the following file: