Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Search  

ChoiceFormat Class Reference

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

#include <choicfmt.h>

Inheritance diagram for ChoiceFormat::

NumberFormat Format UObject UMemory List of all members.

Public Methods

 ChoiceFormat (const UnicodeString &pattern, UErrorCode &status)
 Construct a new ChoiceFormat with the limits and the corresponding formats based on the pattern. More...

 ChoiceFormat (const double *limits, const UnicodeString *formats, int32_t count)
 Construct a new ChoiceFormat with the given limits and formats. More...

 ChoiceFormat (const double *limits, const UBool *closures, const UnicodeString *formats, int32_t count)
 Construct a new ChoiceFormat with the given limits and formats. More...

 ChoiceFormat (const ChoiceFormat &that)
 Copy constructor. More...

const ChoiceFormat & operator= (const ChoiceFormat &that)
 Assignment operator. More...

virtual ~ChoiceFormat ()
 Destructor. More...

virtual Formatclone (void) const
 Clone this Format object polymorphically. More...

virtual UBool operator== (const Format &other) const
 Return 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)
 Set the choices to be used in formatting. More...

virtual void setChoices (const double *limits, const UBool *closures, const UnicodeString *formats, int32_t count)
 Set the choices to be used in formatting. More...

virtual const double * getLimits (int32_t &count) const
 Get the limits passed in the constructor. More...

virtual const UBoolgetClosures (int32_t &count) const
 Get the limit booleans passed in the constructor. More...

virtual const UnicodeStringgetFormats (int32_t &count) const
 Get the formats passed in the constructor. More...

virtual UnicodeStringformat (double number, UnicodeString &appendTo, FieldPosition &pos) const
 Format a double or long number using this object's choices. More...

virtual UnicodeStringformat (int32_t number, UnicodeString &appendTo, FieldPosition &pos) const
 Format a int_32t number using this object's choices. More...

virtual UnicodeStringformat (int64_t number, UnicodeString &appendTo, FieldPosition &pos) const
 Format 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
 Format an array of objects using this object's choices. More...

virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
 Format an object using this object's choices. More...

UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
 Redeclared NumberFormat method. More...

UnicodeStringformat (double number, UnicodeString &appendTo) const
 Redeclared NumberFormat method. More...

UnicodeStringformat (int32_t number, UnicodeString &appendTo) const
 Redeclared NumberFormat method. More...

virtual void parse (const UnicodeString &text, Formattable &result, ParsePosition &parsePosition) const
 Return a long if possible (e.g. More...

virtual void parse (const UnicodeString &text, Formattable &result, UErrorCode &status) const
 Return a long if possible (e.g. More...

virtual UClassID getDynamicClassID (void) const
 Returns a unique class ID POLYMORPHICALLY. More...


Static Public Methods

UClassID getStaticClassID (void)
 Return the class ID for this class. More...


Private Methods

 ChoiceFormat ()
 ChoiceFormat (const UnicodeString &newPattern, UParseError &parseError, UErrorCode &status)
 Construct a new ChoiceFormat with the limits and the corresponding formats based on the pattern. More...


Static Private Methods

double stod (const UnicodeString &string)
 Converts a string to a double value using a default NumberFormat object which is static (shared by all ChoiceFormat instances). More...

UnicodeStringdtos (double value, UnicodeString &string)
 Converts a double value to a string using a default NumberFormat object which is static (shared by all ChoiceFormat instances). More...


Private Attributes

double * fChoiceLimits
 Each ChoiceFormat divides the range -Inf..+Inf into fCount intervals. More...

UBoolfClosures
UnicodeStringfChoiceFormats
int32_t fCount

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,

    0are no files|1is 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:

See below for more information about closures.

Arrays

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

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.0a|2.0b", 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;
   }

Definition at line 250 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
Draft:
This API has been introduced in ICU 2.4. It is still in draft state and may be modified in a future release.

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

ChoiceFormat::ChoiceFormat   [private]
 

ChoiceFormat::ChoiceFormat const UnicodeString   newPattern,
UParseError   parseError,
UErrorCode   status
[private]
 

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

Parameters:
newPattern  Pattern used to construct object.
parseError  Struct to recieve information on position of error if an error is encountered.
status  Output param to receive success code. If the pattern cannot be parsed, set to failure code.
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

Reimplemented from Format.

UnicodeString& ChoiceFormat::dtos double    value,
UnicodeString   string
[static, private]
 

Converts a double value to a string using a default NumberFormat object which is static (shared by all ChoiceFormat instances).

Parameters:
value  the double number to be converted with.
string  the result string.
Returns:
the converted string.

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

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

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

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.
Draft:
This API has been introduced in ICU 2.8. It is still in draft state and may be modified in a future release.

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

Reimplemented from 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

Reimplemented from NumberFormat.

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
Draft:
This API has been introduced in ICU 2.4. It is still in draft state and may be modified in a future release.

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

Reimplemented from 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

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

const ChoiceFormat& ChoiceFormat::operator= const ChoiceFormat &    that
 

Assignment operator.

Parameters:
that  ChoiceFormat object to be copied
Stable:
ICU 2.0

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

Reimplemented from 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
Draft:
This API has been introduced in ICU 2.4. It is still in draft state and may be modified in a future release.

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

double ChoiceFormat::stod const UnicodeString   string [static, private]
 

Converts a string to a double value using a default NumberFormat object which is static (shared by all ChoiceFormat instances).

Parameters:
string  the string to be converted with.
Returns:
the converted double number.

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


Friends And Related Function Documentation

friend class MessageFormat [friend]
 

Definition at line 702 of file choicfmt.h.


Member Data Documentation

UnicodeString* ChoiceFormat::fChoiceFormats [private]
 

Definition at line 742 of file choicfmt.h.

double* ChoiceFormat::fChoiceLimits [private]
 

Each ChoiceFormat divides the range -Inf..+Inf into fCount intervals.

The intervals are:

0: fChoiceLimits[0]..fChoiceLimits[1] 1: fChoiceLimits[1]..fChoiceLimits[2] ... fCount-2: fChoiceLimits[fCount-2]..fChoiceLimits[fCount-1] fCount-1: fChoiceLimits[fCount-1]..+Inf

Interval 0 is special; during formatting (mapping numbers to strings), it also contains all numbers less than fChoiceLimits[0], as well as NaN values.

Interval i maps to and from string fChoiceFormats[i]. When parsing (mapping strings to numbers), then intervals map to their lower limit, that is, interval i maps to fChoiceLimit[i].

The intervals may be closed, half open, or open. This affects formatting but does not affect parsing. Interval i is affected by fClosures[i] and fClosures[i+1]. If fClosures[i] is FALSE, then the value fChoiceLimits[i] is in interval i. That is, intervals i and i are:

i-1: ... x < fChoiceLimits[i] i: fChoiceLimits[i] <= x ...

If fClosures[i] is TRUE, then the value fChoiceLimits[i] is in interval i-1. That is, intervals i-1 and i are:

i-1: ... x <= fChoiceLimits[i] i: fChoiceLimits[i] < x ...

Because of the nature of interval 0, fClosures[0] has no effect.

Definition at line 740 of file choicfmt.h.

UBool* ChoiceFormat::fClosures [private]
 

Definition at line 741 of file choicfmt.h.

int32_t ChoiceFormat::fCount [private]
 

Definition at line 743 of file choicfmt.h.


The documentation for this class was generated from the following file:
Generated on Mon Nov 24 14:36:23 2003 for ICU 2.8 by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001