Main Page   Class Hierarchy   Compound List   File List   Header Files   Sources   Compound Members   File Members  

NumberFormat Class Reference

Abstract base class for all number formats. More...

#include <numfmt.h>

Class diagram for NumberFormat:

Format DecimalFormat ChoiceFormat

List of all members.


Public Members

enum  EAlignmentFields { kIntegerField, kFractionField, INTEGER_FIELD, FRACTION_FIELD }
Alignment Field constants used to construct a FieldPosition object. More...

virtual ~NumberFormat ()
virtual UBool operator== (const Format& other) const
Return true if the given Format objects are semantically equal. More...

virtual UnicodeStringformat (const Formattable& obj, UnicodeString& toAppendTo, FieldPosition& pos, UErrorCode& status) const
Format an object to produce a string. More...

virtual void parseObject (const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const
Parse a string to produce an object. More...

UnicodeStringformat ( double number, UnicodeString& output) const
Format a double or long number. More...

UnicodeStringformat ( int32_t number, UnicodeString& output) const
virtual UnicodeStringformat (double number, UnicodeString& toAppendTo, FieldPosition& pos) const = 0
Format a double or long number. More...

virtual UnicodeStringformat (int32_t number, UnicodeString& toAppendTo, FieldPosition& pos) const = 0
UnicodeStringformat (const Formattable& obj, UnicodeString& result, UErrorCode& status) const
Redeclared Format method. More...

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

virtual void parse ( const UnicodeString& text, Formattable& result, UErrorCode& status) const
Parse a string as a numeric value, and return a Formattable numeric object. More...

UBool isParseIntegerOnly (void) const
Return true if this format will parse numbers as integers only. More...

virtual void setParseIntegerOnly (UBool value)
Sets whether or not numbers should be parsed as integers only. More...

UBool isGroupingUsed (void) const
Returns true if grouping is used in this format. More...

virtual void setGroupingUsed (UBool newValue)
Set whether or not grouping will be used in this format. More...

int32_t getMaximumIntegerDigits (void) const
Returns the maximum number of digits allowed in the integer portion of a number. More...

virtual void setMaximumIntegerDigits (int32_t newValue)
Sets the maximum number of digits allowed in the integer portion of a number. More...

int32_t getMinimumIntegerDigits (void) const
Returns the minimum number of digits allowed in the integer portion of a number. More...

virtual void setMinimumIntegerDigits (int32_t newValue)
Sets the minimum number of digits allowed in the integer portion of a number. More...

int32_t getMaximumFractionDigits (void) const
Returns the maximum number of digits allowed in the fraction portion of a number. More...

virtual void setMaximumFractionDigits (int32_t newValue)
Sets the maximum number of digits allowed in the fraction portion of a number. More...

int32_t getMinimumFractionDigits (void) const
Returns the minimum number of digits allowed in the fraction portion of a number. More...

virtual void setMinimumFractionDigits (int32_t newValue)
Sets the minimum number of digits allowed in the fraction portion of a number. More...

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


Static Public Members

NumberFormat* createInstance (UErrorCode&)
Returns the default number format for the current default locale. More...

NumberFormat* createInstance (const Locale& inLocale, UErrorCode&)
Returns the default number format for the specified locale. More...

NumberFormat* createCurrencyInstance (UErrorCode&)
Returns a currency format for the current default locale. More...

NumberFormat* createCurrencyInstance (const Locale& inLocale, UErrorCode&)
Returns a currency format for the specified locale. More...

NumberFormat* createPercentInstance (UErrorCode&)
Returns a percentage format for the current default locale. More...

NumberFormat* createPercentInstance (const Locale& inLocale, UErrorCode&)
Returns a percentage format for the specified locale. More...

NumberFormat* createScientificInstance (UErrorCode&)
Returns a scientific format for the current default locale. More...

NumberFormat* createScientificInstance (const Locale& inLocale, UErrorCode&)
Returns a scientific format for the specified locale. More...

const LocalegetAvailableLocales (int32_t& count)
Get the set of Locales for which NumberFormats are installed. More...

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


Protected Members

 NumberFormat ()
Default constructor for subclass use only. More...

 NumberFormat (const NumberFormat&)
Copy constructor. More...

NumberFormat& operator= (const NumberFormat&)
Assignment operator. More...


Static Protected Members

const int32_t fgMaxIntegerDigits
const int32_t fgMinIntegerDigits

Detailed Description

Abstract base class for all number formats.

Provides interface for formatting and parsing a number. Also provides methods for determining which locales have number formats, and what their names are.

NumberFormat helps you to format and parse numbers for any locale. Your code can be completely independent of the locale conventions for decimal points, thousands-separators, or even the particular decimal digits used, or whether the number format is even decimal.

To format a number for the current Locale, use one of the static factory methods:

 .   double myNumber = 7.0;
 .   UnicodeString myString;
 .   UErrorCode success = U_ZERO_ERROR;
 .   NumberFormat* nf = NumberFormat::createInstance(success)
 .   nf->format(myNumber, myString);
 .   cout &lt;&lt; " Example 1: " &lt;&lt; myString &lt;&lt; endl;
 
If you are formatting multiple numbers, it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times.
 .    UnicodeString myString;
 .    UErrorCode success = U_ZERO_ERROR;
 .    nf = NumberFormat::createInstance( success );
 .    int32_t a[] = { 123, 3333, -1234567 };
 .    const int32_t a_len = sizeof(a) / sizeof(a[0]);
 .    myString.remove();
 .    for (int32_t i = 0; i < a_len; i++) {
 .        nf->format(a[i], myString);
 .        myString += " ; ";
 .    }
 .    cout &lt;&lt; " Example 2: " &lt;&lt; myString &lt;&lt; endl;
 
To format a number for a different Locale, specify it in the call to createInstance().
 .    nf = NumberFormat::createInstance( Locale::FRENCH, success );
 
You can use a NumberFormat to parse also.
 .   UErrorCode success;
 .   Formattable result(-999);  // initialized with error code
 .   nf->parse(myString, result, success);
 
Use createInstance to get the normal number format for that country. There are other static factory methods available. Use getCurrency to get the currency number format for that country. Use getPercent to get a format for displaying percentages. With this format, a fraction from 0.53 is displayed as 53%.

You can also control the display of numbers with such methods as getMinimumFractionDigits. If you want even more control over the format or parsing, or want to give your users more control, you can try casting the NumberFormat you get from the factory methods to a DecimalNumberFormat. This will work for the vast majority of countries; just remember to put it in a try block in case you encounter an unusual one.

You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to:

For example, you can align numbers in two ways.

If you are using a monospaced font with spacing for alignment, you can pass the FieldPosition in your format call, with field = INTEGER_FIELD. On output, getEndIndex will be set to the offset between the last character of the integer and the decimal. Add (desiredSpaceCount - getEndIndex) spaces at the front of the string.

If you are using proportional fonts, instead of padding with spaces, measure the width of the string in pixels from the start to getEndIndex. Then move the pen by (desiredPixelWidth - widthToAlignmentPoint) before drawing the text. It also works where there is no decimal, but possibly additional characters at the end, e.g. with parentheses in negative numbers: "(12)" for -12.

Stable:

Definition at line 115 of file numfmt.h.


Member Enumeration Documentation

enum NumberFormat::EAlignmentFields

Alignment Field constants used to construct a FieldPosition object.

Signifies that the position of the integer part or fraction part of a formatted number should be returned.

See also:
FieldPosition
Stable:
Enumeration values:
kIntegerField  
kFractionField  
INTEGER_FIELD   These constants are provided for backwards compatibility only, and are deprecated.

Please use the C++ style constants defined above.

Stable:
FRACTION_FIELD  

Definition at line 126 of file numfmt.h.


Member Function Documentation

virtual NumberFormat::~NumberFormat () [virtual]

virtual UBool NumberFormat::operator== (const Format & other) const [virtual]

Return true if the given Format objects are semantically equal.

Objects of different subclasses are considered unequal.

Stable:

Reimplemented from Format.

Reimplemented in ChoiceFormat, and DecimalFormat.

virtual UnicodeString & NumberFormat::format (const Formattable & obj, UnicodeString & toAppendTo, FieldPosition & pos, UErrorCode & status) const [virtual]

Format an object to produce a string.

This method handles Formattable objects with numeric types. If the Formattable object type is not a numeric type, then it returns a failing UErrorCode.

Parameters:
obj   The object to format.
toAppendTo   Where the text is to be appended.
pos   On input: an alignment field, if desired. On output: the offsets of the alignment field.
status   Output param filled with success/failure status.
Returns:
The value passed in as toAppendTo (this allows chaining, as with UnicodeString::append())
Stable:

Reimplemented from Format.

Reimplemented in ChoiceFormat, and DecimalFormat.

virtual void NumberFormat::parseObject (const UnicodeString & source, Formattable & result, ParsePosition & parse_pos) const [virtual]

Parse a string to produce an object.

This methods handles parsing of numeric strings into Formattable objects with numeric types.

Before calling, set parse_pos.index to the offset you want to start parsing at in the source. After calling, parse_pos.index is the end of the text you parsed. If error occurs, index is unchanged.

When parsing, leading whitespace is discarded (with successful parse), while trailing whitespace is left as is.

See Format::parseObject() for more.

Parameters:
source   The string to be parsed into an object.
result   Formattable to be set to the parse result. If parse fails, return contents are undefined.
parse_pos   The position to start parsing at. Upon return this param is set to the position after the last character successfully parsed. If the source is not parsed successfully, this param will remain unchanged.
Returns:
A newly created Formattable* object, or NULL on failure. The caller owns this and should delete it when done.
Stable:

Reimplemented from Format.

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

Format a double or long number.

These methods call the NumberFormat pure virtual format() methods with the default FieldPosition.

Parameters:
number   The value to be formatted.
output   Output param with the formatted string.
Returns:
A reference to 'output' param.
Stable:

Reimplemented in ChoiceFormat, and DecimalFormat.

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

Reimplemented in ChoiceFormat, and DecimalFormat.

virtual UnicodeString & NumberFormat::format (double number, UnicodeString & toAppendTo, FieldPosition & pos) const [pure virtual]

Format a double or long number.

Concrete subclasses must implement these pure virtual methods.

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.
Returns:
A reference to 'toAppendTo'.
Stable:

Reimplemented in ChoiceFormat, and DecimalFormat.

virtual UnicodeString& NumberFormat::format (int32_t number, UnicodeString & toAppendTo, FieldPosition & pos) const [pure virtual]

Reimplemented in ChoiceFormat, and DecimalFormat.

UnicodeString & NumberFormat::format (const Formattable & obj, UnicodeString & result, UErrorCode & status) const [inline]

Redeclared Format method.

Stable:

Reimplemented from Format.

Reimplemented in ChoiceFormat, and DecimalFormat.

Definition at line 550 of file numfmt.h.

virtual void NumberFormat::parse (const UnicodeString & text, Formattable & result, ParsePosition & parsePosition) const [pure 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, index is unchanged, and NULL is returned.

This is a pure virtual which concrete subclasses must implement.

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

Reimplemented in ChoiceFormat, and DecimalFormat.

virtual void NumberFormat::parse (const UnicodeString & text, Formattable & result, UErrorCode & error) const [virtual]

Parse a string as a numeric value, and return a Formattable numeric object.

This method parses integers only if IntegerOnly is set.

Parameters:
text   The text to be parsed.
result   Formattable to be set to the parse result. If parse fails, return contents are undefined.
status   Success or failure output parameter.
Returns:
A Formattable object of numeric type. The caller owns this an must delete it. NULL on failure.
See also:
NumberFormat::isParseIntegerOnly()
Stable:

Reimplemented in ChoiceFormat, and DecimalFormat.

UBool NumberFormat::isParseIntegerOnly (void) const [inline]

Return true if this format will parse numbers as integers only.

For example in the English locale, with ParseIntegerOnly true, the string "1234." would be parsed as the integer value 1234 and parsing would stop at the "." character. Of course, the exact format accepted by the parse operation is locale dependant and determined by sub-classes of NumberFormat.

Stable:

Definition at line 544 of file numfmt.h.

virtual void NumberFormat::setParseIntegerOnly (UBool value) [virtual]

Sets whether or not numbers should be parsed as integers only.

See also:
isParseIntegerOnly()
Stable:

UBool NumberFormat::isGroupingUsed (void) const

Returns true if grouping is used in this format.

For example, in the English locale, with grouping on, the number 1234567 might be formatted as "1,234,567". The grouping separator as well as the size of each group is locale dependant and is determined by sub-classes of NumberFormat.

See also:
setGroupingUsed()
Stable:

virtual void NumberFormat::setGroupingUsed (UBool newValue) [virtual]

Set whether or not grouping will be used in this format.

See also:
getGroupingUsed
Stable:

int32_t NumberFormat::getMaximumIntegerDigits (void) const

Returns the maximum number of digits allowed in the integer portion of a number.

See also:
setMaximumIntegerDigits()
Stable:

virtual void NumberFormat::setMaximumIntegerDigits (int32_t newValue) [virtual]

Sets the maximum number of digits allowed in the integer portion of a number.

maximumIntegerDigits must be >= minimumIntegerDigits. If the new value for maximumIntegerDigits is less than the current value of minimumIntegerDigits, then minimumIntegerDigits will also be set to the new value.

See also:
getMaximumIntegerDigits()
Stable:

Reimplemented in DecimalFormat.

int32_t NumberFormat::getMinimumIntegerDigits (void) const

Returns the minimum number of digits allowed in the integer portion of a number.

See also:
setMinimumIntegerDigits()
Stable:

virtual void NumberFormat::setMinimumIntegerDigits (int32_t newValue) [virtual]

Sets the minimum number of digits allowed in the integer portion of a number.

minimumIntegerDigits must be <= maximumIntegerDigits. If the new value for minimumIntegerDigits exceeds the current value of maximumIntegerDigits, then maximumIntegerDigits will also be set to the new value.

See also:
getMinimumIntegerDigits()
Stable:

Reimplemented in DecimalFormat.

int32_t NumberFormat::getMaximumFractionDigits (void) const

Returns the maximum number of digits allowed in the fraction portion of a number.

See also:
setMaximumFractionDigits()
Stable:

virtual void NumberFormat::setMaximumFractionDigits (int32_t newValue) [virtual]

Sets the maximum number of digits allowed in the fraction portion of a number.

maximumFractionDigits must be >= minimumFractionDigits. If the new value for maximumFractionDigits is less than the current value of minimumFractionDigits, then minimumFractionDigits will also be set to the new value.

See also:
getMaximumFractionDigits()
Stable:

Reimplemented in DecimalFormat.

int32_t NumberFormat::getMinimumFractionDigits (void) const

Returns the minimum number of digits allowed in the fraction portion of a number.

See also:
setMinimumFractionDigits()
Stable:

virtual void NumberFormat::setMinimumFractionDigits (int32_t newValue) [virtual]

Sets the minimum number of digits allowed in the fraction portion of a number.

minimumFractionDigits must be <= maximumFractionDigits. If the new value for minimumFractionDigits exceeds the current value of maximumFractionDigits, then maximumIntegerDigits will also be set to the new value

See also:
getMinimumFractionDigits()
Stable:

Reimplemented in DecimalFormat.

virtual UClassID NumberFormat::getDynamicClassID (void) const [inline, virtual]

Override Calendar 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:

Reimplemented from Format.

Reimplemented in ChoiceFormat, and DecimalFormat.

Definition at line 491 of file numfmt.h.

NumberFormat * NumberFormat::createInstance (UErrorCode &) [static]

Returns the default number format for the current default locale.

The default format is one of the styles provided by the other factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale dependant.

Stable:

NumberFormat * NumberFormat::createInstance (const Locale & inLocale, UErrorCode &) [static]

Returns the default number format for the specified locale.

The default format is one of the styles provided by the other factory methods: getNumberInstance, getCurrencyInstance or getPercentInstance. Exactly which one is locale dependant.

Stable:

NumberFormat * NumberFormat::createCurrencyInstance (UErrorCode &) [static]

Returns a currency format for the current default locale.

Stable:

NumberFormat * NumberFormat::createCurrencyInstance (const Locale & inLocale, UErrorCode &) [static]

Returns a currency format for the specified locale.

Stable:

NumberFormat * NumberFormat::createPercentInstance (UErrorCode &) [static]

Returns a percentage format for the current default locale.

Stable:

NumberFormat * NumberFormat::createPercentInstance (const Locale & inLocale, UErrorCode &) [static]

Returns a percentage format for the specified locale.

Stable:

NumberFormat * NumberFormat::createScientificInstance (UErrorCode &) [static]

Returns a scientific format for the current default locale.

Stable:

NumberFormat * NumberFormat::createScientificInstance (const Locale & inLocale, UErrorCode &) [static]

Returns a scientific format for the specified locale.

Stable:

const Locale * NumberFormat::getAvailableLocales (int32_t & count) [static]

Get the set of Locales for which NumberFormats are installed.

Stable:

UClassID NumberFormat::getStaticClassID (void) [inline, 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:

Reimplemented in ChoiceFormat, and DecimalFormat.

Definition at line 477 of file numfmt.h.

NumberFormat::NumberFormat () [protected]

Default constructor for subclass use only.

Stable:

NumberFormat::NumberFormat (const NumberFormat &) [protected]

Copy constructor.

Stable:

NumberFormat & NumberFormat::operator= (const NumberFormat &) [protected]

Assignment operator.

Stable:

Member Data Documentation

const int32_t NumberFormat::fgMaxIntegerDigits [static, protected]

Definition at line 514 of file numfmt.h.

const int32_t NumberFormat::fgMinIntegerDigits [static, protected]

Definition at line 515 of file numfmt.h.


The documentation for this class was generated from the following file:
Generated at Mon Jun 5 12:53:19 2000 for ICU1.5 by doxygen 1.0.0 written by Dimitri van Heesch, © 1997-1999