Tizen(Headless) Native API  6.5

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

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)

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

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

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

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]formatThe formatter to set.
[in]localizedtrue if the pattern is localized, false otherwise.
[in]patternThe new pattern
[in]pattern_lengthThe length of pattern, or -1 if NULL-terminated.
[out]parse_errorA 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_NONESuccessful.
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe format to copy.
[out]fmt_cloneA pointer to clone of fmt.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful.
I18N_ERROR_INVALID_PARAMETERInvalid 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_NONESuccessful
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]styleThe 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]patternA 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_lenThe number of characters in the pattern, otherwise -1 if NULL-terminated
This parameter is ignored unless the style is I18N_UNUMBER_PATTERN_*.
[in]localeA locale identifier to use to determine formatting and parsing conventions, otherwise NULL to use the default locale.
[in]parse_errA 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_formatA pointer to a newly created i18n_unumber_format_h, otherwise NULL if an error occurs.
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter

Destroys an i18n_unumber_format_h.

Once destroyed, an i18n_unumber_format may no longer be used.

Since :
2.3
Parameters:
[in]fmtThe formatter to destroy
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to use.
[in]numberThe number to format.
[out]resultA 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_lengthThe maximum size of result.
[in]posA 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]statusA 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]fmtThe formatter to use.
[in]numberThe number to format.
[in]lengthThe length of the input number, or -1 if the input is NULL-terminated.
[out]resultA 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_lengthThe maximum size of result.
[in,out]posAn 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_WARNING_STRING_NOT_TERMINATEDIf the formatted number fits into result but cannot be NULL-terminated (length == result_length)
I18N_ERROR_BUFFER_OVERFLOWIf 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]fmtThe formatter to use.
[in]numberThe number to format.
[out]resultA 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_lengthThe maximum size of result.
[in,out]posAn 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_WARNING_STRING_NOT_TERMINATEDIf the formatted number fits into result but cannot be NULL-terminated (length == result_length)
I18N_ERROR_BUFFER_OVERFLOWIf 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]fmtThe formatter to use.
[in]numberThe number to format.
[in]currencyThe 3-letter NULL-terminated ISO 4217 currency code.
[out]resultA 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_lengthThe maximum size of result.
[in,out]posAn 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_WARNING_STRING_NOT_TERMINATEDIf the formatted number fits into result but cannot be NULL-terminated (length == result_length)
I18N_ERROR_BUFFER_OVERFLOWIf 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]fmtThe formatter to use.
[in]numberThe number to format.
[out]resultA 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_lengthThe maximum size of result.
[in,out]posAn 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_WARNING_STRING_NOT_TERMINATEDIf the formatted number fits into result but cannot be NULL-terminated (length == result_length)
I18N_ERROR_BUFFER_OVERFLOWIf the formatted number doesn't fit into the result buffer

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]fmtThe formatter to query.
[in]attrThe 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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_indexThe index of the desired locale.
Returns:
A locale for which number formatting patterns are available, or 0 if none.
Exceptions:
I18N_ERROR_NONESuccessful

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]fmtThe formatter to query.
[in]attrThe attribute to query; only I18N_UNUMBER_ROUNDING_INCREMENT is supported.
Returns:
The value of attr.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter

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]fmtThe formatter to get the locale from.
[in]typeType of the locale we're looking for (valid or actual)
Returns:
The locale name
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to query.
[in]symbolThe unumber_format_symbol_e constant for the symbol to get
[out]bufferThe string buffer that will receive the symbol string
If it is NULL, then only the length of the symbol is returned.
[in]sizeThe size of the string buffer
[out]len_symbolThe length of the symbol
The buffer is not modified if length >= size
Return values:
I18N_ERROR_NONESuccessful.
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to query.
[in]tagThe 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]resultA pointer to a buffer to receive the attribute.
[in]result_lengthThe maximum size of result.
Returns:
The total buffer size needed; if greater than result_length, the output was truncated.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to use.
[in]textThe text to parse.
[in]text_lengthThe length of text, or -1 if NULL-terminated.
[in,out]parse_posIf 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to use.
[in]textThe text to parse.
[in]text_lengthThe length of text, or -1 if NULL-terminated.
[in,out]parse_posIf 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_bufA (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_lengthThe 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to use.
[in]textThe text to parse.
[out]text_lengthThe length of text, or -1 if NULL-terminated.
[in,out]parse_posIf 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to use.
[in]textThe text to parse.
[in]text_lengthThe length of text, or -1 if NULL-terminated.
[in,out]parse_posA 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]currencyA 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to use.
[in]textThe text to parse.
[in]text_lengthThe length of text, or -1 if NULL-terminated.
[in,out]parse_posIf 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter

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]fmtThe formatter to set.
[in]attrThe 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_valueThe new value of attr.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful.
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_NOT_SUPPORTEDNot supported

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]fmtThe formatter to set.
[in]attrThe attribute to query; Only I18N_UNUMBER_ROUNDING_INCREMENT is supported.
[in]new_valueThe new value of attr.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful.
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to set.
[in]symbolThe i18n_unumber_format_symbol_e constant for the symbol to set
[in]valueThe string to set the symbol to
[in]lengthThe length of the input string, or -1 for a zero-terminated string
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful.
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to set.
[in]tagThe 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_valueThe new value of tag.
[in]new_value_lengthThe length of new_value, or -1 if NULL-terminated.
Returns:
The obtained error code.
Return values:
I18N_ERROR_NONESuccessful.
I18N_ERROR_INVALID_PARAMETERInvalid 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]fmtThe formatter to query.
[in]is_pattern_localizedtrue if the pattern should be localized, false otherwise. This is ignored if the formatter is a rule-based formatter.
[out]resultA pointer to a buffer to receive the pattern.
[in]result_lengthThe maximum size of result.
Returns:
The total buffer size needed; if greater than result_length, the output was truncated.
Exceptions:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter