ChoiceFormat

class U_I18N_API ChoiceFormat : public NumberFormat

A ChoiceFormat allows you to attach a format to a range of numbers

Inheritance:

Public Methods
ChoiceFormat(const UnicodeString& newPattern, 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 ChoiceFormat&): Copy constructor
const ChoiceFormat& operator=(const ChoiceFormat&): Assignment operator
virtual ~ChoiceFormat(): Destructor
virtual Format* clone(void) const: Clone this Format object polymorphically
virtual bool_t 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 UnicodeString& toPattern(UnicodeString &pattern) const: Gets the pattern
virtual void adoptChoices(double* limitsToAdopt, UnicodeString* formatsToAdopt, int32_t count ): Set the choices to be used in formatting
virtual void setChoices(const double* limitsToCopy, const UnicodeString* formatsToCopy, 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 UnicodeString* getFormats(int32_t& count) const: Get the formats passed in the constructor
virtual UnicodeString& format(double number, UnicodeString& toAppendTo, FieldPosition& pos) const: Format a double or long number using this object's choices
UnicodeString& format(const Formattable& obj, UnicodeString& result, UErrorCode& status) const: Redeclared NumberFormat method
UnicodeString& format( double number, UnicodeString& output) const: Redeclared NumberFormat method
UnicodeString& format( int32_t number, UnicodeString& output) const: Redeclared NumberFormat method
virtual void parse(const UnicodeString& text, Formattable& result, ParsePosition& parsePosition) const: Return a long if possible (e
virtual UClassID getDynamicClassID(void) const: Returns a unique class ID POLYMORPHICALLY
static UClassID getStaticClassID(void): Return the class ID for this class
static double nextDouble(double d ): Finds the least double greater than d
static double previousDouble(double d ): Finds the greatest double less than d

Inherited from NumberFormat:

Public Classes
enum EAlignmentFields

INTEGER_FIELD
These constants are provided for backwards compatibility only, and are deprecated

Public Methods
virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const
bool_t isParseIntegerOnly(void) const
virtual void setParseIntegerOnly(bool_t value)
static NumberFormat* createInstance(UErrorCode&)
static NumberFormat* createInstance(const Locale& inLocale, UErrorCode&)
static NumberFormat* createCurrencyInstance(UErrorCode&)
static NumberFormat* createCurrencyInstance(const Locale& inLocale, UErrorCode&)
static NumberFormat* createPercentInstance(UErrorCode&)
static NumberFormat* createPercentInstance(const Locale& inLocale, UErrorCode&)
static NumberFormat* createScientificInstance(UErrorCode&)
static NumberFormat* createScientificInstance(const Locale& inLocale, UErrorCode&)
static const Locale* getAvailableLocales(int32_t& count)
bool_t isGroupingUsed(void) const
virtual void setGroupingUsed(bool_t newValue)
int32_t getMaximumIntegerDigits(void) const
virtual void setMaximumIntegerDigits(int32_t newValue)
int32_t getMinimumIntegerDigits(void) const
virtual void setMinimumIntegerDigits(int32_t newValue)
int32_t getMaximumFractionDigits(void) const
virtual void setMaximumFractionDigits(int32_t newValue)
int32_t getMinimumFractionDigits(void) const
virtual void setMinimumFractionDigits(int32_t newValue)

Inherited from Format:

Public Methods
bool_t operator!=(const Format& other) const

Documentation

A ChoiceFormat allows you to attach a format to a range of numbers. It is generally used in a MessageFormat for doing things like plurals. The choice is specified with an ascending list of doubles, where each item specifies a half-open interval up to the next item:
.    X matches j if and only if limit[j] <= X < limit[j+1]
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. The length of the array of formats must be the same as the length of the array of limits. For example,
.     {1,2,3,4,5,6,7},
.          {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"}
.     {0, 1, ChoiceFormat::nextDouble(1)},
.          {"no files", "one file", "many files"}
(nextDouble can be used to get the next higher double, to make the half-open interval.)
Here is a simple example that shows formatting and parsing:
.  void SimpleChoiceExample( void )
.  {
.      double limits[] = {1,2,3,4,5,6,7};
.      UnicodeString monthNames[] = {"Sun","Mon","Tue","Wed","Thur","Fri","Sat"};
.      ChoiceFormat* form = new ChoiceFormat(limits, monthNames, 7 );
.      ParsePosition* status = new ParsePosition(0);
.      UnicodeString str;
.      FieldPosition f1(0), f2(0);
.      for (double i = 0.0; i <= 8.0; ++i) {
.          status->setIndex(0);
.          Formattable parseResult;
.          str.remove();
.          cout << i << " -> " << form->format(i,str, f1) 
.                    << " -> " << parseResult << endl;
.      }
.      delete form;
.      delete status;
.      cout << endl;
.  }
Here is a more complex example, with a pattern format.
.  void ComplexChoiceExample( void )
.  {
.      double filelimits[] = {0,1,2};
.      UnicodeString filepart[] = {"are no files","is one file","are {2} files"};
.      ChoiceFormat* fileform = new ChoiceFormat(filelimits, filepart, 3 );
.      UErrorCode success = U_ZERO_ERROR;
.      const Format* testFormats[] = { fileform, NULL, NumberFormat::createInstance(success) };
.      MessageFormat* pattform = new MessageFormat("There {0} on {1}", success );
.      pattform->setFormats( testFormats, 3 );
.      Formattable testArgs[] = {0L, "Disk_A", 0L};
.      FieldPosition fp(0);
.      UnicodeString str;
.      for (int32_t i = 0; i < 4; ++i) {
.          Formattable fInt(i);
.          testArgs[0] = fInt;
.          testArgs[2] = testArgs[0];
.          str.remove();
.          pattform->format(testArgs, 3, str, fp, success );
.          cout << "Output for i=" << i << " : " << str << endl;
.      }
.      delete pattform;
.      cout << endl;
.  }
ChoiceFormat objects may be converted to and from patterns. The syntax of these patterns is [TODO fill in this section with detail]. Here is an example of a ChoiceFormat pattern:
You can either do this programmatically, as in the above example, or by using a pattern (see ChoiceFormat for more information) as in:
.       "0#are no files|1#is one file|1<are many files"
Here the notation is:
.       <number> "#"  Specifies a limit value.
.       <number> "<"  Specifies a limit of nextDouble(<number>).
.       <number> ">"  Specifies a limit of previousDouble(<number>).
Each limit value is followed by a string, which is terminated by a vertical bar character ("|"), except for the last string, which is terminated by the end of the string.

ChoiceFormat(const UnicodeString& newPattern, 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.

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.

ChoiceFormat(const ChoiceFormat&)

Copy constructor

const ChoiceFormat& operator=(const ChoiceFormat&)

Assignment operator

virtual ~ChoiceFormat()

Destructor

virtual Format* clone(void) const

Clone this Format object polymorphically. The caller owns the result and should delete it when done.

virtual bool_t operator==(const Format& other) const

Return true if the given Format objects are semantically equal. Objects of different subclasses are considered unequal.

virtual void applyPattern(const UnicodeString& pattern, UErrorCode& status)

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.

virtual UnicodeString& toPattern(UnicodeString &pattern) const

Gets the pattern

virtual void adoptChoices(double* limitsToAdopt, UnicodeString* formatsToAdopt, int32_t count )

Set the choices to be used in formatting. The arrays are adopted and should not be deleted by the caller.

Parameters:: limitsToAdopt - 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].
formatsToAdopt - The format strings you want to use for each limit.
count - The size of the above arrays.

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

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.

virtual const double* getLimits(int32_t& count) const

Get the limits passed in the constructor

Returns:: the limits.

virtual const UnicodeString* getFormats(int32_t& count) const

Get the formats passed in the constructor

Returns:: the formats.

virtual UnicodeString& format(double number, UnicodeString& toAppendTo, FieldPosition& pos) const

Format a double or long number using this object's choices.

Returns:: A reference to 'toAppendTo'.
Parameters:: number - The value to be formatted.
toAppendTo - The string to append the formatted string to. This is an output parameter.
pos - On input: an alignment field, if desired. On output: the offsets of the alignment field.

UnicodeString& format(const Formattable& obj, UnicodeString& result, UErrorCode& status) const

Redeclared NumberFormat method

UnicodeString& format( double number, UnicodeString& output) const

Redeclared NumberFormat method

UnicodeString& format( int32_t number, UnicodeString& output) const

Redeclared NumberFormat method

virtual void parse(const UnicodeString& text, Formattable& result, ParsePosition& parsePosition) const

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.

Returns:: A Formattable object of numeric type. The caller owns this an must delete it. NULL on failure.
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

virtual UClassID getDynamicClassID(void) const

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.

static UClassID getStaticClassID(void)

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()) ...