Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classicu_1_1NumberFormat.html below:

ICU 77.1: icu::NumberFormat Class Reference

#include "unicode/numfmt.h"

IMPORTANT: New users are strongly encouraged to see if numberformatter.h fits their use case. Although not deprecated, this header is provided for backwards compatibility only.

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:

#include <iostream>

using namespace std;

int main() {

double myNumber = 7.0;

UnicodeString myString;

nf->format(myNumber, myString);

cout << " Example 1: " << myString << endl;

}

static NumberFormat * createInstance(UErrorCode &)

Create a default style NumberFormat for the current default locale.

NumberFormat()

Default constructor for subclass use only.

C++ API: Compatibility APIs for number formatting.

C++ API: Unicode iostream like API.

UErrorCode

Standard ICU4C error code type, a substitute for exceptions.

@ U_ZERO_ERROR

No error, no warning.

Note that there are additional factory methods within subclasses of NumberFormat.

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;

for (int32_t number: {123, 3333, -1234567}) {

nf->format(number, myString);

myString += "; ";

}

cout << " Example 2: " << myString << endl;

To format a number for a different Locale, specify it in the call to createInstance().

static const Locale & getFrench()

Useful constant for this language.

You can use a NumberFormat to parse also.

Formattable result(-999);

nf->parse(myString, result, success);

Use createInstance() to get the normal number format for a Locale. There are other static factory methods available. Use createCurrencyInstance() to get the currency number format for that country. Use createPercentInstance() to get a format for displaying percentages. With this format, a fraction from 0.53 is displayed as 53%.

The type of number formatting can be specified by passing a 'style' parameter to createInstance(). For example, use
createInstance(locale, UNUM_DECIMAL, errorCode) to get the normal number format,
createInstance(locale, UNUM_PERCENT, errorCode) to get a format for displaying percentage,
createInstance(locale, UNUM_SCIENTIFIC, errorCode) to get a format for displaying scientific number,
createInstance(locale, UNUM_CURRENCY, errorCode) to get the currency number format, in which the currency is represented by its symbol, for example, "$3.00".
createInstance(locale, UNUM_CURRENCY_ISO, errorCode) to get the currency number format, in which the currency is represented by its ISO code, for example "USD3.00".
createInstance(locale, UNUM_CURRENCY_PLURAL, errorCode) to get the currency number format, in which the currency is represented by its full name in plural format, for example, "3.00 US dollars" or "1.00 US dollar".

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 dynamic_casting the NumberFormat you get from the factory methods to a DecimalFormat. This will work for the vast majority of countries; just remember to test for nullptr 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:

• (a) progressively parse through pieces of a string.
• (b) align the decimal point and other areas.

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 = UNUM_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.

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.

Stable:

ICU 2.0

Definition at line 175 of file numfmt.h.

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.

Note: as of ICU 4.4, the values in this enum have been extended to support identification of all number format fields, not just those pertaining to alignment.

These constants are provided for backwards compatibility only. Please use the C style constants defined in the header file unum.h.

See also

FieldPosition

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 2.0

Stable:

ICU 64

Stable:

ICU 64

These constants are provided for backwards compatibility only.

Please use the constants defined in the header file unum.h.

Stable:

ICU 2.0

Stable:

ICU 2.0

Definition at line 234 of file numfmt.h.

Rounding mode.

For more detail on rounding modes, see: https://unicode-org.github.io/icu/userguide/format_parse/numbers/rounding-modes

Stable:

ICU 2.4

Round towards positive infinity.

Round towards negative infinity.

Round towards zero.

Round away from zero.

Round towards the nearest integer, or towards the nearest even integer if equidistant.

Round towards the nearest integer, or towards zero if equidistant.

Round towards the nearest integer, or away from zero if equidistant.

Return U_FORMAT_INEXACT_ERROR if number does not format exactly.

Stable:

ICU 4.8

Rounds ties toward the odd number.

Stable:

ICU 73

Rounds ties toward +∞.

Stable:

ICU 73

Rounds ties toward -∞.

