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 */
41struct UNumberingSystem;
42typedef 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 */
55U_STABLE UNumberingSystem * U_EXPORT2
56unumsys_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 */
76U_STABLE UNumberingSystem * U_EXPORT2
77unumsys_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 */
84U_STABLE void U_EXPORT2
85unumsys_close(UNumberingSystem *unumsys);
86
87#if U_SHOW_CPLUSPLUS_API
88U_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 */
98U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberingSystemPointer, UNumberingSystem, unumsys_close);
99
100U_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 */
111U_STABLE UEnumeration * U_EXPORT2
112unumsys_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 */
123U_STABLE const char * U_EXPORT2
124unumsys_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 */
134U_STABLE UBool U_EXPORT2
135unumsys_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 */
145U_STABLE int32_t U_EXPORT2
146unumsys_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 */
164U_STABLE int32_t U_EXPORT2
165unumsys_getDescription(const UNumberingSystem *unumsys, UChar *result,
166 int32_t resultLength, UErrorCode *status);
167
168#endif /* #if !UCONFIG_NO_FORMATTING */
169
170#endif
171