Unumber

---

The Unumber module helps you format and parse numbers for any locale.

Required Header

#include <utils_i18n.h>

Overview

The Unumber module helps you 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.

Sample Code 1

Gets a currency symbol according to a given locale.

    int buf_len;
    i18n_uchar u_buffer[64];
    char a_buffer[64];
    i18n_unumber_format_h num_format;

    // creates and returns a new unumber_format
    i18n_unumber_create(I18N_UNUMBER_CURRENCY, NULL, -1, "en_US", NULL, &num_format);

    // gets a symbol associated with i18n_unumber_format
    i18n_unumber_get_symbol(num_format, I18N_UNUMBER_CURRENCY_SYMBOL, u_buffer, 64, &buf_len);

    i18n_ustring_copy_au(a_buffer, u_buffer);
    // en_US currency symbol: $
    dlog_print(DLOG_INFO, LOG_TAG, "en_US currency symbol: %s \n", a_buffer);

    // destroys i18n_unumber_format
    i18n_unumber_destroy(num_format);

Functions
int	i18n_unumber_create (i18n_unumber_format_style_e style, const i18n_uchar *pattern, int32_t pattern_len, const char *locale, i18n_uparse_error_s *parse_err, i18n_unumber_format_h *num_format)
	Creates and returns a new unumber_format_h for formatting and parsing numbers.
int	i18n_unumber_destroy (i18n_unumber_format_h fmt)
	Destroys an i18n_unumber_format_h.
int	i18n_unumber_get_symbol (const i18n_unumber_format_h fmt, i18n_unumber_format_symbol_e symbol, i18n_uchar *buffer, int32_t size, int32_t *len_symbol)
	Gets a symbol associated with an i18n_unumber_format_h.
int	i18n_unumber_clone (const i18n_unumber_format_h fmt, i18n_unumber_format_h *fmt_clone)
	Creates a copy of an i18n_unumber_format_h.
int32_t	i18n_unumber_format (const i18n_unumber_format_h fmt, int32_t number, i18n_uchar *result, int32_t result_length, i18n_ufield_position_s *pos, i18n_error_code_e *status)
	Formats an integer using a i18n_unumber_format_h.
int32_t	i18n_unumber_format_int64 (const i18n_unumber_format_h fmt, int64_t number, i18n_uchar *result, int32_t result_length, i18n_ufield_position_h pos)
	Formats an int64 using an i18n_unumber_format_h.
int32_t	i18n_unumber_format_double (const i18n_unumber_format_h fmt, double number, i18n_uchar *result, int32_t result_length, i18n_ufield_position_h pos)
	Formats a double using an i18n_unumber_format_h.
int32_t	i18n_unumber_format_decimal (const i18n_unumber_format_h fmt, const char *number, int32_t length, i18n_uchar *result, int32_t result_length, i18n_ufield_position_h pos)
	Formats a decimal number using an i18n_unumber_format_h.
int32_t	i18n_unumber_format_double_currency (const i18n_unumber_format_h fmt, double number, i18n_uchar *currency, i18n_uchar *result, int32_t result_length, i18n_ufield_position_h pos)
	Formats a double currency amount using an i18n_unumber_format_h.
int32_t	i18n_unumber_parse (const i18n_unumber_format_h fmt, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos)
	Parses a string into an integer using an i18n_unumber_format_h.
int64_t	i18n_unumber_parse_int64 (const i18n_unumber_format_h fmt, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos)
	Parses a string into an int64 using an i18n_unumber_format_h.
double	i18n_unumber_parse_double (const i18n_unumber_format_h fmt, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos)
	Parses a string into a double using an i18n_unumber_format_h.
int32_t	i18n_unumber_parse_decimal (const i18n_unumber_format_h fmt, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos, char *out_buf, int32_t out_buf_length)
	Parses a number from a string into an unformatted numeric string using an i18n_unumber_format_h.
double	i18n_unumber_parse_double_currency (const i18n_unumber_format_h fmt, const i18n_uchar *text, int32_t text_length, int32_t *parse_pos, i18n_uchar *currency)
	Parses a string into a double and a currency using an i18n_unumber_format_h.
int	i18n_unumber_apply_pattern (i18n_unumber_format_h format, i18n_ubool localized, const i18n_uchar *pattern, int32_t pattern_length, i18n_uparse_error_s *parse_error)
	Sets the pattern used by an i18n_unumber_format_h.
const char *	i18n_unumber_get_available (int32_t locale_index)
	Gets a locale for which decimal formatting patterns are available.
int32_t	i18n_unumber_count_available (void)
	Determines how many locales have decimal formatting patterns available.
int32_t	i18n_unumber_get_attribute (const i18n_unumber_format_h fmt, i18n_unumber_format_attribute_e attr)
	Gets a numeric attribute associated with an i18n_unumber_format_h.
int	i18n_unumber_set_attribute (i18n_unumber_format_h fmt, i18n_unumber_format_attribute_e attr, int32_t new_value)
	Sets a numeric attribute associated with an i18n_unumber_format_h.
double	i18n_unumber_get_double_attribute (const i18n_unumber_format_h fmt, i18n_unumber_format_attribute_e attr)
	Gets a numeric attribute associated with an i18n_unumber_format_h.
