Main Page Class Hierarchy Compound List File List Header Files Sources Compound Members File Members
unum.h File Reference
Number Format C API.
More...
Compounds |
 |  | struct | UNumberFormatSymbols |
Defines |
 |  | #define | UNFSYMBOLSMAXSIZE |
Typedefs |
 |  | typedef void* | UNumberFormat |
 |  | | A number formatter. More...
|
 |  | typedef enum UNumberFormatStyle | UNumberFormatStyle |
 |  | typedef enum UNumberFormatRoundingMode | UNumberFormatRoundingMode |
 |  | typedef enum UNumberFormatPadPosition | UNumberFormatPadPosition |
 |  | typedef enum UNumberFormatAttribute | UNumberFormatAttribute |
 |  | typedef enum UNumberFormatTextAttribute | UNumberFormatTextAttribute |
 |  | typedef struct UNumberFormatSymbols | UNumberFormatSymbols |
 |  | typedef enum UNumberFormatSymbol | UNumberFormatSymbol |
Enumerations |
 |  | enum | UNumberFormatStyle { UNUM_DECIMAL,
UNUM_CURRENCY,
UNUM_PERCENT,
UNUM_SPELLOUT,
UNUM_DEFAULT
} |
 |  | | The possible number format styles. More...
|
 |  | enum | UNumberFormatRoundingMode { UNUM_ROUND_CEILING,
UNUM_ROUND_FLOOR,
UNUM_ROUND_DOWN,
UNUM_ROUND_UP,
UNUM_FOUND_HALFEVEN,
UNUM_ROUND_HALFDOWN,
UNUM_ROUND_HALFUP
} |
 |  | enum | UNumberFormatPadPosition { UNUM_PAD_BEFORE_PREFIX,
UNUM_PAD_AFTER_PREFIX,
UNUM_PAD_BEFORE_SUFFIX,
UNUM_PAD_AFTER_SUFFIX
} |
 |  | enum | UNumberFormatAttribute { UNUM_PARSE_INT_ONLY,
UNUM_GROUPING_USED,
UNUM_DECIMAL_ALWAYS_SHOWN,
UNUM_MAX_INTEGER_DIGITS,
UNUM_MIN_INTEGER_DIGITS,
UNUM_INTEGER_DIGITS,
UNUM_MAX_FRACTION_DIGITS,
UNUM_MIN_FRACTION_DIGITS,
UNUM_FRACTION_DIGITS,
UNUM_MULTIPLIER,
UNUM_GROUPING_SIZE,
UNUM_ROUNDING_MODE,
UNUM_ROUNDING_INCREMENT,
UNUM_FORMAT_WIDTH,
UNUM_PADDING_POSITION
} |
 |  | | The possible UNumberFormat numeric attributes. More...
|
 |  | enum | UNumberFormatTextAttribute { UNUM_POSITIVE_PREFIX,
UNUM_POSITIVE_SUFFIX,
UNUM_NEGATIVE_PREFIX,
UNUM_NEGATIVE_SUFFIX,
UNUM_PADDING_CHARACTER
} |
 |  | | The possible UNumberFormat text attributes. More...
|
 |  | enum | UNumberFormatSymbol { UNUM_DECIMAL_SEPARATOR_SYMBOL,
UNUM_GROUPING_SEPARATOR_SYMBOL,
UNUM_PATTERN_SEPARATOR_SYMBOL,
UNUM_PERCENT_SYMBOL,
UNUM_ZERO_DIGIT_SYMBOL,
UNUM_DIGIT_SYMBOL,
UNUM_MINUS_SIGN_SYMBOL,
UNUM_PLUS_SIGN_SYMBOL,
UNUM_CURRENCY_SYMBOL,
UNUM_INTL_CURRENCY_SYMBOL,
UNUM_MONETARY_SEPARATOR_SYMBOL,
UNUM_EXPONENTIAL_SYMBOL,
UNUM_PERMILL_SYMBOL,
UNUM_PAD_ESCAPE_SYMBOL,
UNUM_INFINITY_SYMBOL,
UNUM_NAN_SYMBOL,
UNUM_FORMAT_SYMBOL_COUNT
} |
 |  | | Constants for specifying a number format symbol. More...
