1// © 2017 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3
4#ifndef __UNUMBEROPTIONS_H__
5#define __UNUMBEROPTIONS_H__
6
7#include "unicode/utypes.h"
8
9#if !UCONFIG_NO_FORMATTING
10
11/**
12 * \file
13 * \brief C API: Header-only input options for various number formatting APIs.
14 *
15 * You do not normally need to include this header file directly, because it is included in all
16 * files that use these enums.
17 */
18
19
20/** The possible number format rounding modes.
21 *
22 * <p>
23 * For more detail on rounding modes, see:
24 * https://unicode-org.github.io/icu/userguide/format_parse/numbers/rounding-modes
25 *
26 * @stable ICU 2.0
27 */
28typedef enum UNumberFormatRoundingMode {
29 UNUM_ROUND_CEILING,
30 UNUM_ROUND_FLOOR,
31 UNUM_ROUND_DOWN,
32 UNUM_ROUND_UP,
33 /**
34 * Half-even rounding
35 * @stable, ICU 3.8
36 */
37 UNUM_ROUND_HALFEVEN,
38#ifndef U_HIDE_DEPRECATED_API
39 /**
40 * Half-even rounding, misspelled name
41 * @deprecated, ICU 3.8
42 */
43 UNUM_FOUND_HALFEVEN = UNUM_ROUND_HALFEVEN,
44#endif /* U_HIDE_DEPRECATED_API */
45 UNUM_ROUND_HALFDOWN = UNUM_ROUND_HALFEVEN + 1,
46 UNUM_ROUND_HALFUP,
47 /**
48 * ROUND_UNNECESSARY reports an error if formatted result is not exact.
49 * @stable ICU 4.8
50 */
51 UNUM_ROUND_UNNECESSARY,
52 /**
53 * Rounds ties toward the odd number.
54 * @stable ICU 69
55 */
56 UNUM_ROUND_HALF_ODD,
57 /**
58 * Rounds ties toward +∞.
59 * @stable ICU 69
60 */
61 UNUM_ROUND_HALF_CEILING,
62 /**
63 * Rounds ties toward -∞.
64 * @stable ICU 69
65 */
66 UNUM_ROUND_HALF_FLOOR,
67} UNumberFormatRoundingMode;
68
69
70/**
71 * An enum declaring the strategy for when and how to display grouping separators (i.e., the
72 * separator, often a comma or period, after every 2-3 powers of ten). The choices are several
73 * pre-built strategies for different use cases that employ locale data whenever possible. Example
74 * outputs for 1234 and 1234567 in <em>en-IN</em>:
75 *
76 * <ul>
77 * <li>OFF: 1234 and 12345
78 * <li>MIN2: 1234 and 12,34,567
79 * <li>AUTO: 1,234 and 12,34,567
80 * <li>ON_ALIGNED: 1,234 and 12,34,567
81 * <li>THOUSANDS: 1,234 and 1,234,567
82 * </ul>
83 *
84 * <p>
85 * The default is AUTO, which displays grouping separators unless the locale data says that grouping
86 * is not customary. To force grouping for all numbers greater than 1000 consistently across locales,
87 * use ON_ALIGNED. On the other hand, to display grouping less frequently than the default, use MIN2
88 * or OFF. See the docs of each option for details.
89 *
90 * <p>
91 * Note: This enum specifies the strategy for grouping sizes. To set which character to use as the
92 * grouping separator, use the "symbols" setter.
93 *
94 * @stable ICU 63
95 */
96typedef enum UNumberGroupingStrategy {
97 /**
98 * Do not display grouping separators in any locale.
99 *
100 * @stable ICU 61
101 */
102 UNUM_GROUPING_OFF,
103
104 /**
105 * Display grouping using locale defaults, except do not show grouping on values smaller than
106 * 10000 (such that there is a <em>minimum of two digits</em> before the first separator).
107 *
108 * <p>
109 * Note that locales may restrict grouping separators to be displayed only on 1 million or
110 * greater (for example, ee and hu) or disable grouping altogether (for example, bg currency).
111 *
112 * <p>
113 * Locale data is used to determine whether to separate larger numbers into groups of 2
114 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas).
115 *
116 * @stable ICU 61
117 */
118 UNUM_GROUPING_MIN2,
119
120 /**
121 * Display grouping using the default strategy for all locales. This is the default behavior.
122 *
123 * <p>
124 * Note that locales may restrict grouping separators to be displayed only on 1 million or
125 * greater (for example, ee and hu) or disable grouping altogether (for example, bg currency).
126 *
127 * <p>
128 * Locale data is used to determine whether to separate larger numbers into groups of 2
129 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas).
130 *
131 * @stable ICU 61
132 */
133 UNUM_GROUPING_AUTO,
134
135 /**
136 * Always display the grouping separator on values of at least 1000.
137 *
138 * <p>
139 * This option ignores the locale data that restricts or disables grouping, described in MIN2 and
140 * AUTO. This option may be useful to normalize the alignment of numbers, such as in a
141 * spreadsheet.
142 *
143 * <p>
144 * Locale data is used to determine whether to separate larger numbers into groups of 2
145 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas).
146 *
147 * @stable ICU 61
148 */
149 UNUM_GROUPING_ON_ALIGNED,
150
151 /**
152 * Use the Western defaults: groups of 3 and enabled for all numbers 1000 or greater. Do not use
153 * locale data for determining the grouping strategy.
154 *
155 * @stable ICU 61
156 */
157 UNUM_GROUPING_THOUSANDS
158
159#ifndef U_HIDE_INTERNAL_API
160 ,
161 /**
162 * One more than the highest UNumberGroupingStrategy value.
163 *
164 * @internal ICU 62: The numeric value may change over time; see ICU ticket #12420.
165 */
166 UNUM_GROUPING_COUNT
167#endif /* U_HIDE_INTERNAL_API */
168
169} UNumberGroupingStrategy;
170
171
172#endif /* #if !UCONFIG_NO_FORMATTING */
173#endif //__UNUMBEROPTIONS_H__
174

source code of include/unicode/unumberoptions.h