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