1 /* 2 ***************************************************************************************** 3 * Copyright (C) 2013-2014, International Business Machines 4 * Corporation and others. All Rights Reserved. 5 ***************************************************************************************** 6 */ 7 8 #ifndef UNUMSYS_H 9 #define UNUMSYS_H 10 11 #include "unicode/utypes.h" 12 13 #if !UCONFIG_NO_FORMATTING 14 15 #include "unicode/uenum.h" 16 #include "unicode/localpointer.h" 17 18 /** 19 * \file 20 * \brief C API: UNumberingSystem, information about numbering systems 21 * 22 * Defines numbering systems. A numbering system describes the scheme by which 23 * numbers are to be presented to the end user. In its simplest form, a numbering 24 * system describes the set of digit characters that are to be used to display 25 * numbers, such as Western digits, Thai digits, Arabic-Indic digits, etc., in a 26 * positional numbering system with a specified radix (typically 10). 27 * More complicated numbering systems are algorithmic in nature, and require use 28 * of an RBNF formatter (rule based number formatter), in order to calculate 29 * the characters to be displayed for a given number. Examples of algorithmic 30 * numbering systems include Roman numerals, Chinese numerals, and Hebrew numerals. 31 * Formatting rules for many commonly used numbering systems are included in 32 * the ICU package, based on the numbering system rules defined in CLDR. 33 * Alternate numbering systems can be specified to a locale by using the 34 * numbers locale keyword. 35 */ 36 37 /** 38 * Opaque UNumberingSystem object for use in C programs. 39 * @stable ICU 52 40 */ 41 struct UNumberingSystem; 42 typedef struct UNumberingSystem UNumberingSystem; /**< C typedef for struct UNumberingSystem. @stable ICU 52 */ 43 44 /** 45 * Opens a UNumberingSystem object using the default numbering system for the specified 46 * locale. 47 * @param locale The locale for which the default numbering system should be opened. 48 * @param status A pointer to a UErrorCode to receive any errors. For example, this 49 * may be U_UNSUPPORTED_ERROR for a locale such as "en@numbers=xyz" that 50 * specifies a numbering system unknown to ICU. 51 * @return A UNumberingSystem for the specified locale, or NULL if an error 52 * occurred. 53 * @stable ICU 52 54 */ 55 U_STABLE UNumberingSystem * U_EXPORT2 56 unumsys_open(const char *locale, UErrorCode *status); 57 58 /** 59 * Opens a UNumberingSystem object using the name of one of the predefined numbering 60 * systems specified by CLDR and known to ICU, such as "latn", "arabext", or "hanidec"; 61 * the full list is returned by unumsys_openAvailableNames. Note that some of the names 62 * listed at http://unicode.org/repos/cldr/tags/latest/common/bcp47/number.xml - e.g. 63 * default, native, traditional, finance - do not identify specific numbering systems, 64 * but rather key values that may only be used as part of a locale, which in turn 65 * defines how they are mapped to a specific numbering system such as "latn" or "hant". 66 * 67 * @param name The name of the numbering system for which a UNumberingSystem object 68 * should be opened. 69 * @param status A pointer to a UErrorCode to receive any errors. For example, this 70 * may be U_UNSUPPORTED_ERROR for a numbering system such as "xyz" that 71 * is unknown to ICU. 72 * @return A UNumberingSystem for the specified name, or NULL if an error 73 * occurred. 74 * @stable ICU 52 75 */ 76 U_STABLE UNumberingSystem * U_EXPORT2 77 unumsys_openByName(const char *name, UErrorCode *status); 78 79 /** 80 * Close a UNumberingSystem object. Once closed it may no longer be used. 81 * @param unumsys The UNumberingSystem object to close. 82 * @stable ICU 52 83 */ 84 U_STABLE void U_EXPORT2 85 unumsys_close(UNumberingSystem *unumsys); 86 87 #if U_SHOW_CPLUSPLUS_API 88 U_NAMESPACE_BEGIN 89 90 /** 91 * \class LocalUNumberingSystemPointer 92 * "Smart pointer" class, closes a UNumberingSystem via unumsys_close(). 93 * For most methods see the LocalPointerBase base class. 94 * @see LocalPointerBase 95 * @see LocalPointer 96 * @stable ICU 52 97 */ 98 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberingSystemPointer, UNumberingSystem, unumsys_close); 99 100 U_NAMESPACE_END 101 #endif 102 103 /** 104 * Returns an enumeration over the names of all of the predefined numbering systems known 105 * to ICU. 106 * @param status A pointer to a UErrorCode to receive any errors. 107 * @return A pointer to a UEnumeration that must be closed with uenum_close(), 108 * or NULL if an error occurred. 109 * @stable ICU 52 110 */ 111 U_STABLE UEnumeration * U_EXPORT2 112 unumsys_openAvailableNames(UErrorCode *status); 113 114 /** 115 * Returns the name of the specified UNumberingSystem object (if it is one of the 116 * predefined names known to ICU). 117 * @param unumsys The UNumberingSystem whose name is desired. 118 * @return A pointer to the name of the specified UNumberingSystem object, or 119 * NULL if the name is not one of the ICU predefined names. The pointer 120 * is only valid for the lifetime of the UNumberingSystem object. 121 * @stable ICU 52 122 */ 123 U_STABLE const char * U_EXPORT2 124 unumsys_getName(const UNumberingSystem *unumsys); 125 126 /** 127 * Returns whether the given UNumberingSystem object is for an algorithmic (not purely 128 * positional) system. 129 * @param unumsys The UNumberingSystem whose algorithmic status is desired. 130 * @return TRUE if the specified UNumberingSystem object is for an algorithmic 131 * system. 132 * @stable ICU 52 133 */ 134 U_STABLE UBool U_EXPORT2 135 unumsys_isAlgorithmic(const UNumberingSystem *unumsys); 136 137 /** 138 * Returns the radix of the specified UNumberingSystem object. Simple positional 139 * numbering systems typically have radix 10, but might have a radix of e.g. 16 for 140 * hexadecimal. The radix is less well-defined for non-positional algorithmic systems. 141 * @param unumsys The UNumberingSystem whose radix is desired. 142 * @return The radix of the specified UNumberingSystem object. 143 * @stable ICU 52 144 */ 145 U_STABLE int32_t U_EXPORT2 146 unumsys_getRadix(const UNumberingSystem *unumsys); 147 148 /** 149 * Get the description string of the specified UNumberingSystem object. For simple 150 * positional systems this is the ordered string of digits (with length matching 151 * the radix), e.g. "\u3007\u4E00\u4E8C\u4E09\u56DB\u4E94\u516D\u4E03\u516B\u4E5D" 152 * for "hanidec"; it would be "0123456789ABCDEF" for hexadecimal. For 153 * algorithmic systems this is the name of the RBNF ruleset used for formatting, 154 * e.g. "zh/SpelloutRules/%spellout-cardinal" for "hans" or "%greek-upper" for 155 * "grek". 156 * @param unumsys The UNumberingSystem whose description string is desired. 157 * @param result A pointer to a buffer to receive the description string. 158 * @param resultLength The maximum size of result. 159 * @param status A pointer to a UErrorCode to receive any errors. 160 * @return The total buffer size needed; if greater than resultLength, the 161 * output was truncated. 162 * @stable ICU 52 163 */ 164 U_STABLE int32_t U_EXPORT2 165 unumsys_getDescription(const UNumberingSystem *unumsys, UChar *result, 166 int32_t resultLength, UErrorCode *status); 167 168 #endif /* #if !UCONFIG_NO_FORMATTING */ 169 170 #endif 171