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.
 ChoiceFormat (const double *limits, const UnicodeString *formats, int32_t count)
 Constructs a new ChoiceFormat with the given limits and message strings.
 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.
 ChoiceFormat (const ChoiceFormat &that)
 Copy constructor.
const ChoiceFormatoperator= (const ChoiceFormat &that)
 Assignment operator.
virtual ~ChoiceFormat ()
 Destructor.
virtual Formatclone (void) const
 Clones this Format object.
virtual UBool operator== (const Format &other) const
 Returns true if the given Format objects are semantically equal.
virtual void applyPattern (const UnicodeString &pattern, UErrorCode &status)
 Sets the pattern.
virtual void applyPattern (const UnicodeString &pattern, UParseError &parseError, UErrorCode &status)
 Sets the pattern.
virtual UnicodeStringtoPattern (UnicodeString &pattern) const
 Gets the pattern.
virtual void setChoices (const double *limitsToCopy, const UnicodeString *formatsToCopy, int32_t count)
 Sets the choices to be used in formatting.
virtual void setChoices (const double *limits, const UBool *closures, const UnicodeString *formats, int32_t count)
 Sets the choices to be used in formatting.
virtual const double * getLimits (int32_t &count) const
 Returns NULL and 0.
virtual const UBoolgetClosures (int32_t &count) const
 Returns NULL and 0.
virtual const UnicodeStringgetFormats (int32_t &count) const
 Returns NULL and 0.
virtual UnicodeStringformat (double number, UnicodeString &appendTo, FieldPosition &pos) const
 Formats a double number using this object's choices.
virtual UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPosition &pos) const
 Formats an int32_t number using this object's choices.
virtual UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPosition &pos) const
 Formats an int64_t number using this object's choices.
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.
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Formats an object using this object's choices.
UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
 Redeclared NumberFormat method.
UnicodeStringformat (double number, UnicodeString &appendTo) const
 Redeclared NumberFormat method.
UnicodeStringformat (int32_t number, UnicodeString &appendTo) const
 Redeclared NumberFormat method.
virtual void parse (const UnicodeString &text, Formattable &result, ParsePosition &parsePosition) const
 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.
virtual void parse (const UnicodeString &text, Formattable &result, UErrorCode &status) const
 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.
virtual UClassID getDynamicClassID (void) const
 Returns a unique class ID POLYMORPHICALLY.

Static Public Member Functions

static UClassID getStaticClassID (void)
 Returns the class ID for this class.

Friends

class MessageFormat

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/choicfmt.h>
   #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;
   }

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 171 of file choicfmt.h.


Constructor & Destructor Documentation

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

Constructs a new ChoiceFormat from the pattern string.

Parameters:
pattern Pattern used to construct object.
status Output 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.
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:
limits Array of limit values.
formats Array of formats.
count Size of 'limits' and 'formats' arrays.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.
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:
limits Array of limit values
closures Array 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.
formats Array of formats
count Size of 'limits', 'closures', and 'formats' arrays
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.
icu::ChoiceFormat::ChoiceFormat ( const ChoiceFormat that  ) 

Copy constructor.

Parameters:
that ChoiceFormat object to be copied from
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.
virtual icu::ChoiceFormat::~ChoiceFormat (  )  [virtual]

Destructor.

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

Member Function Documentation

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

Sets the pattern.

Parameters:
pattern The pattern to be applied.
parseError Struct to receive information on position of error if an error is encountered
status Output 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.
virtual void icu::ChoiceFormat::applyPattern ( const UnicodeString pattern,
UErrorCode status 
) [virtual]

Sets the pattern.

Parameters:
pattern The pattern to be applied.
status Output 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.
virtual Format* icu::ChoiceFormat::clone ( void   )  const [virtual]

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::Format.

UnicodeString & icu::ChoiceFormat::format ( int32_t  number,
UnicodeString appendTo 
) const [inline]

Redeclared NumberFormat method.

Formats an int32_t number. These methods call the NumberFormat pure virtual format() methods with the default FieldPosition.

Parameters:
number The value to be formatted.
appendTo Output parameter to receive result. Result is appended to existing contents.
Returns:
Reference to 'appendTo' parameter.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Reimplemented from icu::NumberFormat.

Definition at line 678 of file choicfmt.h.

References format().

UnicodeString & icu::ChoiceFormat::format ( double  number,
UnicodeString appendTo 
) const [inline]

