jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: ***************************************************************************************** jpayne@69: * Copyright (C) 2013-2014, International Business Machines jpayne@69: * Corporation and others. All Rights Reserved. jpayne@69: ***************************************************************************************** jpayne@69: */ jpayne@69: jpayne@69: #ifndef UNUMSYS_H jpayne@69: #define UNUMSYS_H jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: jpayne@69: #include "unicode/uenum.h" jpayne@69: #include "unicode/localpointer.h" jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C API: UNumberingSystem, information about numbering systems jpayne@69: * jpayne@69: * Defines numbering systems. A numbering system describes the scheme by which jpayne@69: * numbers are to be presented to the end user. In its simplest form, a numbering jpayne@69: * system describes the set of digit characters that are to be used to display jpayne@69: * numbers, such as Western digits, Thai digits, Arabic-Indic digits, etc., in a jpayne@69: * positional numbering system with a specified radix (typically 10). jpayne@69: * More complicated numbering systems are algorithmic in nature, and require use jpayne@69: * of an RBNF formatter (rule based number formatter), in order to calculate jpayne@69: * the characters to be displayed for a given number. Examples of algorithmic jpayne@69: * numbering systems include Roman numerals, Chinese numerals, and Hebrew numerals. jpayne@69: * Formatting rules for many commonly used numbering systems are included in jpayne@69: * the ICU package, based on the numbering system rules defined in CLDR. jpayne@69: * Alternate numbering systems can be specified to a locale by using the jpayne@69: * numbers locale keyword. jpayne@69: */ jpayne@69: jpayne@69: /** jpayne@69: * Opaque UNumberingSystem object for use in C programs. jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: struct UNumberingSystem; jpayne@69: typedef struct UNumberingSystem UNumberingSystem; /**< C typedef for struct UNumberingSystem. @stable ICU 52 */ jpayne@69: jpayne@69: /** jpayne@69: * Opens a UNumberingSystem object using the default numbering system for the specified jpayne@69: * locale. jpayne@69: * @param locale The locale for which the default numbering system should be opened. jpayne@69: * @param status A pointer to a UErrorCode to receive any errors. For example, this jpayne@69: * may be U_UNSUPPORTED_ERROR for a locale such as "en@numbers=xyz" that jpayne@69: * specifies a numbering system unknown to ICU. jpayne@69: * @return A UNumberingSystem for the specified locale, or NULL if an error jpayne@69: * occurred. jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_STABLE UNumberingSystem * U_EXPORT2 jpayne@69: unumsys_open(const char *locale, UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Opens a UNumberingSystem object using the name of one of the predefined numbering jpayne@69: * systems specified by CLDR and known to ICU, such as "latn", "arabext", or "hanidec"; jpayne@69: * the full list is returned by unumsys_openAvailableNames. Note that some of the names jpayne@69: * listed at http://unicode.org/repos/cldr/tags/latest/common/bcp47/number.xml - e.g. jpayne@69: * default, native, traditional, finance - do not identify specific numbering systems, jpayne@69: * but rather key values that may only be used as part of a locale, which in turn jpayne@69: * defines how they are mapped to a specific numbering system such as "latn" or "hant". jpayne@69: * jpayne@69: * @param name The name of the numbering system for which a UNumberingSystem object jpayne@69: * should be opened. jpayne@69: * @param status A pointer to a UErrorCode to receive any errors. For example, this jpayne@69: * may be U_UNSUPPORTED_ERROR for a numbering system such as "xyz" that jpayne@69: * is unknown to ICU. jpayne@69: * @return A UNumberingSystem for the specified name, or NULL if an error jpayne@69: * occurred. jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_STABLE UNumberingSystem * U_EXPORT2 jpayne@69: unumsys_openByName(const char *name, UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Close a UNumberingSystem object. Once closed it may no longer be used. jpayne@69: * @param unumsys The UNumberingSystem object to close. jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: unumsys_close(UNumberingSystem *unumsys); jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * \class LocalUNumberingSystemPointer jpayne@69: * "Smart pointer" class, closes a UNumberingSystem via unumsys_close(). jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberingSystemPointer, UNumberingSystem, unumsys_close); jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * Returns an enumeration over the names of all of the predefined numbering systems known jpayne@69: * to ICU. jpayne@69: * The numbering system names will be in alphabetical (invariant) order. jpayne@69: * @param status A pointer to a UErrorCode to receive any errors. jpayne@69: * @return A pointer to a UEnumeration that must be closed with uenum_close(), jpayne@69: * or NULL if an error occurred. jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_STABLE UEnumeration * U_EXPORT2 jpayne@69: unumsys_openAvailableNames(UErrorCode *status); jpayne@69: jpayne@69: /** jpayne@69: * Returns the name of the specified UNumberingSystem object (if it is one of the jpayne@69: * predefined names known to ICU). jpayne@69: * @param unumsys The UNumberingSystem whose name is desired. jpayne@69: * @return A pointer to the name of the specified UNumberingSystem object, or jpayne@69: * NULL if the name is not one of the ICU predefined names. The pointer jpayne@69: * is only valid for the lifetime of the UNumberingSystem object. jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_STABLE const char * U_EXPORT2 jpayne@69: unumsys_getName(const UNumberingSystem *unumsys); jpayne@69: jpayne@69: /** jpayne@69: * Returns whether the given UNumberingSystem object is for an algorithmic (not purely jpayne@69: * positional) system. jpayne@69: * @param unumsys The UNumberingSystem whose algorithmic status is desired. jpayne@69: * @return TRUE if the specified UNumberingSystem object is for an algorithmic jpayne@69: * system. jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_STABLE UBool U_EXPORT2 jpayne@69: unumsys_isAlgorithmic(const UNumberingSystem *unumsys); jpayne@69: jpayne@69: /** jpayne@69: * Returns the radix of the specified UNumberingSystem object. Simple positional jpayne@69: * numbering systems typically have radix 10, but might have a radix of e.g. 16 for jpayne@69: * hexadecimal. The radix is less well-defined for non-positional algorithmic systems. jpayne@69: * @param unumsys The UNumberingSystem whose radix is desired. jpayne@69: * @return The radix of the specified UNumberingSystem object. jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: unumsys_getRadix(const UNumberingSystem *unumsys); jpayne@69: jpayne@69: /** jpayne@69: * Get the description string of the specified UNumberingSystem object. For simple jpayne@69: * positional systems this is the ordered string of digits (with length matching jpayne@69: * the radix), e.g. "\u3007\u4E00\u4E8C\u4E09\u56DB\u4E94\u516D\u4E03\u516B\u4E5D" jpayne@69: * for "hanidec"; it would be "0123456789ABCDEF" for hexadecimal. For jpayne@69: * algorithmic systems this is the name of the RBNF ruleset used for formatting, jpayne@69: * e.g. "zh/SpelloutRules/%spellout-cardinal" for "hans" or "%greek-upper" for jpayne@69: * "grek". jpayne@69: * @param unumsys The UNumberingSystem whose description string is desired. jpayne@69: * @param result A pointer to a buffer to receive the description string. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param status A pointer to a UErrorCode to receive any errors. jpayne@69: * @return The total buffer size needed; if greater than resultLength, the jpayne@69: * output was truncated. jpayne@69: * @stable ICU 52 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: unumsys_getDescription(const UNumberingSystem *unumsys, UChar *result, jpayne@69: int32_t resultLength, UErrorCode *status); jpayne@69: jpayne@69: #endif /* #if !UCONFIG_NO_FORMATTING */ jpayne@69: jpayne@69: #endif