int	i18n_unumber_set_double_attribute (i18n_unumber_format_h fmt, i18n_unumber_format_attribute_e attr, double new_value)
	Sets a numeric attribute associated with an i18n_unumber_format_h.
int32_t	i18n_unumber_get_text_attribute (const i18n_unumber_format_h fmt, i18n_unumber_format_text_attribute_e tag, i18n_uchar *result, int32_t result_length)
	Gets a text attribute associated with an i18n_unumber_format_h.
int	i18n_unumber_set_text_attribute (const i18n_unumber_format_h fmt, i18n_unumber_format_text_attribute_e tag, const i18n_uchar *new_value, int32_t new_value_length)
	Sets a text attribute associated with an i18n_unumber_format_h.
int32_t	i18n_unumber_to_pattern (const i18n_unumber_format_h fmt, i18n_ubool is_pattern_localized, i18n_uchar *result, int32_t result_length)
	Extracts the pattern from an i18n_unumber_format_h.
int	i18n_unumber_set_symbol (i18n_unumber_format_h fmt, i18n_unumber_format_symbol_e symbol, const i18n_uchar *value, int32_t length)
	Sets a symbol associated with an i18n_unumber_format_h.
const char *	i18n_unumber_get_locale_by_type (const i18n_unumber_format_h fmt, i18n_ulocale_data_locale_type_e type)
	Gets the locale for this number format object.
Typedefs
typedef void *	i18n_unumber_format_h
	A number formatter.
Defines
#define	I18N_U_PARSE_CONTEXT_LEN   16
	Definition of context length.

---

Define Documentation

#define I18N_U_PARSE_CONTEXT_LEN   16

Definition of context length.

Since :

2.3

---

Typedef Documentation

typedef void* i18n_unumber_format_h

A number formatter.

Since :

2.3

---

Enumeration Type Documentation

enum i18n_unumber_format_attribute_e

Enumeration for the possible unumber_format numeric attributes.

Since :

2.3.1

Enumerator:

I18N_UNUMBER_PARSE_INT_ONLY	Parse integers only
I18N_UNUMBER_GROUPING_USED	Use grouping separator
I18N_UNUMBER_DECIMAL_ALWAYS_SHOWN	Always show decimal point
I18N_UNUMBER_MAX_INTEGER_DIGITS	Maximum integer digits
I18N_UNUMBER_MIN_INTEGER_DIGITS	Minimum integer digits
I18N_UNUMBER_INTEGER_DIGITS	Integer digits
I18N_UNUMBER_MAX_FRACTION_DIGITS	Maximum fraction digits
I18N_UNUMBER_MIN_FRACTION_DIGITS	Minimum fraction digits
I18N_UNUMBER_FRACTION_DIGITS	Fraction digits
I18N_UNUMBER_MULTIPLIER	Multiplier
I18N_UNUMBER_GROUPING_SIZE	Grouping size
I18N_UNUMBER_ROUNDING_MODE	Rounding Mode
I18N_UNUMBER_ROUNDING_INCREMENT	Rounding increment
I18N_UNUMBER_FORMAT_WIDTH	The width to which the output of format() is padded
I18N_UNUMBER_PADDING_POSITION	The position at which padding will take place
I18N_UNUMBER_SECONDARY_GROUPING_SIZE	Secondary grouping size
I18N_UNUMBER_SIGNIFICANT_DIGITS_USED	Use significant digits
I18N_UNUMBER_MIN_SIGNIFICANT_DIGITS	Minimum significant digits
I18N_UNUMBER_MAX_SIGNIFICANT_DIGITS	Maximum significant digits
I18N_UNUMBER_LENIENT_PARSE	Lenient parse mode used by rule-based formats
I18N_UNUM_SCALE	Scale, which adjusts the position of the decimal point when formatting. Amounts will be multiplied by 10 ^ (scale) before they are formatted. The default value for the scale is 0 ( no adjustment ). Example: setting the scale to 3, 123 formats as "123,000" Example: setting the scale to -4, 123 formats as "0.0123"
I18N_UNUM_FORMAT_FAIL_IF_MORE_THAN_MAX_DIGITS	If 1, specifies that if setting the "max integer digits" attribute would truncate a value, set an error status rather than silently truncating. For example, formatting the value 1234 with 4 max int digits would succeed, but formatting 12345 would fail. There is no effect on parsing. Default: 0 (not set)
I18N_UNUM_PARSE_NO_EXPONENT	If this attribute is set to 1, specifies that, if the pattern doesn't contain an exponent, the exponent will not be parsed. If the pattern does contain an exponent, this attribute has no effect. Has no effect on formatting. Default: 0 (unset)

enum i18n_unumber_format_style_e

Enumeration for the possible number format styles.

Since :

2.3

Enumerator:

I18N_UNUMBER_PATTERN_DECIMAL	Decimal format defined by a pattern string
I18N_UNUMBER_DECIMAL	Decimal format ("normal" style)
I18N_UNUMBER_CURRENCY	Currency format with a currency symbol, e.g., "$1.00"
I18N_UNUMBER_PERCENT	Percent format
I18N_UNUMBER_SCIENTIFIC	Scientific format
I18N_UNUMBER_SPELLOUT	Spellout rule-based format
I18N_UNUMBER_ORDINAL	Ordinal rule-based format
I18N_UNUMBER_DURATION	Duration rule-based format
I18N_UNUMBER_NUMBERING_SYSTEM	Numbering system rule-based format
I18N_UNUMBER_PATTERN_RULEBASED	Rule-based format defined by a pattern string
I18N_UNUMBER_CURRENCY_ISO	Currency format with an ISO currency code, e.g., "USD1.00"
I18N_UNUMBER_CURRENCY_PLURAL	Currency format with a pluralized currency name, e.g., "1.00 US dollar" and "3.00 US dollars"
I18N_UNUMBER_CURRENCY_ACCOUNTING	Currency format for accounting, e.g., "($3.00)" for negative currency amount instead of "-$3.00" (Since 4.0)
I18N_UNUMBER_CASH_CURRENCY	Currency format with a currency symbol given CASH usage, e.g., "NT$3" instead of "NT$3.23" (Since 4.0)
I18N_UNUMBER_FORMAT_STYLE_COUNT	One more than the highest number format style constant
I18N_UNUMBER_DEFAULT	Default format
I18N_UNUMBER_IGNORE	Alias for I18N_UNUMBER_PATTERN_DECIMAL

enum i18n_unumber_format_symbol_e

Enumeration of constants for specifying a number format symbol.

Since :

2.3

Enumerator:

I18N_UNUMBER_DECIMAL_SEPARATOR_SYMBOL	The decimal separator
I18N_UNUMBER_GROUPING_SEPARATOR_SYMBOL	The grouping separator
I18N_UNUMBER_PATTERN_SEPARATOR_SYMBOL	The pattern separator
I18N_UNUMBER_PERCENT_SYMBOL	The percent sign
I18N_UNUMBER_ZERO_DIGIT_SYMBOL	Zero
I18N_UNUMBER_DIGIT_SYMBOL	Character representing a digit in the pattern.
I18N_UNUMBER_MINUS_SIGN_SYMBOL	The minus sign
I18N_UNUMBER_PLUS_SIGN_SYMBOL	The plus sign
I18N_UNUMBER_CURRENCY_SYMBOL	The currency symbol
I18N_UNUMBER_INTL_CURRENCY_SYMBOL	The international currency symbol
I18N_UNUMBER_MONETARY_SEPARATOR_SYMBOL	The monetary separator
I18N_UNUMBER_EXPONENTIAL_SYMBOL	The exponential symbol
I18N_UNUMBER_PERMILL_SYMBOL	Per mill symbol
I18N_UNUMBER_PAD_ESCAPE_SYMBOL	Escape padding character
I18N_UNUMBER_INFINITY_SYMBOL	Infinity symbol
I18N_UNUMBER_NAN_SYMBOL	NAN symbol
I18N_UNUMBER_SIGNIFICANT_DIGIT_SYMBOL	Significant digit symbol
I18N_UNUMBER_MONETARY_GROUPING_SEPARATOR_SYMBOL	The monetary grouping separator
I18N_UNUMBER_ONE_DIGIT_SYMBOL	One
I18N_UNUMBER_TWO_DIGIT_SYMBOL	Two
I18N_UNUMBER_THREE_DIGIT_SYMBOL	Three
I18N_UNUMBER_FOUR_DIGIT_SYMBOL	Four
I18N_UNUMBER_FIVE_DIGIT_SYMBOL	Five
I18N_UNUMBER_SIX_DIGIT_SYMBOL	Six
I18N_UNUMBER_SEVEN_DIGIT_SYMBOL	Seven
I18N_UNUMBER_EIGHT_DIGIT_SYMBOL	Eight
I18N_UNUMBER_NINE_DIGIT_SYMBOL	Nine
I18N_UNUMBER_FORMAT_SYMBOL_COUNT	Number of enumerators

enum i18n_unumber_format_text_attribute_e

The possible i18n_unumber_format_h text attributes.

Since :

2.3.1

Enumerator:

I18N_UNUMBER_POSITIVE_PREFIX	Positive prefix
I18N_UNUMBER_POSITIVE_SUFFIX	Positive suffix
I18N_UNUMBER_NEGATIVE_PREFIX	Negative prefix
I18N_UNUMBER_NEGATIVE_SUFFIX	Negative suffix
I18N_UNUMBER_PADDING_CHARACTER	The character used to pad to the format width
I18N_UNUMBER_CURRENCY_CODE	The ISO currency code
I18N_UNUMBER_DEFAULT_RULESET	The default rule set, such as "%spellout-numbering-year:", "%spellout-cardinal:", "%spellout-ordinal-masculine-plural:", "%spellout-ordinal-feminine:" or "%spellout-ordinal-neuter:". The available public rulesets can be listed using i18n_unumber_get_text_attribute() with I18N_UNUMBER_PUBLIC_RULESETS. This is only available with rule-based formatters
I18N_UNUMBER_PUBLIC_RULESETS	The public rule sets. This is only available with rule-based formatters. This is a read-only attribute. The public rulesets are returned as a single string, with each ruleset name delimited by ';' (semicolon). See the CLDR LDML spec for more information about RBNF rulesets: http://www.unicode.org/reports/tr35/tr35-numbers.html#Rule-Based_Number_Formatting

enum i18n_unumber_pad_position_e

Enumeration for the possible values of the I18N_UNUMBER_PADDING_POSITION attribute.

Since :

3.0

---

Function Documentation

int i18n_unumber_apply_pattern	(	i18n_unumber_format_h	format,
		i18n_ubool	localized,
		const i18n_uchar *	pattern,
		int32_t	pattern_length,
		i18n_uparse_error_s *	parse_error
	)

Sets the pattern used by an i18n_unumber_format_h.

This can only be used on a DecimalFormat, other formats return I18N_ERROR_NOT_SUPPORTED in the status.

Remarks:

Error codes are described in i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	format	The formatter to set.
[in]	localized	true if the pattern is localized, false otherwise.
[in]	pattern	The new pattern
[in]	pattern_length	The length of pattern, or -1 if NULL-terminated.
[out]	parse_error	A pointer to i18n_uparse_error_s to receive information about errors occurred during parsing, or NULL if no parse error information is desired.

Returns:

The obtained error code.

Return values:

I18N_ERROR_NONE	Successful.
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_unumber_clone	(	const i18n_unumber_format_h	fmt,
		i18n_unumber_format_h *	fmt_clone
	)

Creates a copy of an i18n_unumber_format_h.

This function performs a deep copy.

Remarks:

Error codes are described in i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The format to copy.
[out]	fmt_clone	A pointer to clone of fmt.

Returns:

The obtained error code.

Return values:

I18N_ERROR_NONE	Successful.
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int32_t i18n_unumber_count_available

(

void

)

Determines how many locales have decimal formatting patterns available.

The results of this call are not valid for rule-based number formats. This function is useful for determining the loop ending condition for calls to i18n_unumber_get_available().

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.

Since :

2.3.1

Returns:

The number of locales for which decimal formatting patterns are available.

Exceptions:

I18N_ERROR_NONE

Successful

int i18n_unumber_create	(	i18n_unumber_format_style_e	style,
		const i18n_uchar *	pattern,
		int32_t	pattern_len,
		const char *	locale,
		i18n_uparse_error_s *	parse_err,
		i18n_unumber_format_h *	num_format
	)

Creates and returns a new unumber_format_h for formatting and parsing numbers.

A unumber_format_style_e may be used to format numbers by calling i18n_unumber_create(). The caller must call i18n_unumber_destroy() when done to release resources used by this object.

Since :

2.3

Remarks:

Must release num_format using i18n_unumber_destroy().

Parameters:

[in]	style	The type of number format to create: one of I18N_UNUMBER_DECIMAL, I18N_UNUMBER_CURRENCY, I18N_UNUMBER_PERCENT, I18N_UNUMBER_SCIENTIFIC, I18N_UNUMBER_CURRENCY_ISO, I18N_UNUMBER_CURRENCY_PLURAL, I18N_UNUMBER_SPELLOUT, I18N_UNUMBER_ORDINAL, I18N_UNUMBER_DURATION, I18N_UNUMBER_NUMBERING_SYSTEM, I18N_UNUMBER_PATTERN_RULEBASED, or I18N_UNUMBER_DEFAULT If I18N_UNUMBER_PATTERN_DECIMAL or I18N_UNUMBER_PATTERN_RULEBASED is passed then the number format is created using the given pattern, which must conform to the syntax described in DecimalFormat or RuleBasedNumberFormat, respectively.
[in]	pattern	A pattern specifying the format to use This parameter is ignored unless the style is I18N_UNUMBER_PATTERN_DECIMAL or I18N_UNUMBER_PATTERN_RULEBASED.
[in]	pattern_len	The number of characters in the pattern, otherwise -1 if NULL-terminated This parameter is ignored unless the style is I18N_UNUMBER_PATTERN_*.
[in]	locale	A locale identifier to use to determine formatting and parsing conventions, otherwise NULL to use the default locale.
[in]	parse_err	A pointer to a i18n_uparse_error_s structure to receive the details of any parsing errors, otherwise NULL if no parsing error details are desired.
[out]	num_format	A pointer to a newly created i18n_unumber_format_h, otherwise NULL if an error occurs.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_unumber_destroy

(

i18n_unumber_format_h

fmt

)

Destroys an i18n_unumber_format_h.

Once destroyed, an i18n_unumber_format may no longer be used.

Since :

2.3

Parameters:

[in]

fmt

The formatter to destroy

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int32_t i18n_unumber_format	(	const i18n_unumber_format_h	fmt,
		int32_t	number,
		i18n_uchar *	result,
		int32_t	result_length,
		i18n_ufield_position_s *	pos,
		i18n_error_code_e *	status
	)

Formats an integer using a i18n_unumber_format_h.

