C API: UNumberingSystem, information about numbering systems.

Required Header

#include <utils_i18n.h>

Overview

Defines numbering systems. A numbering system describes the scheme by which numbers are to be presented to the end user. In its simplest form, a numbering system describes the set of digit characters that are to be used to display numbers, such as Western digits, Thai digits, Arabic-Indic digits, etc., in a positional numbering system with a specified radix (typically 10). More complicated numbering systems are algorithmic in nature, and require use of an RBNF formatter (rule based number formatter), in order to calculate the characters to be displayed for a given number. Examples of algorithmic numbering systems include Roman numerals, Chinese numerals, and Hebrew numerals. Formatting rules for many commonly used numbering systems are included in the ICU package, based on the numbering system rules defined in CLDR. Alternate numbering systems can be specified to a locale by using the numbers locale keyword. Formatting numbers is done using the Unumber API.

Functions
int	i18n_unumsys_create (const char locale, i18n_unumsys_h unumsys)
	Creates an i18n_unumsys_h using the numbering system for the specified locale.
int	i18n_unumsys_create_by_name (const char name, i18n_unumsys_h unumsys)
	Creates an i18n_unumsys_h using the name of one of the predefined numbering systems specified by CLDR and known to ICU, such as "latn", "arabext", or "hanidec"; the full list is returned by i18n_unumsys_get_available_names.
void	i18n_unumsys_destroy (i18n_unumsys_h unumsys)
	Destroys an i18n_unumsys_h.
int	i18n_unumsys_get_available_names (i18n_uenumeration_h *uenum)
	Returns an enumeration over the names of all of the predefined numbering systems known to ICU.
int	i18n_unumsys_get_name (i18n_unumsys_h unumsys, const char **name)
	Returns the name of the specified i18n_unumsys_h.
int	i18n_unumsys_is_algorithmic (i18n_unumsys_h unumsys, i18n_ubool *is_algorithmic)
	Returns whether the given i18n_unumsys_h is for an algorithmic (not purely positional) system.
int	i18n_unumsys_get_radix (i18n_unumsys_h unumsys, int32_t *radix)
	Returns the radix of the specified i18n_unumsys_h.
int	i18n_unumsys_get_description (i18n_unumsys_h unumsys, i18n_uchar result, int32_t result_max_len, int32_t ulen)
	Gets the description string of the specified i18n_unumsys_h.
Typedefs
typedef void *	i18n_unumsys_h
	An i18n_unumsys_h handle.

Typedef Documentation

typedef void* i18n_unumsys_h

An i18n_unumsys_h handle.

Since :: 6.0

Function Documentation

int i18n_unumsys_create	(	const char *	locale,
		i18n_unumsys_h *	unumsys
	)

Creates an i18n_unumsys_h using the numbering system for the specified locale.

Since :: 6.0

Parameters:

[in]	locale	The locale for which the default numbering system should be created.
[out]	unumsys	An i18n_unumsys_h handle for the specified locale, or NULL if an error occurred.

Remarks:: The unumsys should be released using i18n_unumsys_destroy().

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_NOT_SUPPORTED	A locale such as "en@numbers=xyz" that specifies a numbering system unknown to ICU.
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_unumsys_create_by_name	(	const char *	name,
		i18n_unumsys_h *	unumsys
	)

Creates an i18n_unumsys_h using the name of one of the predefined numbering systems specified by CLDR and known to ICU, such as "latn", "arabext", or "hanidec"; the full list is returned by i18n_unumsys_get_available_names.

Since :: 6.0

Parameters:

[in]	name	The name of the numbering system for which an i18n_unumsys_h should be created.
[out]	unumsys	An i18n_unumsys_h handle for the specified name, or NULL if an error occurred.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_NOT_SUPPORTED	A numbering system unknown to ICU.
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

void i18n_unumsys_destroy ( i18n_unumsys_h unumsys )

Destroys an i18n_unumsys_h.

Once closed it may no longer be used.

Since :: 6.0

Parameters:

[in] unumsys The i18n_unumsys_h to destroy.

int i18n_unumsys_get_available_names ( i18n_uenumeration_h * uenum )

Returns an enumeration over the names of all of the predefined numbering systems known to ICU.

The numbering system names will be in alphabetical (invariant) order.

Since :: 6.0

Parameters:

[out] uenum A pointer to a i18n_uenumeration_h that must be closed with i18n_uenumeration_destroy(), or NULL if an error occurred.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_unumsys_get_description	(	i18n_unumsys_h	unumsys,
		i18n_uchar *	result,
		int32_t	result_max_len,
		int32_t *	ulen
	)

Gets the description string of the specified i18n_unumsys_h.

For simple positional systems this is the ordered string of digits (with length matching the radix), e.g. "\u3007\u4E00\u4E8C\u4E09\u56DB\u4E94\u516D\u4E03\u516B\u4E5D" for "hanidec"; it would be "0123456789ABCDEF" for hexadecimal.

For algorithmic systems this is the name of the RBNF ruleset used for formatting, e.g. "zh/SpelloutRules/%spellout-cardinal" for "hans" or "%greek-upper" for "grek".

Since :: 6.0

Parameters:

[in]	unumsys	The i18n_unumsys_h whose description string is desired.
[in]	result	A pointer to a buffer to receive the description string.
[in]	result_max_len	The maximum size of result.
[out]	ulen	The total buffer size needed; if greater than result_length, the output was truncated.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_unumsys_get_name	(	i18n_unumsys_h	unumsys,
		const char **	name
	)

Returns the name of the specified i18n_unumsys_h.

Since :: 6.0

Parameters:

[in]	unumsys	The i18n_unumsys_h whose name is desired.
[out]	name	A pointer to the name of the specified i18n_unumsys_h, or NULL if the name is not one of the ICU predefined names. The pointer is only valid for the lifetime of the i18n_unumsys_h.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_unumsys_get_radix	(	i18n_unumsys_h	unumsys,
		int32_t *	radix
	)

Returns the radix of the specified i18n_unumsys_h.

Simple positional numbering systems typically have radix 10, but might have a radix of e.g. 16 for hexadecimal. The radix is less well-defined for non-positional algorithmic systems.

Since :: 6.0

Parameters:

[in]	unumsys	The i18n_unumsys_h whose radix is desired.
[out]	radix	The radix of the specified i18n_unumsys_h.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_unumsys_is_algorithmic	(	i18n_unumsys_h	unumsys,
		i18n_ubool *	is_algorithmic
	)

Returns whether the given i18n_unumsys_h is for an algorithmic (not purely positional) system.

Since :: 6.0

Parameters:

[in]	unumsys	The i18n_unumsys_h whose algorithmic status is desired.
[out]	is_algorithmic	TRUE if the specified i18n_unumsys_h is for an algorithmic system.

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation