ICU 4.8.1.1
4.8.1.1
|
ChoiceFormat converts between ranges of numeric values and strings for those ranges. More...
#include <choicfmt.h>
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 ChoiceFormat & | operator= (const ChoiceFormat &that) |
Assignment operator. | |
virtual | ~ChoiceFormat () |
Destructor. | |
virtual Format * | clone (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 UnicodeString & | toPattern (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 UBool * | getClosures (int32_t &count) const |
Returns NULL and 0. | |
virtual const UnicodeString * | getFormats (int32_t &count) const |
Returns NULL and 0. | |
virtual UnicodeString & | format (double number, UnicodeString &appendTo, FieldPosition &pos) const |
Formats a double number using this object's choices. | |
virtual UnicodeString & | format (int32_t number, UnicodeString &appendTo, FieldPosition &pos) const |
Formats an int32_t number using this object's choices. | |
virtual UnicodeString & | format (int64_t number, UnicodeString &appendTo, FieldPosition &pos) const |
Formats 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 |
Formats an array of objects using this object's choices. | |
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const |
Formats 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 |
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 |
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
.
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.
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.
Definition at line 168 of file choicfmt.h.
ChoiceFormat::ChoiceFormat | ( | const UnicodeString & | pattern, |
UErrorCode & | status | ||
) |
Constructs a new ChoiceFormat from the pattern string.
pattern | Pattern used to construct object. |
status | Output param to receive success code. If the pattern cannot be parsed, set to failure code. |
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.
limits | Array of limit values. |
formats | Array of formats. |
count | Size of 'limits' and 'formats' arrays. |
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.
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 |
ChoiceFormat::ChoiceFormat | ( | const ChoiceFormat & | that | ) |
virtual ChoiceFormat::~ChoiceFormat | ( | ) | [virtual] |
Destructor.
virtual void ChoiceFormat::applyPattern | ( | const UnicodeString & | pattern, |
UErrorCode & | status | ||
) | [virtual] |
Sets the pattern.
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 void ChoiceFormat::applyPattern | ( | const UnicodeString & | pattern, |
UParseError & | parseError, | ||
UErrorCode & | status | ||
) | [virtual] |
Sets the pattern.
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. |
virtual Format* ChoiceFormat::clone | ( | void | ) | const [virtual] |
virtual UnicodeString& ChoiceFormat::format | ( | double | number, |
UnicodeString & | appendTo, | ||
FieldPosition & | pos | ||
) | const [virtual] |
Formats a double number using this object's choices.
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. |
Implements NumberFormat.
Referenced by format().
virtual UnicodeString& ChoiceFormat::format | ( | int32_t | number, |
UnicodeString & | appendTo, | ||
FieldPosition & | pos | ||
) | const [virtual] |
Formats an int32_t number using this object's choices.
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. |
Implements NumberFormat.
virtual UnicodeString& ChoiceFormat::format | ( | int64_t | number, |
UnicodeString & | appendTo, | ||
FieldPosition & | pos | ||
) | const [virtual] |
Formats an int64_t number using this object's choices.
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. |
Reimplemented from NumberFormat.
virtual UnicodeString& 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.
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. |
virtual UnicodeString& ChoiceFormat::format | ( | const Formattable & | obj, |
UnicodeString & | appendTo, | ||
FieldPosition & | pos, | ||
UErrorCode & | status | ||
) | const [virtual] |
Formats an object using this object's choices.
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. |
Reimplemented from NumberFormat.
UnicodeString & ChoiceFormat::format | ( | const Formattable & | obj, |
UnicodeString & | appendTo, | ||
UErrorCode & | status | ||
) | const [inline] |
Redeclared NumberFormat method.
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. |
Reimplemented from NumberFormat.
Definition at line 661 of file choicfmt.h.
References format().
UnicodeString & 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.
number | The value to be formatted. |
appendTo | Output parameter to receive result. Result is appended to existing contents. |
Reimplemented from NumberFormat.
Definition at line 670 of file choicfmt.h.
References format().
UnicodeString & 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.
number | The value to be formatted. |
appendTo | Output parameter to receive result. Result is appended to existing contents. |
Reimplemented from NumberFormat.
Definition at line 676 of file choicfmt.h.
References format().
virtual const UBool* ChoiceFormat::getClosures | ( | int32_t & | count | ) | const [virtual] |
Returns NULL and 0.
Before ICU 4.8, this used to return the limit booleans array.
count | Will be set to 0. |
virtual UClassID ChoiceFormat::getDynamicClassID | ( | void | ) | const [virtual] |
Returns a unique class ID POLYMORPHICALLY.
Part of ICU's "poor man's RTTI".
Implements NumberFormat.
virtual const UnicodeString* ChoiceFormat::getFormats | ( | int32_t & | count | ) | const [virtual] |
Returns NULL and 0.
Before ICU 4.8, this used to return the array of choice strings.
count | Will be set to 0. |
virtual const double* ChoiceFormat::getLimits | ( | int32_t & | count | ) | const [virtual] |
Returns NULL and 0.
Before ICU 4.8, this used to return the choice limits array.
count | Will be set to 0. |
static UClassID 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()) ...
Reimplemented from NumberFormat.
const ChoiceFormat& ChoiceFormat::operator= | ( | const ChoiceFormat & | that | ) |
Returns true if the given Format objects are semantically equal.
Objects of different subclasses are considered unequal.
other | ChoiceFormat object to be compared |
Reimplemented from NumberFormat.
virtual void 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.
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. |
Implements NumberFormat.
virtual void 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.
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. |
Reimplemented from NumberFormat.
virtual void 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.
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 void 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.
limits | Array of limits |
closures | Array of limit booleans |
formats | Array of format string |
count | The size of the above arrays |
virtual UnicodeString& ChoiceFormat::toPattern | ( | UnicodeString & | pattern | ) | const [virtual] |
Gets the pattern.
pattern | Output param which will receive the pattern Previous contents are deleted. |