The integer will be formatted according to the i18n_unumber_format_h's locale.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to use.
[in]	number	The number to format.
[out]	result	A pointer to a buffer to receive the NULL-terminated formatted number. If the formatted number fits into dest but cannot be NULL-terminated (length == resultLength) then the error code is set to I18N_WARNING_STRING_NOT_TERMINATED. If the formatted number doesn't fit into result then the error code is set to I18N_ERROR_BUFFER_OVERFLOW.
[in]	result_length	The maximum size of result.
[in]	pos	A pointer to a i18n_ufield_position. On input, position->field is read. On output, position->beginIndex and position->endIndex indicate the beginning and ending indices of field number position->field, if such a field exists. This parameter may be NULL, in which case no field
[out]	status	A pointer to an i18n_error_code_e to receive any errors

Returns:

The total buffer size needed; if greater than result_length, the output was truncated.

int32_t i18n_unumber_format_decimal	(	const i18n_unumber_format_h	fmt,
		const char *	number,
		int32_t	length,
		i18n_uchar *	result,
		int32_t	result_length,
		i18n_ufield_position_h	pos
	)

Formats a decimal number using an i18n_unumber_format_h.

The number will be formatted according to the i18n_unumber_format_h's locale. The syntax of the input number is a "numeric string" as defined in the Decimal Arithmetic Specification, available at http://speleotrove.com/decimal

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to use.
[in]	number	The number to format.
[in]	length	The length of the input number, or -1 if the input is NULL-terminated.
[out]	result	A pointer to a buffer to receive the NULL-terminated formatted number. If the formatted number fits into result but cannot be NULL-terminated (length == result_length) then the error code is set to I18N_WARNING_STRING_NOT_TERMINATED. If the formatted number doesn't fit into result then the error code is set to I18N_ERROR_BUFFER_OVERFLOW.
[in]	result_length	The maximum size of result.
[in,out]	pos	An i18n_ufield_position_h handle. On input, position->field is read. On output, position->beginIndex and position->endIndex indicate the beginning and ending indices of field number position->field, if such a field exists. This parameter may be NULL, in which case it is ignored.

Returns:

The total buffer size needed; if greater than result_length, the output was truncated.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_WARNING_STRING_NOT_TERMINATED	If the formatted number fits into result but cannot be NULL-terminated (length == result_length)
I18N_ERROR_BUFFER_OVERFLOW	If the formatted number doesn't fit into the result buffer

int32_t i18n_unumber_format_double	(	const i18n_unumber_format_h	fmt,
		double	number,
		i18n_uchar *	result,
		int32_t	result_length,
		i18n_ufield_position_h	pos
	)

Formats a double using an i18n_unumber_format_h.

The double will be formatted according to the i18n_unumber_format_h's locale.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to use.
[in]	number	The number to format.
[out]	result	A pointer to a buffer to receive the NULL-terminated formatted number. If the formatted number fits into result but cannot be NULL-terminated (length == result_length) then the error code is set to I18N_WARNING_STRING_NOT_TERMINATED. If the formatted number doesn't fit into result then the error code is set to I18N_ERROR_BUFFER_OVERFLOW.
[in]	result_length	The maximum size of result.
[in,out]	pos	An i18n_ufield_position_h handle. On input, position->field is read. On output, position->beginIndex and position->endIndex indicate the beginning and ending indices of field number position->field, if such a field exists. This parameter may be NULL, in which case no field

Returns:

The total buffer size needed; if greater than result_length, the output was truncated.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_WARNING_STRING_NOT_TERMINATED	If the formatted number fits into result but cannot be NULL-terminated (length == result_length)
I18N_ERROR_BUFFER_OVERFLOW	If the formatted number doesn't fit into the result buffer

int32_t i18n_unumber_format_double_currency	(	const i18n_unumber_format_h	fmt,
		double	number,
		i18n_uchar *	currency,
		i18n_uchar *	result,
		int32_t	result_length,
		i18n_ufield_position_h	pos
	)

Formats a double currency amount using an i18n_unumber_format_h.

The double will be formatted according to the i18n_unumber_format_h's locale.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to use.
[in]	number	The number to format.
[in]	currency	The 3-letter NULL-terminated ISO 4217 currency code.
[out]	result	A pointer to a buffer to receive the NULL-terminated formatted number. If the formatted number fits into result but cannot be NULL-terminated (length == result_length) then the error code is set to I18N_WARNING_STRING_NOT_TERMINATED. If the formatted number doesn't fit into result then the error code is set to I18N_ERROR_BUFFER_OVERFLOW.
[in]	result_length	The maximum size of result.
[in,out]	pos	An i18n_ufield_position_h handle. On input, position->field is read. On output, position->beginIndex and position->endIndex indicate the beginning and ending indices of field number position->field, if such a field exists. This parameter may be NULL, in which case it is ignored.

Returns:

The total buffer size needed; if greater than result_length, the output was truncated.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_WARNING_STRING_NOT_TERMINATED	If the formatted number fits into result but cannot be NULL-terminated (length == result_length)
I18N_ERROR_BUFFER_OVERFLOW	If the formatted number doesn't fit into the result buffer

int32_t i18n_unumber_format_int64	(	const i18n_unumber_format_h	fmt,
		int64_t	number,
		i18n_uchar *	result,
		int32_t	result_length,
		i18n_ufield_position_h	pos
	)

