159d709d503bab6e2b61931737e662dd293b40578ccornelius/* 259d709d503bab6e2b61931737e662dd293b40578ccornelius***************************************************************************************** 3f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius* Copyright (C) 2013-2014, International Business Machines 459d709d503bab6e2b61931737e662dd293b40578ccornelius* Corporation and others. All Rights Reserved. 559d709d503bab6e2b61931737e662dd293b40578ccornelius***************************************************************************************** 659d709d503bab6e2b61931737e662dd293b40578ccornelius*/ 759d709d503bab6e2b61931737e662dd293b40578ccornelius 859d709d503bab6e2b61931737e662dd293b40578ccornelius#ifndef UNUMSYS_H 959d709d503bab6e2b61931737e662dd293b40578ccornelius#define UNUMSYS_H 1059d709d503bab6e2b61931737e662dd293b40578ccornelius 1159d709d503bab6e2b61931737e662dd293b40578ccornelius#include "unicode/utypes.h" 1259d709d503bab6e2b61931737e662dd293b40578ccornelius 1359d709d503bab6e2b61931737e662dd293b40578ccornelius#if !UCONFIG_NO_FORMATTING 1459d709d503bab6e2b61931737e662dd293b40578ccornelius 1559d709d503bab6e2b61931737e662dd293b40578ccornelius#include "unicode/uenum.h" 1659d709d503bab6e2b61931737e662dd293b40578ccornelius#include "unicode/localpointer.h" 1759d709d503bab6e2b61931737e662dd293b40578ccornelius 1859d709d503bab6e2b61931737e662dd293b40578ccornelius/** 1959d709d503bab6e2b61931737e662dd293b40578ccornelius * \file 2059d709d503bab6e2b61931737e662dd293b40578ccornelius * \brief C API: UNumberingSystem, information about numbering systems 2159d709d503bab6e2b61931737e662dd293b40578ccornelius * 2259d709d503bab6e2b61931737e662dd293b40578ccornelius * Defines numbering systems. A numbering system describes the scheme by which 2359d709d503bab6e2b61931737e662dd293b40578ccornelius * numbers are to be presented to the end user. In its simplest form, a numbering 2459d709d503bab6e2b61931737e662dd293b40578ccornelius * system describes the set of digit characters that are to be used to display 2559d709d503bab6e2b61931737e662dd293b40578ccornelius * numbers, such as Western digits, Thai digits, Arabic-Indic digits, etc., in a 2659d709d503bab6e2b61931737e662dd293b40578ccornelius * positional numbering system with a specified radix (typically 10). 2759d709d503bab6e2b61931737e662dd293b40578ccornelius * More complicated numbering systems are algorithmic in nature, and require use 2859d709d503bab6e2b61931737e662dd293b40578ccornelius * of an RBNF formatter (rule based number formatter), in order to calculate 2959d709d503bab6e2b61931737e662dd293b40578ccornelius * the characters to be displayed for a given number. Examples of algorithmic 3059d709d503bab6e2b61931737e662dd293b40578ccornelius * numbering systems include Roman numerals, Chinese numerals, and Hebrew numerals. 3159d709d503bab6e2b61931737e662dd293b40578ccornelius * Formatting rules for many commonly used numbering systems are included in 3259d709d503bab6e2b61931737e662dd293b40578ccornelius * the ICU package, based on the numbering system rules defined in CLDR. 3359d709d503bab6e2b61931737e662dd293b40578ccornelius * Alternate numbering systems can be specified to a locale by using the 3459d709d503bab6e2b61931737e662dd293b40578ccornelius * numbers locale keyword. 3559d709d503bab6e2b61931737e662dd293b40578ccornelius */ 3659d709d503bab6e2b61931737e662dd293b40578ccornelius 3759d709d503bab6e2b61931737e662dd293b40578ccornelius/** 3859d709d503bab6e2b61931737e662dd293b40578ccornelius * Opaque UNumberingSystem object for use in C programs. 39f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius * @stable ICU 52 4059d709d503bab6e2b61931737e662dd293b40578ccornelius */ 4159d709d503bab6e2b61931737e662dd293b40578ccorneliusstruct UNumberingSystem; 42f9878a236aa0d9662d8e40cafdaf2e04cd615835ccorneliustypedef struct UNumberingSystem UNumberingSystem; /**< C typedef for struct UNumberingSystem. @stable ICU 52 */ 4359d709d503bab6e2b61931737e662dd293b40578ccornelius 4459d709d503bab6e2b61931737e662dd293b40578ccornelius/** 4559d709d503bab6e2b61931737e662dd293b40578ccornelius * Opens a UNumberingSystem object using the default numbering system for the specified 4659d709d503bab6e2b61931737e662dd293b40578ccornelius * locale. 4759d709d503bab6e2b61931737e662dd293b40578ccornelius * @param locale The locale for which the default numbering system should be opened. 4859d709d503bab6e2b61931737e662dd293b40578ccornelius * @param status A pointer to a UErrorCode to receive any errors. For example, this 4959d709d503bab6e2b61931737e662dd293b40578ccornelius * may be U_UNSUPPORTED_ERROR for a locale such as "en@numbers=xyz" that 5059d709d503bab6e2b61931737e662dd293b40578ccornelius * specifies a numbering system unknown to ICU. 5159d709d503bab6e2b61931737e662dd293b40578ccornelius * @return A UNumberingSystem for the specified locale, or NULL if an error 5259d709d503bab6e2b61931737e662dd293b40578ccornelius * occurred. 53f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius * @stable ICU 52 5459d709d503bab6e2b61931737e662dd293b40578ccornelius */ 55f9878a236aa0d9662d8e40cafdaf2e04cd615835ccorneliusU_STABLE UNumberingSystem * U_EXPORT2 5659d709d503bab6e2b61931737e662dd293b40578ccorneliusunumsys_open(const char *locale, UErrorCode *status); 5759d709d503bab6e2b61931737e662dd293b40578ccornelius 5859d709d503bab6e2b61931737e662dd293b40578ccornelius/** 5959d709d503bab6e2b61931737e662dd293b40578ccornelius * Opens a UNumberingSystem object using the name of one of the predefined numbering 6059d709d503bab6e2b61931737e662dd293b40578ccornelius * systems specified by CLDR and known to ICU, such as "latn", "arabext", or "hanidec"; 6159d709d503bab6e2b61931737e662dd293b40578ccornelius * the full list is returned by unumsys_openAvailableNames. Note that some of the names 6259d709d503bab6e2b61931737e662dd293b40578ccornelius * listed at http://unicode.org/repos/cldr/tags/latest/common/bcp47/number.xml - e.g. 6359d709d503bab6e2b61931737e662dd293b40578ccornelius * default, native, traditional, finance - do not identify specific numbering systems, 6459d709d503bab6e2b61931737e662dd293b40578ccornelius * but rather key values that may only be used as part of a locale, which in turn 6559d709d503bab6e2b61931737e662dd293b40578ccornelius * defines how they are mapped to a specific numbering system such as "latn" or "hant". 6659d709d503bab6e2b61931737e662dd293b40578ccornelius * 6759d709d503bab6e2b61931737e662dd293b40578ccornelius * @param name The name of the numbering system for which a UNumberingSystem object 6859d709d503bab6e2b61931737e662dd293b40578ccornelius * should be opened. 6959d709d503bab6e2b61931737e662dd293b40578ccornelius * @param status A pointer to a UErrorCode to receive any errors. For example, this 7059d709d503bab6e2b61931737e662dd293b40578ccornelius * may be U_UNSUPPORTED_ERROR for a numbering system such as "xyz" that 7159d709d503bab6e2b61931737e662dd293b40578ccornelius * is unknown to ICU. 7259d709d503bab6e2b61931737e662dd293b40578ccornelius * @return A UNumberingSystem for the specified name, or NULL if an error 7359d709d503bab6e2b61931737e662dd293b40578ccornelius * occurred. 74f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius * @stable ICU 52 7559d709d503bab6e2b61931737e662dd293b40578ccornelius */ 76f9878a236aa0d9662d8e40cafdaf2e04cd615835ccorneliusU_STABLE UNumberingSystem * U_EXPORT2 7759d709d503bab6e2b61931737e662dd293b40578ccorneliusunumsys_openByName(const char *name, UErrorCode *status); 7859d709d503bab6e2b61931737e662dd293b40578ccornelius 7959d709d503bab6e2b61931737e662dd293b40578ccornelius/** 8059d709d503bab6e2b61931737e662dd293b40578ccornelius * Close a UNumberingSystem object. Once closed it may no longer be used. 8159d709d503bab6e2b61931737e662dd293b40578ccornelius * @param unumsys The UNumberingSystem object to close. 82f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius * @stable ICU 52 8359d709d503bab6e2b61931737e662dd293b40578ccornelius */ 84f9878a236aa0d9662d8e40cafdaf2e04cd615835ccorneliusU_STABLE void U_EXPORT2 8559d709d503bab6e2b61931737e662dd293b40578ccorneliusunumsys_close(UNumberingSystem *unumsys); 8659d709d503bab6e2b61931737e662dd293b40578ccornelius 8759d709d503bab6e2b61931737e662dd293b40578ccornelius#if U_SHOW_CPLUSPLUS_API 8859d709d503bab6e2b61931737e662dd293b40578ccorneliusU_NAMESPACE_BEGIN 8959d709d503bab6e2b61931737e662dd293b40578ccornelius 9059d709d503bab6e2b61931737e662dd293b40578ccornelius/** 9159d709d503bab6e2b61931737e662dd293b40578ccornelius * \class LocalUNumberingSystemPointer 9259d709d503bab6e2b61931737e662dd293b40578ccornelius * "Smart pointer" class, closes a UNumberingSystem via unumsys_close(). 9359d709d503bab6e2b61931737e662dd293b40578ccornelius * For most methods see the LocalPointerBase base class. 9459d709d503bab6e2b61931737e662dd293b40578ccornelius * @see LocalPointerBase 9559d709d503bab6e2b61931737e662dd293b40578ccornelius * @see LocalPointer 96f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius * @stable ICU 52 9759d709d503bab6e2b61931737e662dd293b40578ccornelius */ 9859d709d503bab6e2b61931737e662dd293b40578ccorneliusU_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberingSystemPointer, UNumberingSystem, unumsys_close); 9959d709d503bab6e2b61931737e662dd293b40578ccornelius 10059d709d503bab6e2b61931737e662dd293b40578ccorneliusU_NAMESPACE_END 10159d709d503bab6e2b61931737e662dd293b40578ccornelius#endif 10259d709d503bab6e2b61931737e662dd293b40578ccornelius 10359d709d503bab6e2b61931737e662dd293b40578ccornelius/** 10459d709d503bab6e2b61931737e662dd293b40578ccornelius * Returns an enumeration over the names of all of the predefined numbering systems known 10559d709d503bab6e2b61931737e662dd293b40578ccornelius * to ICU. 10659d709d503bab6e2b61931737e662dd293b40578ccornelius * @param status A pointer to a UErrorCode to receive any errors. 10759d709d503bab6e2b61931737e662dd293b40578ccornelius * @return A pointer to a UEnumeration that must be closed with uenum_close(), 10859d709d503bab6e2b61931737e662dd293b40578ccornelius * or NULL if an error occurred. 109f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius * @stable ICU 52 11059d709d503bab6e2b61931737e662dd293b40578ccornelius */ 111f9878a236aa0d9662d8e40cafdaf2e04cd615835ccorneliusU_STABLE UEnumeration * U_EXPORT2 11259d709d503bab6e2b61931737e662dd293b40578ccorneliusunumsys_openAvailableNames(UErrorCode *status); 11359d709d503bab6e2b61931737e662dd293b40578ccornelius 11459d709d503bab6e2b61931737e662dd293b40578ccornelius/** 11559d709d503bab6e2b61931737e662dd293b40578ccornelius * Returns the name of the specified UNumberingSystem object (if it is one of the 11659d709d503bab6e2b61931737e662dd293b40578ccornelius * predefined names known to ICU). 11759d709d503bab6e2b61931737e662dd293b40578ccornelius * @param unumsys The UNumberingSystem whose name is desired. 11859d709d503bab6e2b61931737e662dd293b40578ccornelius * @return A pointer to the name of the specified UNumberingSystem object, or 11959d709d503bab6e2b61931737e662dd293b40578ccornelius * NULL if the name is not one of the ICU predefined names. The pointer 12059d709d503bab6e2b61931737e662dd293b40578ccornelius * is only valid for the lifetime of the UNumberingSystem object. 121f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius * @stable ICU 52 12259d709d503bab6e2b61931737e662dd293b40578ccornelius */ 123f9878a236aa0d9662d8e40cafdaf2e04cd615835ccorneliusU_STABLE const char * U_EXPORT2 12459d709d503bab6e2b61931737e662dd293b40578ccorneliusunumsys_getName(const UNumberingSystem *unumsys); 12559d709d503bab6e2b61931737e662dd293b40578ccornelius 12659d709d503bab6e2b61931737e662dd293b40578ccornelius/** 12759d709d503bab6e2b61931737e662dd293b40578ccornelius * Returns whether the given UNumberingSystem object is for an algorithmic (not purely 12859d709d503bab6e2b61931737e662dd293b40578ccornelius * positional) system. 12959d709d503bab6e2b61931737e662dd293b40578ccornelius * @param unumsys The UNumberingSystem whose algorithmic status is desired. 13059d709d503bab6e2b61931737e662dd293b40578ccornelius * @return TRUE if the specified UNumberingSystem object is for an algorithmic 13159d709d503bab6e2b61931737e662dd293b40578ccornelius * system. 132f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius * @stable ICU 52 13359d709d503bab6e2b61931737e662dd293b40578ccornelius */ 134f9878a236aa0d9662d8e40cafdaf2e04cd615835ccorneliusU_STABLE UBool U_EXPORT2 13559d709d503bab6e2b61931737e662dd293b40578ccorneliusunumsys_isAlgorithmic(const UNumberingSystem *unumsys); 13659d709d503bab6e2b61931737e662dd293b40578ccornelius 13759d709d503bab6e2b61931737e662dd293b40578ccornelius/** 13859d709d503bab6e2b61931737e662dd293b40578ccornelius * Returns the radix of the specified UNumberingSystem object. Simple positional 13959d709d503bab6e2b61931737e662dd293b40578ccornelius * numbering systems typically have radix 10, but might have a radix of e.g. 16 for 14059d709d503bab6e2b61931737e662dd293b40578ccornelius * hexadecimal. The radix is less well-defined for non-positional algorithmic systems. 14159d709d503bab6e2b61931737e662dd293b40578ccornelius * @param unumsys The UNumberingSystem whose radix is desired. 14259d709d503bab6e2b61931737e662dd293b40578ccornelius * @return The radix of the specified UNumberingSystem object. 143f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius * @stable ICU 52 14459d709d503bab6e2b61931737e662dd293b40578ccornelius */ 145f9878a236aa0d9662d8e40cafdaf2e04cd615835ccorneliusU_STABLE int32_t U_EXPORT2 14659d709d503bab6e2b61931737e662dd293b40578ccorneliusunumsys_getRadix(const UNumberingSystem *unumsys); 14759d709d503bab6e2b61931737e662dd293b40578ccornelius 14859d709d503bab6e2b61931737e662dd293b40578ccornelius/** 14959d709d503bab6e2b61931737e662dd293b40578ccornelius * Get the description string of the specified UNumberingSystem object. For simple 15059d709d503bab6e2b61931737e662dd293b40578ccornelius * positional systems this is the ordered string of digits (with length matching 15159d709d503bab6e2b61931737e662dd293b40578ccornelius * the radix), e.g. "\u3007\u4E00\u4E8C\u4E09\u56DB\u4E94\u516D\u4E03\u516B\u4E5D" 15259d709d503bab6e2b61931737e662dd293b40578ccornelius * for "hanidec"; it would be "0123456789ABCDEF" for hexadecimal. For 15359d709d503bab6e2b61931737e662dd293b40578ccornelius * algorithmic systems this is the name of the RBNF ruleset used for formatting, 15459d709d503bab6e2b61931737e662dd293b40578ccornelius * e.g. "zh/SpelloutRules/%spellout-cardinal" for "hans" or "%greek-upper" for 15559d709d503bab6e2b61931737e662dd293b40578ccornelius * "grek". 15659d709d503bab6e2b61931737e662dd293b40578ccornelius * @param unumsys The UNumberingSystem whose description string is desired. 15759d709d503bab6e2b61931737e662dd293b40578ccornelius * @param result A pointer to a buffer to receive the description string. 15859d709d503bab6e2b61931737e662dd293b40578ccornelius * @param resultLength The maximum size of result. 15959d709d503bab6e2b61931737e662dd293b40578ccornelius * @param status A pointer to a UErrorCode to receive any errors. 16059d709d503bab6e2b61931737e662dd293b40578ccornelius * @return The total buffer size needed; if greater than resultLength, the 16159d709d503bab6e2b61931737e662dd293b40578ccornelius * output was truncated. 162f9878a236aa0d9662d8e40cafdaf2e04cd615835ccornelius * @stable ICU 52 16359d709d503bab6e2b61931737e662dd293b40578ccornelius */ 164f9878a236aa0d9662d8e40cafdaf2e04cd615835ccorneliusU_STABLE int32_t U_EXPORT2 16559d709d503bab6e2b61931737e662dd293b40578ccorneliusunumsys_getDescription(const UNumberingSystem *unumsys, UChar *result, 16659d709d503bab6e2b61931737e662dd293b40578ccornelius int32_t resultLength, UErrorCode *status); 16759d709d503bab6e2b61931737e662dd293b40578ccornelius 16859d709d503bab6e2b61931737e662dd293b40578ccornelius#endif /* #if !UCONFIG_NO_FORMATTING */ 16959d709d503bab6e2b61931737e662dd293b40578ccornelius 17059d709d503bab6e2b61931737e662dd293b40578ccornelius#endif 171