ICU 74.2: i18n/unicode/unumsys.h File Reference

ICU 74.2 74.2

Namespaces | Typedefs | Functions
unumsys.h File Reference

C API: UNumberingSystem, information about numbering systems. More...

`#include "unicode/utypes.h"`
`#include "unicode/uenum.h"`
`#include "unicode/localpointer.h"`

Go to the source code of this file.

## Namespaces
namespace | icu
| File coll.h.

## Typedefs
typedef struct UNumberingSystem | UNumberingSystem
| C typedef for struct UNumberingSystem.

## Functions
U_CAPI UNumberingSystem * | unumsys_open (const char *locale, UErrorCode *status)
| Opens a UNumberingSystem object using the default numbering system for the specified locale.
U_CAPI UNumberingSystem * | unumsys_openByName (const char *name, UErrorCode *status)
| Opens a UNumberingSystem object 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 unumsys_openAvailableNames.
U_CAPI void | unumsys_close (UNumberingSystem *unumsys)
| Close a UNumberingSystem object.
U_CAPI UEnumeration * | unumsys_openAvailableNames (UErrorCode *status)
| Returns an enumeration over the names of all of the predefined numbering systems known to ICU.
U_CAPI const char * | unumsys_getName (const UNumberingSystem *unumsys)
| Returns the name of the specified UNumberingSystem object (if it is one of the predefined names known to ICU).
U_CAPI UBool | unumsys_isAlgorithmic (const UNumberingSystem *unumsys)
| Returns whether the given UNumberingSystem object is for an algorithmic (not purely positional) system.
U_CAPI int32_t | unumsys_getRadix (const UNumberingSystem *unumsys)
| Returns the radix of the specified UNumberingSystem object.
U_CAPI int32_t | unumsys_getDescription (const UNumberingSystem *unumsys, UChar *result, int32_t resultLength, UErrorCode *status)
| Get the description string of the specified UNumberingSystem object.

## Detailed Description

C API: UNumberingSystem, information about numbering systems.

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.

Definition in file unumsys.h.

## Typedef Documentation

## ◆ UNumberingSystem

typedef struct UNumberingSystem UNumberingSystem

C typedef for struct UNumberingSystem.

Stable:
  ICU 52

Definition at line 47 of file unumsys.h.

## Function Documentation

## ◆ unumsys_close()

U_CAPI void unumsys_close | ( | UNumberingSystem * | unumsys | ) |

Close a UNumberingSystem object.

Once closed it may no longer be used.

Parameters

  unumsys | The UNumberingSystem object to close.

Stable:
  ICU 52

## ◆ unumsys_getDescription()

U_CAPI int32_t unumsys_getDescription | ( | const UNumberingSystem * | unumsys,
|  | UChar * | result,
|  | int32_t | resultLength,
|  | UErrorCode * | status
| ) |  |

Get the description string of the specified UNumberingSystem object.

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

Parameters

  unumsys | The UNumberingSystem whose description string is desired.
  result | A pointer to a buffer to receive the description string.
  resultLength | The maximum size of result.
  status | A pointer to a UErrorCode to receive any errors.

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

Stable:
  ICU 52

## ◆ unumsys_getName()

U_CAPI const char * unumsys_getName | ( | const UNumberingSystem * | unumsys | ) |

Returns the name of the specified UNumberingSystem object (if it is one of the predefined names known to ICU).

Parameters

  unumsys | The UNumberingSystem whose name is desired.

Returns
  A pointer to the name of the specified UNumberingSystem object, or NULL if the name is not one of the ICU predefined names. The pointer is only valid for the lifetime of the UNumberingSystem object.

Stable:
  ICU 52

## ◆ unumsys_getRadix()

U_CAPI int32_t unumsys_getRadix | ( | const UNumberingSystem * | unumsys | ) |

Returns the radix of the specified UNumberingSystem object.

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.

Parameters

  unumsys | The UNumberingSystem whose radix is desired.

Returns
  The radix of the specified UNumberingSystem object.

Stable:
  ICU 52

## ◆ unumsys_isAlgorithmic()

U_CAPI UBool unumsys_isAlgorithmic | ( | const UNumberingSystem * | unumsys | ) |

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

Parameters

  unumsys | The UNumberingSystem whose algorithmic status is desired.

Returns
  true if the specified UNumberingSystem object is for an algorithmic system.

Stable:
  ICU 52

## ◆ unumsys_open()

U_CAPI UNumberingSystem * unumsys_open | ( | const char * | locale,
|  | UErrorCode * | status
| ) |  |

Opens a UNumberingSystem object using the default numbering system for the specified locale.

Parameters

  locale | The locale for which the default numbering system should be opened.
  status | A pointer to a UErrorCode to receive any errors. For example, this may be U_UNSUPPORTED_ERROR for a locale such as "en@numbers=xyz" that specifies a numbering system unknown to ICU.

Returns
  A UNumberingSystem for the specified locale, or NULL if an error occurred.

Stable:
  ICU 52

## ◆ unumsys_openAvailableNames()

U_CAPI UEnumeration * unumsys_openAvailableNames | ( | UErrorCode * | status | ) |

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.

Parameters

  status | A pointer to a UErrorCode to receive any errors.

Returns
  A pointer to a UEnumeration that must be closed with uenum_close(), or NULL if an error occurred.

Stable:
  ICU 52

## ◆ unumsys_openByName()

U_CAPI UNumberingSystem * unumsys_openByName | ( | const char * | name,
|  | UErrorCode * | status
| ) |  |

Opens a UNumberingSystem object 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 unumsys_openAvailableNames.

Note that some of the names listed at http://unicode.org/repos/cldr/tags/latest/common/bcp47/number.xml - e.g. default, native, traditional, finance - do not identify specific numbering systems, but rather key values that may only be used as part of a locale, which in turn defines how they are mapped to a specific numbering system such as "latn" or "hant".

Parameters

  name | The name of the numbering system for which a UNumberingSystem object should be opened.
  status | A pointer to a UErrorCode to receive any errors. For example, this may be U_UNSUPPORTED_ERROR for a numbering system such as "xyz" that is unknown to ICU.

Returns
  A UNumberingSystem for the specified name, or NULL if an error occurred.

Stable:
  ICU 52