Formats an int64 using an i18n_unumber_format_h.

The int64 will be formatted according to the i18n_unumber_format_h's locale.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to use.
[in]	number	The number to format.
[out]	result	A pointer to a buffer to receive the NULL-terminated formatted number. If the formatted number fits into result but cannot be NULL-terminated (length == result_length) then the error code is set to I18N_WARNING_STRING_NOT_TERMINATED. If the formatted number doesn't fit into result then the error code is set to I18N_ERROR_BUFFER_OVERFLOW.
[in]	result_length	The maximum size of result.
[in,out]	pos	An i18n_ufield_position_h handle. On input, position->field is read. On output, position->beginIndex and position->endIndex indicate the beginning and ending indices of field number position->field, if such a field exists. This parameter may be NULL, in which case no field

Returns:

The total buffer size needed; if greater than result_length, the output was truncated.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_WARNING_STRING_NOT_TERMINATED	If the formatted number fits into result but cannot be NULL-terminated (length == result_length)
I18N_ERROR_BUFFER_OVERFLOW	If the formatted number doesn't fit into the result buffer

int32_t i18n_unumber_get_attribute	(	const i18n_unumber_format_h	fmt,
		i18n_unumber_format_attribute_e	attr
	)

Gets a numeric attribute associated with an i18n_unumber_format_h.

An example of a numeric attribute is the number of integer digits a formatter will produce.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to query.
[in]	attr	The attribute to query; one of I18N_UNUMBER_PARSE_INT_ONLY, I18N_UNUMBER_GROUPING_USED, I18N_UNUMBER_DECIMAL_ALWAYS_SHOWN, I18N_UNUMBER_MAX_INTEGER_DIGITS, I18N_UNUMBER_MIN_INTEGER_DIGITS, I18N_UNUMBER_INTEGER_DIGITS, I18N_UNUMBER_MAX_FRACTION_DIGITS, I18N_UNUMBER_MIN_FRACTION_DIGITS, I18N_UNUMBER_FRACTION_DIGITS, I18N_UNUMBER_MULTIPLIER, I18N_UNUMBER_GROUPING_SIZE, I18N_UNUMBER_ROUNDING_MODE, I18N_UNUMBER_FORMAT_WIDTH, I18N_UNUMBER_PADDING_POSITION, I18N_UNUMBER_SECONDARY_GROUPING_SIZE, I18N_UNUM_SCALE.

Returns:

The value of attr or -1 if the given attribute is not supported.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

const char* i18n_unumber_get_available

(

int32_t

locale_index

)

Gets a locale for which decimal formatting patterns are available.

An i18n_unumber_format_h in a locale returned by this function will perform the correct formatting and parsing for the locale. The results of this call are not valid for rule-based number formats.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.

Since :

2.3.1

Parameters:

[in]

locale_index

The index of the desired locale.

Returns:

A locale for which number formatting patterns are available, or 0 if none.

Exceptions:

I18N_ERROR_NONE

Successful

double i18n_unumber_get_double_attribute	(	const i18n_unumber_format_h	fmt,
		i18n_unumber_format_attribute_e	attr
	)

Gets a numeric attribute associated with an i18n_unumber_format_h.

An example of a numeric attribute is the number of integer digits a formatter will produce. If the formatter does not understand the attribute, -1 is returned.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to query.
[in]	attr	The attribute to query; only I18N_UNUMBER_ROUNDING_INCREMENT is supported.

Returns:

The value of attr.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

const char* i18n_unumber_get_locale_by_type	(	const i18n_unumber_format_h	fmt,
		i18n_ulocale_data_locale_type_e	type
	)

Gets the locale for this number format object.

You can choose between valid and actual locale.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to get the locale from.
[in]	type	Type of the locale we're looking for (valid or actual)

Returns:

The locale name

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_unumber_get_symbol	(	const i18n_unumber_format_h	fmt,
		i18n_unumber_format_symbol_e	symbol,
		i18n_uchar *	buffer,
		int32_t	size,
		int32_t *	len_symbol
	)

Gets a symbol associated with an i18n_unumber_format_h.

An i18n_unumber_format_h uses symbols to represent the special locale-dependent characters in a number, for example the percent sign. This API is not supported for rule-based formatters.

Since :

2.3

Parameters:

[in]	fmt	The formatter to query.
[in]	symbol	The unumber_format_symbol_e constant for the symbol to get
[out]	buffer	The string buffer that will receive the symbol string If it is NULL, then only the length of the symbol is returned.
[in]	size	The size of the string buffer
[out]	len_symbol	The length of the symbol The buffer is not modified if length >= size

Return values:

I18N_ERROR_NONE	Successful.
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int32_t i18n_unumber_get_text_attribute	(	const i18n_unumber_format_h	fmt,
		i18n_unumber_format_text_attribute_e	tag,
		i18n_uchar *	result,
		int32_t	result_length
	)

Gets a text attribute associated with an i18n_unumber_format_h.