|
Functions |
 |  | U_CAPI UNumberFormat* | unum_open (UNumberFormatStyle style, const char* locale, UErrorCode* status) |
 |  | | Open a new UNumberFormat for formatting and parsing numbers. More...
|
 |  | U_CAPI UNumberFormat* | unum_openPattern ( const UChar* pattern, int32_t patternLength, const char* locale, UErrorCode* status) |
 |  | | Open a new UNumberFormat for formatting and parsing numbers. More...
|
 |  | U_CAPI void | unum_close (UNumberFormat* fmt) |
 |  | | Close a UNumberFormat. More...
|
 |  | U_CAPI UNumberFormat* | unum_clone (const UNumberFormat *fmt, UErrorCode *status) |
 |  | | Open a copy of a UNumberFormat. More...
|
 |  | U_CAPI int32_t | unum_format ( const UNumberFormat* fmt, int32_t number, UChar* result, int32_t resultLength, UFieldPosition *pos, UErrorCode* status) |
 |  | | Format an integer using a UNumberFormat. More...
|
 |  | U_CAPI int32_t | unum_formatDouble ( const UNumberFormat* fmt, double number, UChar* result, int32_t resultLength, UFieldPosition *pos, UErrorCode* status) |
 |  | | Format a double using a UNumberFormat. More...
|
 |  | U_CAPI int32_t | unum_parse ( const UNumberFormat* fmt, const UChar* text, int32_t textLength, int32_t *parsePos , UErrorCode *status) |
 |  | | Parse a string into an integer using a UNumberFormat. More...
|
 |  | U_CAPI double | unum_parseDouble ( const UNumberFormat* fmt, const UChar* text, int32_t textLength, int32_t *parsePos , UErrorCode *status) |
 |  | | Parse a string into a double using a UNumberFormat. More...
|
 |  | U_CAPI const char* | unum_getAvailable (int32_t index) |
 |  | | Get a locale for which number formatting patterns are available. More...
|
 |  | U_CAPI int32_t | unum_countAvailable (void) |
 |  | | Determine how many locales have number formatting patterns available. More...
|
 |  | U_CAPI int32_t | unum_getAttribute (const UNumberFormat* fmt, UNumberFormatAttribute attr) |
 |  | | Get a numeric attribute associated with a UNumberFormat. More...
|
 |  | U_CAPI void | unum_setAttribute ( UNumberFormat* fmt, UNumberFormatAttribute attr, int32_t newValue) |
 |  | | Set a numeric attribute associated with a UNumberFormat. More...
|
 |  | U_CAPI double | unum_getDoubleAttribute (const UNumberFormat* fmt, UNumberFormatAttribute attr) |
 |  | | Get a numeric attribute associated with a UNumberFormat. More...
|
 |  | U_CAPI void | unum_setDoubleAttribute ( UNumberFormat* fmt, UNumberFormatAttribute attr, double newValue) |
 |  | | Set a numeric attribute associated with a UNumberFormat. More...
|
 |  | U_CAPI int32_t | unum_getTextAttribute ( const UNumberFormat* fmt, UNumberFormatTextAttribute tag, UChar* result, int32_t resultLength, UErrorCode* status) |
 |  | | Get a text attribute associated with a UNumberFormat. More...
|
 |  | U_CAPI void | unum_setTextAttribute ( UNumberFormat* fmt, UNumberFormatTextAttribute tag, const UChar* newValue, int32_t newValueLength, UErrorCode *status) |
 |  | | Set a text attribute associated with a UNumberFormat. More...
|
 |  | U_CAPI int32_t | unum_toPattern ( const UNumberFormat* fmt, UBool isPatternLocalized, UChar* result, int32_t resultLength, UErrorCode* status) |
 |  | | Extract the pattern from a UNumberFormat. More...
