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
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
// © 2022 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
#ifndef __UFORMATTEDNUMBER_H__
#define __UFORMATTEDNUMBER_H__
#include "unicode/utypes.h"
#if !UCONFIG_NO_FORMATTING
#include "unicode/ufieldpositer.h"
#include "unicode/uformattedvalue.h"
#include "unicode/umisc.h"
/**
* \file
* \brief C API: Formatted number result from various number formatting functions.
*
* Create a `UFormattedNumber` to hold the result of a number formatting operation. The same
* `UFormattedNumber` can be reused multiple times.
*
* <pre>
* LocalUFormattedNumberPointer uresult(unumf_openResult(status));
*
* // pass uresult.getAlias() to your number formatter
*
* int32_t length;
* const UChar* s = ufmtval_getString(unumf_resultAsValue(uresult.getAlias(), status), &length, status));
*
* // The string result is in `s` with the given `length` (it is also NUL-terminated).
* </pre>
*/
struct UFormattedNumber;
/**
* C-compatible version of icu::number::FormattedNumber.
*
* NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
*
* @stable ICU 62
*/
typedef struct UFormattedNumber UFormattedNumber;
/**
* Creates an object to hold the result of a UNumberFormatter
* operation. The object can be used repeatedly; it is cleared whenever
* passed to a format function.
*
* @param ec Set if an error occurs.
* @stable ICU 62
*/
U_CAPI UFormattedNumber* U_EXPORT2
unumf_openResult(UErrorCode* ec);
/**
* Returns a representation of a UFormattedNumber as a UFormattedValue,
* which can be subsequently passed to any API requiring that type.
*
* The returned object is owned by the UFormattedNumber and is valid
* only as long as the UFormattedNumber is present and unchanged in memory.
*
* You can think of this method as a cast between types.
*
* @param uresult The object containing the formatted string.
* @param ec Set if an error occurs.
* @return A UFormattedValue owned by the input object.
* @stable ICU 64
*/
U_CAPI const UFormattedValue* U_EXPORT2
unumf_resultAsValue(const UFormattedNumber* uresult, UErrorCode* ec);
/**
* Extracts the result number string out of a UFormattedNumber to a UChar buffer if possible.
* If bufferCapacity is greater than the required length, a terminating NUL is written.
* If bufferCapacity is less than the required length, an error code is set.
*
* Also see ufmtval_getString, which returns a NUL-terminated string:
*
* int32_t len;
* const UChar* str = ufmtval_getString(unumf_resultAsValue(uresult, &ec), &len, &ec);
*
* NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
*
* @param uresult The object containing the formatted number.
* @param buffer Where to save the string output.
* @param bufferCapacity The number of UChars available in the buffer.
* @param ec Set if an error occurs.
* @return The required length.
* @stable ICU 62
*/
U_CAPI int32_t U_EXPORT2
unumf_resultToString(const UFormattedNumber* uresult, UChar* buffer, int32_t bufferCapacity,
UErrorCode* ec);
/**
* Determines the start and end indices of the next occurrence of the given <em>field</em> in the
* output string. This allows you to determine the locations of, for example, the integer part,
* fraction part, or symbols.
*
* This is a simpler but less powerful alternative to {@link ufmtval_nextPosition}.
*
* If a field occurs just once, calling this method will find that occurrence and return it. If a
* field occurs multiple times, this method may be called repeatedly with the following pattern:
*
* <pre>
* UFieldPosition ufpos = {UNUM_GROUPING_SEPARATOR_FIELD, 0, 0};
* while (unumf_resultNextFieldPosition(uresult, ufpos, &ec)) {
* // do something with ufpos.
* }
* </pre>
*
* This method is useful if you know which field to query. If you want all available field position
* information, use unumf_resultGetAllFieldPositions().
*
* NOTE: All fields of the UFieldPosition must be initialized before calling this method.
*
* @param uresult The object containing the formatted number.
* @param ufpos
* Input+output variable. On input, the "field" property determines which field to look up,
* and the "endIndex" property determines where to begin the search. On output, the
* "beginIndex" field is set to the beginning of the first occurrence of the field after the
* input "endIndex", and "endIndex" is set to the end of that occurrence of the field
* (exclusive index). If a field position is not found, the FieldPosition is not changed and
* the method returns false.
* @param ec Set if an error occurs.
* @stable ICU 62
*/
U_CAPI UBool U_EXPORT2
unumf_resultNextFieldPosition(const UFormattedNumber* uresult, UFieldPosition* ufpos, UErrorCode* ec);
/**
* Populates the given iterator with all fields in the formatted output string. This allows you to
* determine the locations of the integer part, fraction part, and sign.
*
* This is an alternative to the more powerful {@link ufmtval_nextPosition} API.
*
* If you need information on only one field, use {@link ufmtval_nextPosition} or
* {@link unumf_resultNextFieldPosition}.
*
* @param uresult The object containing the formatted number.
* @param ufpositer
* A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open}. Iteration
* information already present in the UFieldPositionIterator is deleted, and the iterator is reset
* to apply to the fields in the formatted string created by this function call. The field values
* and indexes returned by {@link #ufieldpositer_next} represent fields denoted by
* the UNumberFormatFields enum. Fields are not returned in a guaranteed order. Fields cannot
* overlap, but they may nest. For example, 1234 could format as "1,234" which might consist of a
* grouping separator field for ',' and an integer field encompassing the entire string.
* @param ec Set if an error occurs.
* @stable ICU 62
*/
U_CAPI void U_EXPORT2
unumf_resultGetAllFieldPositions(const UFormattedNumber* uresult, UFieldPositionIterator* ufpositer,
UErrorCode* ec);
/**
* Extracts the formatted number as a "numeric string" conforming to the
* syntax defined in the Decimal Arithmetic Specification, available at
* http://speleotrove.com/decimal
*
* This endpoint is useful for obtaining the exact number being printed
* after scaling and rounding have been applied by the number formatter.
*
* @param uresult The input object containing the formatted number.
* @param dest the 8-bit char buffer into which the decimal number is placed
* @param destCapacity The size, in chars, of the destination buffer. May be zero
* for precomputing the required size.
* @param ec receives any error status.
* If U_BUFFER_OVERFLOW_ERROR: Returns number of chars for
* preflighting.
* @return Number of chars in the data. Does not include a trailing NUL.
* @stable ICU 68
*/
U_CAPI int32_t U_EXPORT2
unumf_resultToDecimalNumber(
const UFormattedNumber* uresult,
char* dest,
int32_t destCapacity,
UErrorCode* ec);
/**
* Releases the UFormattedNumber created by unumf_openResult().
*
* @param uresult An object created by unumf_openResult().
* @stable ICU 62
*/
U_CAPI void U_EXPORT2
unumf_closeResult(UFormattedNumber* uresult);
#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN
/**
* \class LocalUFormattedNumberPointer
* "Smart pointer" class; closes a UFormattedNumber via unumf_closeResult().
* For most methods see the LocalPointerBase base class.
*
* Usage:
* <pre>
* LocalUFormattedNumberPointer uformatter(unumf_openResult(...));
* // no need to explicitly call unumf_closeResult()
* </pre>
*
* @see LocalPointerBase
* @see LocalPointer
* @stable ICU 62
*/
U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedNumberPointer, UFormattedNumber, unumf_closeResult);
U_NAMESPACE_END
#endif // U_SHOW_CPLUSPLUS_API
#endif /* #if !UCONFIG_NO_FORMATTING */
#endif //__UFORMATTEDNUMBER_H__
|
