summaryrefslogtreecommitdiffstats
path: root/intl/icu/source/i18n/unicode/unumsys.h
blob: 46289c0f9aba0daa4d0f0f9929a394745cc113f2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
// Copyright (C) 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*****************************************************************************************
* Copyright (C) 2013-2014, International Business Machines
* Corporation and others. All Rights Reserved.
*****************************************************************************************
*/

#ifndef UNUMSYS_H
#define UNUMSYS_H

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING

#include "unicode/uenum.h"
#include "unicode/localpointer.h"

/**
 * \file
 * \brief C API: UNumberingSystem, information about numbering systems
 *
 * Defines numbering systems. A numbering system describes the scheme by which 
 * numbers are to be presented to the end user. In its simplest form, a numbering
 * system describes the set of digit characters that are to be used to display
 * numbers, such as Western digits, Thai digits, Arabic-Indic digits, etc., in a
 * positional numbering system with a specified radix (typically 10).
 * More complicated numbering systems are algorithmic in nature, and require use
 * of an RBNF formatter (rule based number formatter), in order to calculate
 * the characters to be displayed for a given number. Examples of algorithmic
 * numbering systems include Roman numerals, Chinese numerals, and Hebrew numerals.
 * Formatting rules for many commonly used numbering systems are included in
 * the ICU package, based on the numbering system rules defined in CLDR.
 * Alternate numbering systems can be specified to a locale by using the
 * numbers locale keyword.
 */

/**
 * Opaque UNumberingSystem object for use in C programs.
 * @stable ICU 52
 */
struct UNumberingSystem;
typedef struct UNumberingSystem UNumberingSystem;  /**< C typedef for struct UNumberingSystem. @stable ICU 52 */

/**
 * Opens a UNumberingSystem object using the default numbering system for the specified
 * locale.
 * @param locale    The locale for which the default numbering system should be opened.
 * @param status    A pointer to a UErrorCode to receive any errors. For example, this
 *                  may be U_UNSUPPORTED_ERROR for a locale such as "en@numbers=xyz" that
 *                  specifies a numbering system unknown to ICU.
 * @return          A UNumberingSystem for the specified locale, or NULL if an error
 *                  occurred.
 * @stable ICU 52
 */
U_STABLE UNumberingSystem * U_EXPORT2
unumsys_open(const char *locale, UErrorCode *status);

/**
 * Opens a UNumberingSystem object using the name of one of the predefined numbering
 * systems specified by CLDR and known to ICU, such as "latn", "arabext", or "hanidec";
 * the full list is returned by unumsys_openAvailableNames. Note that some of the names
 * listed at http://unicode.org/repos/cldr/tags/latest/common/bcp47/number.xml - e.g.
 * default, native, traditional, finance - do not identify specific numbering systems,
 * but rather key values that may only be used as part of a locale, which in turn
 * defines how they are mapped to a specific numbering system such as "latn" or "hant".
 *
 * @param name      The name of the numbering system for which a UNumberingSystem object
 *                  should be opened.
 * @param status    A pointer to a UErrorCode to receive any errors. For example, this
 *                  may be U_UNSUPPORTED_ERROR for a numbering system such as "xyz" that
 *                  is unknown to ICU.
 * @return          A UNumberingSystem for the specified name, or NULL if an error
 *                  occurred.
 * @stable ICU 52
 */
U_STABLE UNumberingSystem * U_EXPORT2
unumsys_openByName(const char *name, UErrorCode *status);

/**
 * Close a UNumberingSystem object. Once closed it may no longer be used.
 * @param unumsys   The UNumberingSystem object to close.
 * @stable ICU 52
 */
U_STABLE void U_EXPORT2
unumsys_close(UNumberingSystem *unumsys);

#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN

/**
 * \class LocalUNumberingSystemPointer
 * "Smart pointer" class, closes a UNumberingSystem via unumsys_close().
 * For most methods see the LocalPointerBase base class.
 * @see LocalPointerBase
 * @see LocalPointer
 * @stable ICU 52
 */
U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberingSystemPointer, UNumberingSystem, unumsys_close);

U_NAMESPACE_END
#endif

/**
 * Returns an enumeration over the names of all of the predefined numbering systems known
 * to ICU.
 * @param status    A pointer to a UErrorCode to receive any errors.
 * @return          A pointer to a UEnumeration that must be closed with uenum_close(),
 *                  or NULL if an error occurred.
 * @stable ICU 52
 */
U_STABLE UEnumeration * U_EXPORT2
unumsys_openAvailableNames(UErrorCode *status);

/**
 * Returns the name of the specified UNumberingSystem object (if it is one of the
 * predefined names known to ICU).
 * @param unumsys   The UNumberingSystem whose name is desired.
 * @return          A pointer to the name of the specified UNumberingSystem object, or
 *                  NULL if the name is not one of the ICU predefined names. The pointer
 *                  is only valid for the lifetime of the UNumberingSystem object.
 * @stable ICU 52
 */
U_STABLE const char * U_EXPORT2
unumsys_getName(const UNumberingSystem *unumsys);

/**
 * Returns whether the given UNumberingSystem object is for an algorithmic (not purely
 * positional) system.
 * @param unumsys   The UNumberingSystem whose algorithmic status is desired.
 * @return          TRUE if the specified UNumberingSystem object is for an algorithmic
 *                  system.
 * @stable ICU 52
 */
U_STABLE UBool U_EXPORT2
unumsys_isAlgorithmic(const UNumberingSystem *unumsys);

/**
 * Returns the radix of the specified UNumberingSystem object. Simple positional
 * numbering systems typically have radix 10, but might have a radix of e.g. 16 for
 * hexadecimal. The radix is less well-defined for non-positional algorithmic systems.
 * @param unumsys   The UNumberingSystem whose radix is desired.
 * @return          The radix of the specified UNumberingSystem object.
 * @stable ICU 52
 */
U_STABLE int32_t U_EXPORT2
unumsys_getRadix(const UNumberingSystem *unumsys);

/**
 * Get the description string of the specified UNumberingSystem object. For simple
 * positional systems this is the ordered string of digits (with length matching
 * the radix), e.g. "\u3007\u4E00\u4E8C\u4E09\u56DB\u4E94\u516D\u4E03\u516B\u4E5D"
 * for "hanidec"; it would be "0123456789ABCDEF" for hexadecimal. For
 * algorithmic systems this is the name of the RBNF ruleset used for formatting,
 * e.g. "zh/SpelloutRules/%spellout-cardinal" for "hans" or "%greek-upper" for
 * "grek".
 * @param unumsys   The UNumberingSystem whose description string is desired.
 * @param result    A pointer to a buffer to receive the description string.
 * @param resultLength  The maximum size of result.
 * @param status    A pointer to a UErrorCode to receive any errors.
 * @return          The total buffer size needed; if greater than resultLength, the
 *                  output was truncated.
 * @stable ICU 52
 */
U_STABLE int32_t U_EXPORT2
unumsys_getDescription(const UNumberingSystem *unumsys, UChar *result,
                       int32_t resultLength, UErrorCode *status);

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif