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