Stable:

ICU 73

Definition at line 186 of file numfmt.h.

Default constructor for subclass use only.

Stable:

ICU 2.0

ICU use only.

Returns handle to the shared, cached NumberFormat instance for given locale. On success, caller must call removeRef() on returned value once it is done with the shared instance.

Internal:

Do not use. This API is for internal use only.

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. 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 filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Stable:

ICU 2.0

Implements icu::Format.

Format an object to produce a string.

This is a pure virtual method which subclasses must implement. This method allows polymorphic formatting of Formattable objects. If a subclass of Format receives a Formattable object type it doesn't handle (e.g., if a numeric Formattable is passed to a DateFormat object) then it returns a failing UErrorCode.

Parameters

obj The object to format. 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 filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Stable:

ICU 2.0

Format an object to produce a string.

Subclasses should override this method. This method allows polymorphic formatting of Formattable objects. If a subclass of Format receives a Formattable object type it doesn't handle (e.g., if a numeric Formattable is passed to a DateFormat object) then it returns a failing UErrorCode.

Parameters

obj The object to format. appendTo Output parameter to receive result. Result is appended to existing contents. posIter On return, can be used to iterate over positions of fields generated by this format call. status Output param filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Stable:

ICU 4.4

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. appendTo Output parameter to receive result. Result is appended to existing contents. posIter On return, can be used to iterate over positions of fields generated by this format call. Can be nullptr. status Output param filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Stable:

ICU 4.4

Reimplemented from icu::Format.

Formats an object to produce a string.

Parameters

obj The object to format. appendTo Output parameter to receive result. Result is appended to existing contents. status Output parameter filled in with success or failure status.

Returns

Reference to 'appendTo' parameter.

Stable:

ICU 2.0

Format a decimal number.

The number is a DecimalQuantity wrapper onto a floating point decimal number. The default implementation in NumberFormat converts the decimal number to a double and formats that. Subclasses of NumberFormat that want to specifically handle big decimal numbers must override this method. class DecimalFormat does so.

Parameters

number The number, a DecimalQuantity format Decimal Floating Point. 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 filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Internal:

Do not use. This API is for internal use only.

Reimplemented in icu::RuleBasedNumberFormat, and icu::DecimalFormat.

Format a decimal number.

The number is a DecimalQuantity wrapper onto a floating point decimal number. The default implementation in NumberFormat converts the decimal number to a double and formats that. Subclasses of NumberFormat that want to specifically handle big decimal numbers must override this method. class DecimalFormat does so.

Parameters

number The number, a DecimalQuantity format Decimal Floating Point. appendTo Output parameter to receive result. Result is appended to existing contents. posIter On return, can be used to iterate over positions of fields generated by this format call. status Output param filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Internal:

Do not use. This API is for internal use only.

Reimplemented in icu::DecimalFormat.

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

Format a double number.

Concrete subclasses must implement these pure virtual methods.

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

Implemented in icu::RuleBasedNumberFormat, icu::DecimalFormat, and icu::ChoiceFormat.

Format a double number.

By default, the parent function simply calls the base class and does not return an error status. Therefore, the status may be ignored in some subclasses.

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. status error status

Returns

Reference to 'appendTo' parameter.

Internal:

Do not use. This API is for internal use only.

Reimplemented in icu::DecimalFormat.

Format a double number.

Subclasses must implement this method.

Parameters

number The value to be formatted. appendTo Output parameter to receive result. Result is appended to existing contents. posIter On return, can be used to iterate over positions of fields generated by this format call. Can be nullptr. status Output param filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Stable:

ICU 4.4

Reimplemented in icu::DecimalFormat.

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

Format a long number.

Concrete subclasses must implement these pure virtual methods.

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

Implemented in icu::RuleBasedNumberFormat, icu::DecimalFormat, and icu::ChoiceFormat.

Format a long number.

Concrete subclasses may override this function to provide status return.

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. status the output status.

Returns

Reference to 'appendTo' parameter.

Internal:

Do not use. This API is for internal use only.