An example of a text attribute is the suffix for positive numbers. If the formatter does not understand the attribute, I18N_ERROR_NOT_SUPPORTED error code is set. Rule-based formatters only understand I18N_UNUMBER_DEFAULT_RULESET and I18N_UNUMBER_PUBLIC_RULESETS.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to query.
[in]	tag	The attribute to query; one of I18N_UNUMBER_POSITIVE_PREFIX, I18N_UNUMBER_POSITIVE_SUFFIX, I18N_UNUMBER_NEGATIVE_PREFIX, I18N_UNUMBER_NEGATIVE_SUFFIX, I18N_UNUMBER_PADDING_CHARACTER, I18N_UNUMBER_CURRENCY_CODE, I18N_UNUMBER_DEFAULT_RULESET, or I18N_UNUMBER_PUBLIC_RULESETS.
[out]	result	A pointer to a buffer to receive the attribute.
[in]	result_length	The maximum size of result.

Returns:

The total buffer size needed; if greater than result_length, the output was truncated.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int32_t i18n_unumber_parse	(	const i18n_unumber_format_h	fmt,
		const i18n_uchar *	text,
		int32_t	text_length,
		int32_t *	parse_pos
	)

Parses a string into an integer using an i18n_unumber_format_h.

The string will be parsed according to the i18n_unumber_format_h's locale.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to use.
[in]	text	The text to parse.
[in]	text_length	The length of text, or -1 if NULL-terminated.
[in,out]	parse_pos	If not NULL, on input a pointer to an integer specifying the offset at which to begin parsing. If not NULL, on output the offset at which parsing ended.

Returns:

The value of the parsed integer

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int32_t i18n_unumber_parse_decimal	(	const i18n_unumber_format_h	fmt,
		const i18n_uchar *	text,
		int32_t	text_length,
		int32_t *	parse_pos,
		char *	out_buf,
		int32_t	out_buf_length
	)

Parses a number from a string into an unformatted numeric string using an i18n_unumber_format_h.

The input string will be parsed according to the i18n_unumber_format_h's locale. The syntax of the output is a "numeric string" as defined in the Decimal Arithmetic Specification, available at http://speleotrove.com/decimal

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to use.
[in]	text	The text to parse.
[in]	text_length	The length of text, or -1 if NULL-terminated.
[in,out]	parse_pos	If not NULL, on input a pointer to an integer specifying the offset at which to begin parsing. If not NULL, on output the offset at which parsing ended.
[out]	out_buf	A (char *) buffer to receive the parsed number as a string. The output string will be NULL-terminated if there is sufficient space.
[out]	out_buf_length	The size of the output buffer. May be zero, in which case the out_buf pointer may be NULL, and the function will return the size of the output string.

Returns:

The length of the output string, not including any terminating NULL.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

double i18n_unumber_parse_double	(	const i18n_unumber_format_h	fmt,
		const i18n_uchar *	text,
		int32_t	text_length,
		int32_t *	parse_pos
	)

Parses a string into a double using an i18n_unumber_format_h.

The string will be parsed according to the i18n_unumber_format_h's locale.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to use.
[in]	text	The text to parse.
[out]	text_length	The length of text, or -1 if NULL-terminated.
[in,out]	parse_pos	If not NULL, on input a pointer to an integer specifying the offset at which to begin parsing. If not NULL, on output the offset at which parsing ended.

Returns:

The value of the parsed double

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

double i18n_unumber_parse_double_currency	(	const i18n_unumber_format_h	fmt,
		const i18n_uchar *	text,
		int32_t	text_length,
		int32_t *	parse_pos,
		i18n_uchar *	currency
	)

Parses a string into a double and a currency using an i18n_unumber_format_h.

The string will be parsed according to the i18n_unumber_format_h's locale.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to use.
[in]	text	The text to parse.
[in]	text_length	The length of text, or -1 if NULL-terminated.
[in,out]	parse_pos	A pointer to an offset index into text at which to begin parsing. On output, parse_pos will point after the last parsed character. This parameter may be NULL, in which case parsing begins at offset 0. If not NULL, on output the offset at which parsing ended.
[out]	currency	A pointer to the buffer to receive the parsed NULL- terminated currency. This buffer must have a capacity of at least 4 i18n_uchar characters.

Returns:

The parsed double

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int64_t i18n_unumber_parse_int64	(	const i18n_unumber_format_h	fmt,
		const i18n_uchar *	text,
		int32_t	text_length,
		int32_t *	parse_pos
	)

Parses a string into an int64 using an i18n_unumber_format_h.

The string will be parsed according to the i18n_unumber_format_h's locale.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to use.
[in]	text	The text to parse.
[in]	text_length	The length of text, or -1 if NULL-terminated.
[in,out]	parse_pos	If not NULL, on input a pointer to an integer specifying the offset at which to begin parsing. If not NULL, on output the offset at which parsing ended.

Returns:

The value of the parsed integer

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_unumber_set_attribute	(	i18n_unumber_format_h	fmt,
		i18n_unumber_format_attribute_e	attr,
		int32_t	new_value
	)

Sets a numeric attribute associated with an i18n_unumber_format_h.

An example of a numeric attribute is the number of integer digits a formatter will produce. If the formatter does not understand the attribute, the call is ignored. Rule-based formatters only understand the lenient-parse attribute. The I18N_UNUMBER_ROUNDING_INCREMENT attribute is not supported.