Redeclared NumberFormat method.

Formats a double number. These methods call the NumberFormat pure virtual format() methods with the default FieldPosition.

Parameters:
number The value to be formatted.
appendTo Output parameter to receive result. Result is appended to existing contents.
Returns:
Reference to 'appendTo' parameter.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Reimplemented from icu::NumberFormat.

Definition at line 672 of file choicfmt.h.

References format().

UnicodeString & icu::ChoiceFormat::format ( const Formattable obj,
UnicodeString appendTo,
UErrorCode status 
) const [inline]

Redeclared NumberFormat method.

Parameters:
obj The object to be formatted.
appendTo Output parameter to receive result. Result is appended to existing contents.
status Output param set to success/failure code on exit.
Returns:
Reference to 'appendTo' parameter.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Reimplemented from icu::NumberFormat.

Definition at line 663 of file choicfmt.h.

References format().

virtual UnicodeString& icu::ChoiceFormat::format ( const Formattable obj,
UnicodeString appendTo,
FieldPosition pos,
UErrorCode status 
) const [virtual]

Formats an object using this object's choices.

Parameters:
obj The object to be formatted.
appendTo Output parameter to receive result. Result is appended to existing contents.
pos On input: an alignment field, if desired. On output: the offsets of the alignment field.
status Output param set to success/failure code on exit.
Returns:
Reference to 'appendTo' parameter.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Reimplemented from icu::NumberFormat.

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:
objs The array of objects to be formatted.
cnt The size of objs.
appendTo Output parameter to receive result. Result is appended to existing contents.
pos On input: an alignment field, if desired. On output: the offsets of the alignment field.
success Output param set to success/failure code on exit.
Returns:
Reference to 'appendTo' parameter.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.
virtual UnicodeString& icu::ChoiceFormat::format ( int64_t  number,
UnicodeString appendTo,
FieldPosition pos 
) const [virtual]

Formats an int64_t number using this object's choices.

Parameters:
number The value to be formatted.
appendTo Output parameter to receive result. Result is appended to existing contents.
pos On 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.

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

Formats an int32_t number using this object's choices.

Parameters:
number The value to be formatted.
appendTo Output parameter to receive result. Result is appended to existing contents.
pos On 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.

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

Formats a double number using this object's choices.

Parameters:
number The value to be formatted.
appendTo Output parameter to receive result. Result is appended to existing contents.
pos On 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.

Referenced by format().

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:
count Will be set to 0.
Returns:
NULL
Deprecated:
ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern.
virtual UClassID icu::ChoiceFormat::getDynamicClassID ( void   )  const [virtual]

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.

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:
count Will be set to 0.
Returns:
NULL
Deprecated:
ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern.
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:
count Will be set to 0.
Returns:
NULL
Deprecated:
ICU 4.8 Use the MessagePattern class to analyze a ChoiceFormat pattern.
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.

Reimplemented from icu::NumberFormat.

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

Assignment operator.

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

Reimplemented from icu::NumberFormat.

virtual UBool icu::ChoiceFormat::operator== ( const Format other  )  const [virtual]

Returns true if the given Format objects are semantically equal.

Objects of different subclasses are considered unequal.

Parameters:
other ChoiceFormat 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.

virtual void icu::ChoiceFormat::parse ( const UnicodeString text,
Formattable result,
UErrorCode status 
) const [virtual]

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 UErrorCode is set to U_INVALID_FORMAT_ERROR.

Parameters:
text The text to be parsed.
result Formattable to be set to the parse result. If parse fails, return contents are undefined.
status Output param with the formatted string.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.

Reimplemented from icu::NumberFormat.

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

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:
text The text to be parsed.
result Formattable to be set to the parse result. If parse fails, return contents are undefined.
parsePosition The 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.

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:
limits Array of limits
closures Array of limit booleans
formats Array of format string
count The size of the above arrays
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.
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:
limitsToCopy Contains 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].
formatsToCopy The format strings you want to use for each limit.
count The size of the above arrays.
Deprecated:
ICU 49 Use MessageFormat instead, with plural and select arguments.
virtual UnicodeString& icu::ChoiceFormat::toPattern ( UnicodeString pattern  )  const [virtual]

Gets the pattern.

Parameters:
pattern Output 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.

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

Generated on 25 Nov 2014 for ICU 50.1.2 by  doxygen 1.6.1