Reimplemented in icu::DecimalFormat.

Format an int32 number.

Subclasses must implement this method.

Parameters

number The value to be formatted. appendTo Output parameter to receive result. Result is appended to existing contents. posIter On return, can be used to iterate over positions of fields generated by this format call. Can be nullptr. status Output param filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Stable:

ICU 4.4

Reimplemented in icu::DecimalFormat.

Format an int64 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.8

Format an int64 number.

(Not abstract to retain compatibility with earlier releases, however subclasses should override this method as it just delegates to format(int32_t number...);

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 in icu::RuleBasedNumberFormat, icu::DecimalFormat, and icu::ChoiceFormat.

Format an int64 number.

(Not abstract to retain compatibility with earlier releases, however subclasses should override this method as it just delegates to format(int32_t number...);

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. status Output param filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Internal:

Do not use. This API is for internal use only.

Reimplemented in icu::DecimalFormat.

Format an int64 number.

Subclasses must implement this method.

Parameters

number The value to be formatted. appendTo Output parameter to receive result. Result is appended to existing contents. posIter On return, can be used to iterate over positions of fields generated by this format call. Can be nullptr. status Output param filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Stable:

ICU 4.4

Reimplemented in icu::DecimalFormat.

Format a decimal number.

Subclasses must implement this method. The syntax of the unformatted number is a "numeric string" as defined in the Decimal Arithmetic Specification, available at http://speleotrove.com/decimal

Parameters

number The unformatted number, as a string, to be formatted. appendTo Output parameter to receive result. Result is appended to existing contents. posIter On return, can be used to iterate over positions of fields generated by this format call. Can be nullptr. status Output param filled with success/failure status.

Returns

Reference to 'appendTo' parameter.

Stable:

ICU 4.4

Reimplemented in icu::DecimalFormat.

Get the set of Locales for which NumberFormats are installed.

Parameters

count Output param to receive the size of the locales

Stable:

ICU 2.0

Get the formatter's UDisplayContext value for the specified UDisplayContextType, such as UDISPCTX_TYPE_CAPITALIZATION.

Parameters

type The UDisplayContextType whose value to return status Input/output status. If at entry this indicates a failure status, the function will do nothing; otherwise this will be updated with any new status from the function.

Returns

The UDisplayContextValue for the specified type.

Stable:

ICU 53

Gets the currency used to display currency amounts.

This may be an empty string for some subclasses.

Returns

a 3-letter null-terminated ISO code indicating the currency in use, or a pointer to the empty string.

Stable:

ICU 2.6

Returns the currency in effect for this formatter.

Subclasses should override this method as needed. Unlike getCurrency(), this method should never return "".

Returns

output parameter for null-terminated result, which must have a capacity of at least 4

Internal:

Do not use. This API is for internal use only.

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

Returns

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

See also

setMaximumFractionDigits

Stable:

ICU 2.0

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

Returns

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

See also

setMaximumIntegerDigits

Stable:

ICU 2.0

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

Returns

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

See also

setMinimumFractionDigits

Stable:

ICU 2.0

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

Returns

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

See also

setMinimumIntegerDigits

Stable:

ICU 2.0

ICU use only.

Creates NumberFormat instance without using the cache.

Internal:

Do not use. This API is for internal use only.

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 dependent and is determined by sub-classes of NumberFormat.

See also

setGroupingUsed

Stable:

ICU 2.0

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 dependent and determined by sub-classes of NumberFormat.

Returns

true if this format will parse numbers as integers only.

Stable:

ICU 2.0

Definition at line 1268 of file numfmt.h.

Creates the specified number format style of the desired locale.

If mustBeDecimalFormat is true, then the returned pointer is either a DecimalFormat or it is nullptr.

Internal:

Do not use. This API is for internal use only.

Assignment operator.

Stable:

ICU 2.0

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

Stable:

ICU 2.0

Implemented in icu::RuleBasedNumberFormat, icu::DecimalFormat, icu::CompactDecimalFormat, and icu::ChoiceFormat.

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 Output parameter set to a failure error code when a failure occurs. The error code when the string fails to parse is U_INVALID_FORMAT_ERROR, unless overridden by a subclass.

See also

NumberFormat::isParseIntegerOnly

Stable:

ICU 2.0

Reimplemented in icu::CompactDecimalFormat.

Parses text from the given string as a currency amount.

Unlike the parse() method, this method will attempt to parse a generic currency name, searching for a match of this object's locale's currency display names, or for a 3-letter ISO currency code. This method will fail if this format is not a currency format, that is, if it does not contain the currency pattern symbol (U+00A4) in its prefix or suffix.

Parameters

text the string to parse pos input-output position; on input, the position within text to match; must have 0 <= pos.getIndex() < text.length(); on output, the position after the last matched character. If the parse fails, the position in unchanged upon output.

Returns

if parse succeeds, a pointer to a newly-created CurrencyAmount object (owned by the caller) containing information about the parsed currency; if parse fails, this is nullptr.

Stable:

ICU 49

Reimplemented in icu::DecimalFormat, and icu::CompactDecimalFormat.

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 indicates the position after the successfully parsed text. If an error occurs, parse_pos.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 nullptr on failure. The caller owns this and should delete it when done.

Stable:

ICU 2.0

Implements icu::Format.

Register a new NumberFormatFactory.

The factory will be adopted. Because ICU may choose to cache NumberFormat objects internally, this must be called at application startup, prior to any calls to NumberFormat::createInstance to avoid undefined behavior.

Parameters

toAdopt the NumberFormatFactory instance to be adopted status the in/out status code, no special meanings are assigned

Returns

a registry key that can be used to unregister this factory

Stable:

ICU 2.6

Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALONE.

Parameters

value The UDisplayContext value to set. status Input/output status. If at entry this indicates a failure status, the function will do nothing; otherwise this will be updated with any new status from the function.

Stable:

ICU 53

Reimplemented in icu::RuleBasedNumberFormat.

Sets the currency used to display currency amounts.

This takes effect immediately, if this format is a currency format. If this format is not a currency format, then the currency is used if and when this object becomes a currency format.

Parameters

theCurrency a 3-letter ISO code indicating new currency to use. It need not be null-terminated. May be the empty string or nullptr to indicate no currency. ec input-output error code

Stable:

ICU 3.0

Reimplemented in icu::DecimalFormat.

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

Parameters

newValue True, grouping will be used in this format.

See also

getGroupingUsed

Stable:

ICU 2.0

Reimplemented in icu::DecimalFormat.

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.

Parameters

newValue the new value to be set.

See also

getMaximumFractionDigits

Stable:

ICU 2.0

Reimplemented in icu::DecimalFormat.

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.

Parameters

newValue the new value for the maximum number of digits allowed in the integer portion of a number.

See also

getMaximumIntegerDigits

Stable:

ICU 2.0

Reimplemented in icu::DecimalFormat.

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

Parameters

newValue the new value to be set.

See also

getMinimumFractionDigits

Stable:

ICU 2.0

Reimplemented in icu::DecimalFormat.

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.

Parameters

newValue the new value to be set.

See also

getMinimumIntegerDigits

Stable:

ICU 2.0

Reimplemented in icu::DecimalFormat.

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

Parameters

value set True, this format will parse numbers as integers only.

See also

isParseIntegerOnly

Stable:

ICU 2.0

Reimplemented in icu::DecimalFormat.

Unregister a previously-registered NumberFormatFactory using the key returned from the register call.

Key becomes invalid after a successful call and should not be used again. The NumberFormatFactory corresponding to the key will be deleted. Because ICU may choose to cache NumberFormat objects internally, this should be called during application shutdown, after all calls to NumberFormat::createInstance to avoid undefined behavior.

Parameters

key the registry key returned by a previous call to registerFactory status the in/out status code, no special meanings are assigned

Returns

true if the factory for the key was successfully unregistered

Stable:

ICU 2.6

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

• i18n/unicode/numfmt.h

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4