Note that the value for the I18N_UNUMBER_PADDING_POSITION attribute should be one of the i18n_unumber_pad_position_e enumeration values.

Remarks:

Error codes are described in i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to set.
[in]	attr	The attribute to query; one of I18N_UNUMBER_PARSE_INT_ONLY, I18N_UNUMBER_GROUPING_USED, I18N_UNUMBER_DECIMAL_ALWAYS_SHOWN, I18N_UNUMBER_MAX_INTEGER_DIGITS, I18N_UNUMBER_MIN_INTEGER_DIGITS, I18N_UNUMBER_INTEGER_DIGITS, I18N_UNUMBER_MAX_FRACTION_DIGITS, I18N_UNUMBER_MIN_FRACTION_DIGITS, I18N_UNUMBER_FRACTION_DIGITS, I18N_UNUMBER_MULTIPLIER, I18N_UNUMBER_GROUPING_SIZE, I18N_UNUMBER_ROUNDING_MODE, I18N_UNUMBER_FORMAT_WIDTH, I18N_UNUMBER_PADDING_POSITION, I18N_UNUMBER_SECONDARY_GROUPING_SIZE, I18N_UNUMBER_SIGNIFICANT_DIGITS_USED, I18N_UNUMBER_MIN_SIGNIFICANT_DIGITS, I18N_UNUMBER_MAX_SIGNIFICANT_DIGITS, I18N_UNUMBER_LENIENT_PARSE, I18N_UNUM_SCALE, I18N_UNUM_FORMAT_FAIL_IF_MORE_THAN_MAX_DIGITS, I18N_UNUM_PARSE_NO_EXPONENT.
[in]	new_value	The new value of attr.

Returns:

The obtained error code.

Return values:

I18N_ERROR_NONE	Successful.
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_NOT_SUPPORTED	Not supported

int i18n_unumber_set_double_attribute	(	i18n_unumber_format_h	fmt,
		i18n_unumber_format_attribute_e	attr,
		double	new_value
	)

Sets a numeric attribute associated with an i18n_unumber_format_h.

An example of a numeric attribute is the number of integer digits a formatter will produce. If the formatter does not understand the attribute, this call is ignored.

Remarks:

Error codes are described in i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to set.
[in]	attr	The attribute to query; Only I18N_UNUMBER_ROUNDING_INCREMENT is supported.
[in]	new_value	The new value of attr.

Returns:

The obtained error code.

Return values:

I18N_ERROR_NONE	Successful.
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_unumber_set_symbol	(	i18n_unumber_format_h	fmt,
		i18n_unumber_format_symbol_e	symbol,
		const i18n_uchar *	value,
		int32_t	length
	)

Sets a symbol associated with an i18n_unumber_format_h.

An i18n_unumber_format_h uses symbols to represent the special locale-dependent characters in a number, for example the percent sign. This API is not supported for rule-based formatters.

Remarks:

Error codes are described in i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to set.
[in]	symbol	The i18n_unumber_format_symbol_e constant for the symbol to set
[in]	value	The string to set the symbol to
[in]	length	The length of the input string, or -1 for a zero-terminated string

Returns:

The obtained error code.

Return values:

I18N_ERROR_NONE	Successful.
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_unumber_set_text_attribute	(	const i18n_unumber_format_h	fmt,
		i18n_unumber_format_text_attribute_e	tag,
		const i18n_uchar *	new_value,
		int32_t	new_value_length
	)

Sets a text attribute associated with an i18n_unumber_format_h.

An example of a text attribute is the suffix for positive numbers. Rule-based formatters only understand I18N_UNUMBER_DEFAULT_RULESET. The I18N_UNUMBER_PUBLIC_RULESETS tag is not supported.

Remarks:

Error codes are described in i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to set.
[in]	tag	The attribute to set; one of I18N_UNUMBER_POSITIVE_PREFIX, I18N_UNUMBER_POSITIVE_SUFFIX, I18N_UNUMBER_NEGATIVE_PREFIX, I18N_UNUMBER_NEGATIVE_SUFFIX, I18N_UNUMBER_PADDING_CHARACTER, I18N_UNUMBER_CURRENCY_CODE, I18N_UNUMBER_DEFAULT_RULESET.
[in]	new_value	The new value of tag.
[in]	new_value_length	The length of new_value, or -1 if NULL-terminated.

Returns:

The obtained error code.

Return values:

I18N_ERROR_NONE	Successful.
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int32_t i18n_unumber_to_pattern	(	const i18n_unumber_format_h	fmt,
		i18n_ubool	is_pattern_localized,
		i18n_uchar *	result,
		int32_t	result_length
	)

Extracts the pattern from an i18n_unumber_format_h.

The pattern will follow the DecimalFormat pattern syntax.

Remarks:

The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :

2.3.1

Parameters:

[in]	fmt	The formatter to query.
[in]	is_pattern_localized	true if the pattern should be localized, false otherwise. This is ignored if the formatter is a rule-based formatter.
[out]	result	A pointer to a buffer to receive the pattern.
[in]	result_length	The maximum size of result.

Returns:

The total buffer size needed; if greater than result_length, the output was truncated.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter