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