# ChoiceFormat Class Reference

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

`#include <choicfmt.h>`

Inheritance diagram for ChoiceFormat:

## Public Member Functions
| ChoiceFormat (const UnicodeString &pattern, UErrorCode &status)
| Construct a new ChoiceFormat with the limits and the corresponding formats based on the pattern.
| ChoiceFormat (const double *limits, const UnicodeString *formats, int32_t count)
| Construct a new ChoiceFormat with the given limits and formats.
| ChoiceFormat (const double *limits, const UBool *closures, const UnicodeString *formats, int32_t count)
| Construct a new ChoiceFormat with the given limits and formats.
| ChoiceFormat (const ChoiceFormat &that)
| Copy constructor.
const ChoiceFormat & | operator= (const ChoiceFormat &that)
| Assignment operator.
virtual | ~ChoiceFormat ()
| Destructor.
virtual Format * | clone (void) const
| Clone this Format object polymorphically.
virtual UBool | operator== (const Format &other) const
| Return 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 UnicodeString & | toPattern (UnicodeString &pattern) const
| Gets the pattern.
virtual void | setChoices (const double *limitsToCopy, const UnicodeString *formatsToCopy, int32_t count)
| Set the choices to be used in formatting.
virtual void | setChoices (const double *limits, const UBool *closures, const UnicodeString *formats, int32_t count)
| Set the choices to be used in formatting.
virtual const double * | getLimits (int32_t &count) const
| Get the limits passed in the constructor.
virtual const UBool * | getClosures (int32_t &count) const
| Get the limit booleans passed in the constructor.
virtual const UnicodeString * | getFormats (int32_t &count) const
| Get the formats passed in the constructor.
virtual UnicodeString & | format (double number, UnicodeString &appendTo, FieldPosition &pos) const
| Format a double or long number using this object's choices.
virtual UnicodeString & | format (int32_t number, UnicodeString &appendTo, FieldPosition &pos) const
| Format a int_32t number using this object's choices.
virtual UnicodeString & | format (int64_t number, UnicodeString &appendTo, FieldPosition &pos) const
| Format an int64_t number using this object's choices.
virtual UnicodeString & | format (const Formattable *objs, int32_t cnt, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &success) const
| Format an array of objects using this object's choices.
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
| Format an object using this object's choices.
UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
| Redeclared NumberFormat method.
UnicodeString & | format (double number, UnicodeString &appendTo) const
| Redeclared NumberFormat method.
UnicodeString & | format (int32_t number, UnicodeString &appendTo) const
| Redeclared NumberFormat method.
virtual void | parse (const UnicodeString &text, Formattable &result, ParsePosition &parsePosition) const
| Return a long if possible (e.g.
virtual void | parse (const UnicodeString &text, Formattable &result, UErrorCode &status) const
| Return a long if possible (e.g.
virtual UClassID | getDynamicClassID (void) const
| Returns a unique class ID POLYMORPHICALLY.
## Static Public Member Functions
static UClassID | getStaticClassID (void)
| Return the class ID for this class.
## Friends
class | MessageFormat

## Detailed Description

ChoiceFormat converts between ranges of numeric values and string names for those ranges.

A `ChoiceFormat` splits the real number line `-Inf` to `+Inf` into two or more contiguous ranges. Each range is mapped to a string. `ChoiceFormat` is generally used in a `MessageFormat` for displaying grammatically correct plurals such as "There are 2 files."

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 make up the `ChoiceFormat`.

Patterns

In most cases, the preferred way to define a `ChoiceFormat` is with a pattern. Here is an example of a `ChoiceFormat` pattern:

        0≤are no files|1≤is one file|1<are many files

or equivalently,

        0#are no files|1#is one file|1<are many files

The pattern consists of a number or range specifiers separated by vertical bars '|' (U+007C). There is no vertical bar after the last range. Each range specifier is of the form:

> Number Separator String

Number is a floating point number that can be parsed by a default `NumberFormat` for the US locale. It gives the lower limit of this range. The lower limit is either inclusive or exclusive, depending on the separator. The upper limit is given by the lower limit of the next range. The Unicode infinity sign ∞ (U+221E) is recognized for positive infinity. It may be preceded by '-' (U+002D) to indicate negative infinity.

String is the format string for this range, with special characters enclosed in single quotes (`'The # sign'`). Single quotes themselves are indicated by two single quotes in a row (`'o''clock'`).

Separator is one of the following single characters:

- '≤' (U+2264) or '#' (U+0023) indicates that the lower limit given by Number is inclusive. (The two characters are equivalent to ChoiceFormat.) This means that the limit value Number belongs to this range. Another way of saying this is that the corresponding closure is `FALSE`.

- '<' (U+003C) indicates that the lower limit given by Number is exclusive. This means that the value Number belongs to the prior range. Another way of saying this is that the corresponding closure is `TRUE`.

See below for more information about closures.

Arrays

A `ChoiceFormat` defining `n` intervals (`n` >= 2) is specified by three arrays of `n` items:

- `double limits[]` gives the start of each interval. This must be a non-decreasing list of values, none of which may be `NaN`.
- `UBool closures[]` determines whether each limit value is contained in the interval below it or in the interval above it. If `closures[i]` is `FALSE`, then `limits[i]` is a member of interval `i`. Otherwise it is a member of interval `i+1`. If no closures array is specified, this is equivalent to having all closures be `FALSE`. Closures allow one to specify half-open, open, or closed intervals.
- `UnicodeString formats[]` gives the string label associated with each interval.

Formatting and Parsing

During formatting, a number is converted to a string. `ChoiceFormat` accomplishes this by mapping the number to an interval using the following rule. Given a number `X` and and index value `j` in the range `0..n-1`, where `n` is the number of ranges:

> `X` matches `j` if and only if `limit[j] <= X < limit[j+1]`

(This assumes that all closures are `FALSE`. If some closures are `TRUE` then the relations must be changed to `<=` or `<` as appropriate.) If there is no match, then either the first or last index is used, depending on whether the number is too low or too high. Once a number is mapped to an interval `j`, the string `formats[j]` is output.

During parsing, a string is converted to a number. `ChoiceFormat` finds the element `formats[j]` equal to the string, and returns `limits[j]` as the parsed value.

Notes

The first limit value does not define a range boundary. For example, in the pattern "`1.0#a|2.0#b`", the intervals are [-Inf, 2.0) and [2.0, +Inf]. It appears that the first interval should be [1.0, 2.0). However, since all values that are too small are mapped to range zero, the first interval is effectively [-Inf, 2.0). However, the first limit value is used during formatting. In this example, `parse("a")` returns 1.0.

There are no gaps between intervals and the entire number line is covered. A `ChoiceFormat` maps all possible double values to a finite set of intervals.

The non-number `NaN` is mapped to interval zero during formatting.

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.

        {0, 1, 1},
         {FALSE, FALSE, TRUE},
         {"no files", "one file", "many files"}

Here is a simple 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;
       }

Here is a more complex example using a `ChoiceFormat` constructed from a pattern together with a `MessageFormat`.

       #include <unicode/choicfmt.h>
       #include <unicode/msgfmt.h>
       #include <unicode/unistr.h>
       #include <iostream.h>

       int main(int argc, char *argv[]) {
           UErrorCode status = U_ZERO_ERROR;
           double filelimits[] = {0,1,2};
           UnicodeString filepart[] =
               {"are no files","is one file","are {0} files"};
           ChoiceFormat* fileform = new ChoiceFormat(filelimits, filepart, 3 );
           Format* testFormats[] =
               {fileform, NULL, NumberFormat::createInstance(status)};
           MessageFormat pattform("There {0} on {1}", status );
           pattform.adoptFormats(testFormats, 3);
           Formattable testArgs[] = {0L, "Disk A"};
           FieldPosition fp(0);
           UnicodeString str;
           char buf[256];
           for (int32_t i = 0; i < 4; ++i) {
               Formattable fInt(i);
               testArgs[0] = fInt;
               pattform.format(testArgs, 2, str, fp, status );
               str.extract(0, str.length(), buf, "");
               str.truncate(0);
               cout << "Output for i=" << i << " : " << 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.

Definition at line 259 of file choicfmt.h.

## Constructor & Destructor Documentation

ChoiceFormat::ChoiceFormat | ( | const UnicodeString & | pattern,
|  | UErrorCode & | status |
| ) |  |  |

Construct a new ChoiceFormat with the limits and the corresponding formats based on the pattern.

Parameters:

  | pattern | Pattern used to construct object.
  | status | Output param to receive success code. If the pattern cannot be parsed, set to failure code.

Stable:
  ICU 2.0

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

Construct a new ChoiceFormat with the given limits and formats.

Copy 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.

Stable:
  ICU 2.0

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

Construct a new ChoiceFormat with the given limits and formats.

Copy the limits and formats (instead of adopting them). By default, each limit in the array specifies the inclusive lower bound of its range, and the exclusive upper bound of the previous range. However, if the isLimitOpen element corresponding to a limit is TRUE, then the limit is the exclusive lower bound of its range, and the inclusive upper bound of the previous range.

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 is a member of the range above it. If TRUE, then the limit belongs to the range below it.
  | formats | Array of formats
  | count | Size of 'limits', 'closures', and 'formats' arrays

Stable:
  ICU 2.4

ChoiceFormat::ChoiceFormat | ( | const ChoiceFormat & | that | ) |

Copy constructor.

Parameters:

  | that | ChoiceFormat object to be copied from

Stable:
  ICU 2.0

virtual ChoiceFormat::~ChoiceFormat | ( |  | ) | `[virtual]`

Destructor.

Stable:
  ICU 2.0

## Member Function Documentation

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

Sets the pattern.

Parameters:

  | pattern | The pattern to be applied.
  | parseError | Struct to recieve 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.

Stable:
  ICU 2.0

virtual void 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.

Stable:
  ICU 2.0

virtual Format* ChoiceFormat::clone | ( | void |  | ) | const`[virtual]`

Clone this Format object polymorphically.

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

Returns:
  a copy of this object

Stable:
  ICU 2.0

Implements Format.

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

Redeclared NumberFormat method.

Format a long 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.

Stable:
  ICU 2.0

Reimplemented from NumberFormat.

Definition at line 740 of file choicfmt.h.

References format().

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

Redeclared NumberFormat method.

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

Stable:
  ICU 2.0

Reimplemented from NumberFormat.

Definition at line 734 of file choicfmt.h.

References format().

UnicodeString & 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.

Stable:
  ICU 2.0

Reimplemented from NumberFormat.

Definition at line 725 of file choicfmt.h.

References format().

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

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

Stable:
  ICU 2.0

Reimplemented from NumberFormat.

virtual UnicodeString& ChoiceFormat::format | ( | const Formattable * | objs,
|  | int32_t | cnt,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos,
|  | UErrorCode & | success |
| ) |  |  | const`[virtual]`

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

Stable:
  ICU 2.0

virtual UnicodeString& ChoiceFormat::format | ( | int64_t | number,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | pos |
| ) |  |  | const`[virtual]`

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

Stable:
  ICU 2.8

Reimplemented from NumberFormat.

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

Format a int_32t 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.

Stable:
  ICU 2.0

Implements NumberFormat.

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

Format a double or long 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.

Stable:
  ICU 2.0

Implements NumberFormat.

Referenced by format().

virtual const UBool* ChoiceFormat::getClosures | ( | int32_t & | count | ) | const`[virtual]`

Get the limit booleans passed in the constructor.

The caller must not delete the result.

Parameters:

  | count | The size of the arrays

Returns:
  the closures

Stable:
  ICU 2.4

virtual UClassID ChoiceFormat::getDynamicClassID | ( | void |  | ) | const`[virtual]`

Returns a unique class ID POLYMORPHICALLY.

Pure virtual override. This method is to implement a simple version of RTTI, since not all C++ compilers support genuine RTTI. Polymorphic operator==() and clone() methods call this method.

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.

Stable:
  ICU 2.0

Implements NumberFormat.

virtual const UnicodeString* ChoiceFormat::getFormats | ( | int32_t & | count | ) | const`[virtual]`

Get the formats passed in the constructor.

Parameters:

  | count | The size of the arrays

Returns:
  the formats.

Stable:
  ICU 2.0

virtual const double* ChoiceFormat::getLimits | ( | int32_t & | count | ) | const`[virtual]`

Get the limits passed in the constructor.

Parameters:

  | count | The size of the limits arrays

Returns:
  the limits.

Stable:
  ICU 2.0

static UClassID ChoiceFormat::getStaticClassID | ( | void |  | ) | `[static]`

Return 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.

Stable:
  ICU 2.0

Reimplemented from NumberFormat.

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

Assignment operator.

Parameters:

  | that | ChoiceFormat object to be copied

Stable:
  ICU 2.0

Reimplemented from NumberFormat.

virtual UBool ChoiceFormat::operator== | ( | const Format & | other | ) | const`[virtual]`

Return 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.

Stable:
  ICU 2.0

Reimplemented from NumberFormat.

virtual void ChoiceFormat::parse | ( | const UnicodeString & | text,
|  | Formattable & | result,
|  | UErrorCode & | status |
| ) |  |  | 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, parsePosition is unchanged, and NULL is returned.

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.

See also:
  NumberFormat::isParseIntegerOnly

Stable:
  ICU 2.0

Reimplemented from NumberFormat.

virtual void ChoiceFormat::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, parsePosition is unchanged, and NULL is returned.

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.

See also:
  NumberFormat::isParseIntegerOnly

Stable:
  ICU 2.0

Implements NumberFormat.

virtual void ChoiceFormat::setChoices | ( | const double * | limits,
|  | const UBool * | closures,
|  | const UnicodeString * | formats,
|  | int32_t | count |
| ) |  |  | `[virtual]`

Set the choices to be used in formatting.

See class description for documenatation of the limits, closures, and formats arrays.

Parameters:

  | limits | Array of limits
  | closures | Array of limit booleans
  | formats | Array of format string
  | count | The size of the above arrays

Stable:
  ICU 2.4

virtual void ChoiceFormat::setChoices | ( | const double * | limitsToCopy,
|  | const UnicodeString * | formatsToCopy,
|  | int32_t | count |
| ) |  |  | `[virtual]`

Set the choices to be used in formatting.

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.

Stable:
  ICU 2.0

virtual UnicodeString& ChoiceFormat::toPattern | ( | UnicodeString & | pattern | ) | const`[virtual]`

Gets the pattern.

Parameters:

  | pattern | Output param which will recieve the pattern Previous contents are deleted.

Returns:
  A reference to 'pattern'

Stable:
  ICU 2.0

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

- choicfmt.h

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Defines