|
 |  | U_CAPI void | unum_getSymbols ( const UNumberFormat *fmt, UNumberFormatSymbols *syms) |
 |  | | Get the symbols associated with a UNumberFormat. More...
|
 |  | U_CAPI void | unum_setSymbols ( UNumberFormat* fmt, const UNumberFormatSymbols* symbolsToSet, UErrorCode *status) |
 |  | | Set the symbols associated with a UNumberFormat. More...
|
 |  | U_CAPI int32_t U_EXPORT2 | unum_getSymbol (UNumberFormat *fmt, UNumberFormatSymbol symbol, UChar *buffer, int32_t size, UErrorCode *status) |
 |  | | Get a symbol associated with a UNumberFormat. More...
|
 |  | U_CAPI void U_EXPORT2 | unum_setSymbol (UNumberFormat *fmt, UNumberFormatSymbol symbol, const UChar *value, int32_t length, UErrorCode *status) |
 |  | | Set a symbol associated with a UNumberFormat. More...
|
Detailed Description
Number Format C API.
Number Format C API Provides functions for formatting and parsing a number. Also provides methods for determining which locales have number formats, and what their names are.
UNumberFormat 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. There are different number format styles like decimal, currency, percent and spellout.
To format a number for the current Locale, use one of the static factory methods:
. UChar myString[20];
. UFieldPosition pos=0;
. double myNumber = 7.0;
. UErrorCode success = U_ZERO_ERROR;
. UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, &success)
. unum_formatDouble(nf, myNumber, myString, u_strlen(myString), &pos, &status);
. printf(" Example 1: %s\n", austrdup(myString) ); //austrdup( a function used to convert UChar* to char*)
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.
. UChar* myString;
. t_int32 i, resultlength, reslenneeded;
. UErrorCode success = U_ZERO_ERROR;
. UFieldPosition pos=0;
. t_int32 a[] = { 123, 3333, -1234567 };
. const t_int32 a_len = sizeof(a) / sizeof(a[0]);
. UNumberFormat* nf = unum_open(UNUM_DEFAULT, NULL, &success)
. for (i = 0; i < a_len; i++) {
. resultlength=0;
. reslenneeded=unum_format(nf, a[i], NULL, resultlength, &pos, &status);
. if(status==U_BUFFER_OVERFLOW_ERROR){
. status=U_ZERO_ERROR;
. resultlength=resultlengthneeded+1;
. result=(UChar*)malloc(sizeof(UChar) * resultlength);
. unum_format(nf, a[i], result, resultlength, &pos, &status);
. }
. printf(" Example 2: %s\n", austrdup(result) );
. free(result);
. }
To format a number for a different Locale, specify it in the call to unum_open().
. UNumberFormat* nf = unum_open(UNUM_DEFAULT, "fr_FR", &success)
You can use a NumberFormat API unum_parse() to parse.
. UErrorCode success;
. t_int32 pos=0;
. unum_parse(nf, result, u_strlen(result), &pos, &success);
Use UCAL_DECIMAL to get the normal number format for that country. There are other static options available. Use UCAL_CURRENCY to get the currency number format for that country. Use UCAL_PERCENT 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 function as unum_getAttribues() and unum_setAtributes(). where in you can set the miminum fraction digits, grouping used etc.
-
See also:
-
UNumberFormatAttributes for more details
You can also use forms of the parse and format methods with ParsePosition and UFieldPosition to allow you to:
- (a) progressively parse through pieces of a string.
- (b) align the decimal point and other areas.
It is also possible to change or set the symbols used for a particular locale like the currency symbol, the grouping seperator , monetary seperator etc by making use of functions unum_setSymbols() and unum_getSymbols().
Definition in file unum.h.
Define Documentation
#define UNFSYMBOLSMAXSIZE ()
|
Typedef Documentation
typedef void* UNumberFormat
|
A number formatter.
For usage in C programs.
Definition at line 105 of file unum.h.
typedef enum UNumberFormatStyle UNumberFormatStyle
|
typedef enum UNumberFormatRoundingMode UNumberFormatRoundingMode
|
typedef enum UNumberFormatPadPosition UNumberFormatPadPosition
|
typedef enum UNumberFormatAttribute UNumberFormatAttribute
|
typedef enum UNumberFormatTextAttribute UNumberFormatTextAttribute
|
typedef struct UNumberFormatSymbols UNumberFormatSymbols
|
typedef enum UNumberFormatSymbol UNumberFormatSymbol
|
Enumeration Type Documentation
The possible number format styles.
-
Enumeration values:
-
Definition at line 108 of file unum.h.
enum UNumberFormatRoundingMode
|
-
Enumeration values:
-
Definition at line 122 of file unum.h.
enum UNumberFormatPadPosition
|
-
Enumeration values:
-
Definition at line 133 of file unum.h.
enum UNumberFormatAttribute
|
The possible UNumberFormat numeric attributes.
-
Enumeration values:
-
Definition at line 313 of file unum.h.
enum UNumberFormatTextAttribute
|
The possible UNumberFormat text attributes.
-
Enumeration values:
-
Definition at line 436 of file unum.h.
Constants for specifying a number format symbol.
-
Draft:
-
-
Enumeration values:
-
Definition at line 585 of file unum.h.
Function Documentation
Open a new UNumberFormat for formatting and parsing numbers.
A UNumberFormat may be used to format numbers in calls to \Ref{unum_format}, and to parse numbers in calls to \Ref{unum_parse}.
-
Parameters:
-
style
|
The type of number format to open: one of UNUM_DECIMAL, UNUM_CURRENCY, UNUM_PERCENT, UNUM_SPELLOUT, or UNUM_DEFAULT |
locale
|
The locale specifying the formatting conventions |
status
|
A pointer to an UErrorCode to receive any errors |
-
Returns:
-
A pointer to a UNumberFormat to use for formatting numbers, or 0 if an error occurred.
-
See also:
-
unum_openPattern()
-
Stable:
-
Open a new UNumberFormat for formatting and parsing numbers.
A UNumberFormat may be used to format numbers in calls to \Ref{unum_format}, and to parse numbers in calls to \Ref{unum_parse}.
-
Parameters:
-
pattern
|
A pattern specifying the format to use. |
patternLength
|
The number of characters in the pattern, or -1 if null-terminated. |
locale
|
The locale specifying the formatting conventions |
status
|
A pointer to an UErrorCode to receive any errors |
-
Returns:
-
A pointer to a UNumberFormat to use for formatting numbers, or 0 if an error occurred.
-
See also:
-
unum_open()
-
Draft:
-
Close a UNumberFormat.
Once closed, a UNumberFormat may no longer be used.
-
Parameters:
-
fmt
|
The formatter to close. |
-
Stable:
-
Open a copy of a UNumberFormat.
This function performs a deep copy.
-
Parameters:
-
fmt
|
The format to copy |
status
|
A pointer to an UErrorCode to receive any errors. |
-
Returns:
-
A pointer to a UNumberFormat identical to fmt.
-
Stable:
-
Format an integer using a UNumberFormat.
The integer will be formatted according to the UNumberFormat's locale.
-
Parameters:
-
fmt
|
The formatter to use. |
number
|
The number to format. |
result
|
A pointer to a buffer to receive the formatted number. |
resultLength
|
The maximum size of result. |
pos
|
If not 0, a UFieldPosition which will receive the information on a specific field. |
status
|
A pointer to an UErrorCode to receive any errors |
-
Returns:
-
The total buffer size needed; if greater than resultLength, the output was truncated.
-
See also:
-
unum_formatDouble() , unum_parse() , unum_parseDouble()
-
Draft:
-
Format a double using a UNumberFormat.
The double will be formatted according to the UNumberFormat's locale.
-
Parameters:
-
fmt
|
The formatter to use. |
number
|
The number to format. |
result
|
A pointer to a buffer to receive the formatted number. |
resultLength
|
The maximum size of result. |
pos
|
If not 0, a UFieldPosition which will receive the information on a specific field. |
status
|
A pointer to an UErrorCode to receive any errors |
-
Returns:
-
The total buffer size needed; if greater than resultLength, the output was truncated.
-
See also:
-
unum_format() , unum_parse() , unum_parseDouble()
-
Draft:
-
Parse a string into an integer using a UNumberFormat.
The string will be parsed according to the UNumberFormat's locale.
-
Parameters:
-
fmt
|
The formatter to use. |
text
|
The text to parse. |
textLength
|
The length of text, or -1 if null-terminated. |
parsePos
|
If not 0, on input a pointer to an integer specifying the offset at which to begin parsing. If not 0, on output the offset at which parsing ended. |
status
|
A pointer to an UErrorCode to receive any errors |
-
Returns:
-
The value of the parsed integer
-
See also:
-
unum_parseDouble() , unum_format() , unum_formatDouble()
-
Draft:
-
Parse a string into a double using a UNumberFormat.
The string will be parsed according to the UNumberFormat's locale.
-
Parameters:
-
fmt
|
The formatter to use. |
text
|
The text to parse. |
textLength
|
The length of text, or -1 if null-terminated. |
parsePos
|
If not 0, on input a pointer to an integer specifying the offset at which to begin parsing. If not 0, on output the offset at which parsing ended. |
status
|
A pointer to an UErrorCode to receive any errors |
-
Returns:
-
The value of the parsed double
-
See also:
-
unum_parse() , unum_format() , unum_formatDouble()
-
Draft:
-
U_CAPI const char * unum_getAvailable (int32_t index)
|
Get a locale for which number formatting patterns are available.
A UNumberFormat in a locale returned by this function will perform the correct formatting and parsing for the locale.
-
Parameters:
-
index
|
The index of the desired locale. |
-
Returns:
-
A locale for which number formatting patterns are available, or 0 if none.
-
See also:
-
unum_countAvailable()
-
Stable:
-
U_CAPI int32_t unum_countAvailable (void)
|
Determine how many locales have number formatting patterns available.
This function is most useful as determining the loop ending condition for calls to \Ref{unum_getAvailable}.
-
Returns:
-
The number of locales for which number formatting patterns are available.
-
See also:
-
unum_getAvailable()
-
Stable:
-
Get a numeric attribute associated with a UNumberFormat.
An example of a numeric attribute is the number of integer digits a formatter will produce.
-
Parameters:
-
fmt
|
The formatter to query. |
attr
|
The attribute to query; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION. |
-
Returns:
-
The value of attr.
-
See also:
-
unum_setAttribute() , unum_getDoubleAttribute() , unum_setDoubleAttribute() , unum_getTextAttribute() , unum_setTextAttribute()
-
Stable:
-
Set a numeric attribute associated with a UNumberFormat.
An example of a numeric attribute is the number of integer digits a formatter will produce.
-
Parameters:
-
fmt
|
The formatter to set. |
attr
|
The attribute to set; one of UNUM_PARSE_INT_ONLY, UNUM_GROUPING_USED, UNUM_DECIMAL_ALWAYS_SHOWN, UNUM_MAX_INTEGER_DIGITS, UNUM_MIN_INTEGER_DIGITS, UNUM_INTEGER_DIGITS, UNUM_MAX_FRACTION_DIGITS, UNUM_MIN_FRACTION_DIGITS, UNUM_FRACTION_DIGITS, UNUM_MULTIPLIER, UNUM_GROUPING_SIZE, UNUM_ROUNDING_MODE, UNUM_FORMAT_WIDTH, UNUM_PADDING_POSITION. |
newValue
|
The new value of attr. |
-
See also:
-
unum_getAttribute() , unum_getDoubleAttribute() , unum_setDoubleAttribute() , unum_getTextAttribute() , unum_setTextAttribute()
-
Stable:
-
Get a text attribute associated with a UNumberFormat.
An example of a text attribute is the suffix for positive numbers.
-
Parameters:
-
fmt
|
The formatter to query. |
attr
|
The attribute to query; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX |
result
|
A pointer to a buffer to receive the attribute. |
resultLength
|
The maximum size of result. |
status
|
A pointer to an UErrorCode to receive any errors |
-
Returns:
-
The total buffer size needed; if greater than resultLength, the output was truncated.
-
See also:
-
unum_setTextAttribute() , unum_getAttribute() , unum_setAttribute()
-
Draft:
-
Set a text attribute associated with a UNumberFormat.
An example of a text attribute is the suffix for positive numbers.
-
Parameters:
-
fmt
|
The formatter to set. |
attr
|
The attribute to set; one of UNUM_POSITIVE_PREFIX, UNUM_POSITIVE_SUFFIX, UNUM_NEGATIVE_PREFIX, UNUM_NEGATIVE_SUFFIX |
newValue
|
The new value of attr. |
newValueLength
|
The length of newValue, or -1 if null-terminated. |
status
|
A pointer to an UErrorCode to receive any errors |
-
See also:
-
unum_getTextAttribute() , unum_getAttribute() , unum_setAttribute()
-
Draft:
-
Extract the pattern from a UNumberFormat.
The pattern will follow the pattern syntax.
-
Parameters:
-
fmt
|
The formatter to query. |
isPatternLocalized
|
TRUE if the pattern should be localized, FALSE otherwise. |
result
|
A pointer to a buffer to receive the pattern. |
resultLength
|
The maximum size of result. |
status
|
A pointer to an UErrorCode to receive any errors |
-
Returns:
-
The total buffer size needed; if greater than resultLength, the output was truncated.
-
Draft:
-
Get the symbols associated with a UNumberFormat.
A UNumberFormat uses symbols to represent the special locale-dependent characters in a number, for example the percent sign.
-
Parameters:
-
fmt
|
The formatter to query. |
syms
|
A pointer to a UNumberFormatSymbols to receive the symbols associated with fmt. |
-
See also:
-
unum_setSymbols()
-
Deprecated:
-
remove after 2000-dec-31
Set the symbols associated with a UNumberFormat.
A UNumberFormat uses symbols to represent the special locale-dependent characters in a number, for example the percent sign.
-
Parameters:
-
fmt
|
The formatter to set. |
symbolsToSet
|
The UNumberFormatSymbols to associate with fmt. |
status
|
A pointer to an UErrorCode to receive any errors. |
-
See also:
-
unum_getSymbols()
-
Deprecated:
-
remove after 2000-dec-31
Get a symbol associated with a UNumberFormat.
A UNumberFormat uses symbols to represent the special locale-dependent characters in a number, for example the percent sign.
-
Parameters:
-
fmt
|
The formatter to query. |
symbol
|
The UNumberFormatSymbol constant for the symbol to get |
buffer
|
The string buffer that will receive the symbol string; if it is NULL, then only the length of the symbol is returned |
size
|
The size of the string buffer |
-
Returns:
-
The length of the symbol; the buffer is not modified if
length>=size
-
See also:
-
unum_setSymbol()
-
Draft:
-
Set a symbol associated with a UNumberFormat.
A UNumberFormat uses symbols to represent the special locale-dependent characters in a number, for example the percent sign.
-
Parameters:
-
fmt
|
The formatter to set. |
symbol
|
The UNumberFormatSymbol constant for the symbol to set |
value
|
The string to set the symbol to |
length
|
The length of the string, or -1 for a zero-terminated string |
status
|
A pointer to an UErrorCode to receive any errors. |
-
See also:
-
unum_getSymbol()
-
Draft:
-
Generated at Mon Jun 5 12:53:00 2000 for ICU1.5 by
1.0.0 written by Dimitri van Heesch,
© 1997-1999