summaryrefslogtreecommitdiffstats
path: root/intl/icu/source/i18n/unicode/unumberrangeformatter.h
blob: 106942f25af0b93288464febf8f44da720f24629 (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
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
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
// © 2020 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html

#ifndef __UNUMBERRANGEFORMATTER_H__
#define __UNUMBERRANGEFORMATTER_H__

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING

#include "unicode/parseerr.h"
#include "unicode/ufieldpositer.h"
#include "unicode/umisc.h"
#include "unicode/uformattedvalue.h"
#include "unicode/uformattable.h"


/**
 * \file
 * \brief C API: Localized number range formatting
 *
 * This is the C-compatible version of the NumberRangeFormatter API. C++ users
 * should include unicode/numberrangeformatter.h and use the proper C++ APIs.
 *
 * First create a UNumberRangeFormatter, which is immutable, and then format to
 * a UFormattedNumberRange.
 *
 * Example code:
 * <pre>
 * // Setup:
 * UErrorCode ec = U_ZERO_ERROR;
 * UNumberRangeFormatter* uformatter = unumrf_openForSkeletonCollapseIdentityFallbackAndLocaleWithError(
 *     u"currency/USD precision-integer",
 *     -1,
 *     UNUM_RANGE_COLLAPSE_AUTO,
 *     UNUM_IDENTITY_FALLBACK_APPROXIMATELY,
 *     "en-US",
 *     NULL,
 *     &ec);
 * UFormattedNumberRange* uresult = unumrf_openResult(&ec);
 * if (U_FAILURE(ec)) { return; }
 *
 * // Format a double range:
 * unumrf_formatDoubleRange(uformatter, 3.0, 5.0, uresult, &ec);
 * if (U_FAILURE(ec)) { return; }
 *
 * // Get the result string:
 * int32_t len;
 * const UChar* str = ufmtval_getString(unumrf_resultAsValue(uresult, &ec), &len, &ec);
 * if (U_FAILURE(ec)) { return; }
 * // str should equal "$3 – $5"
 *
 * // Cleanup:
 * unumf_close(uformatter);
 * unumf_closeResult(uresult);
 * </pre>
 *
 * If you are a C++ user linking against the C libraries, you can use the LocalPointer versions of these
 * APIs. The following example uses LocalPointer with the decimal number and field position APIs:
 *
 * <pre>
 * // Setup:
 * LocalUNumberRangeFormatterPointer uformatter(
 *     unumrf_openForSkeletonCollapseIdentityFallbackAndLocaleWithError(...));
 * LocalUFormattedNumberRangePointer uresult(unumrf_openResult(&ec));
 * if (U_FAILURE(ec)) { return; }
 *
 * // Format a double number range:
 * unumrf_formatDoubleRange(uformatter.getAlias(), 3.0, 5.0, uresult.getAlias(), &ec);
 * if (U_FAILURE(ec)) { return; }
 *
 * // No need to do any cleanup since we are using LocalPointer.
 * </pre>
 *
 * You can also get field positions. For more information, see uformattedvalue.h.
 */

/**
 * Defines how to merge fields that are identical across the range sign.
 *
 * @stable ICU 63
 */
typedef enum UNumberRangeCollapse {
    /**
     * Use locale data and heuristics to determine how much of the string to collapse. Could end up collapsing none,
     * some, or all repeated pieces in a locale-sensitive way.
     *
     * The heuristics used for this option are subject to change over time.
     *
     * @stable ICU 63
     */
    UNUM_RANGE_COLLAPSE_AUTO,

    /**
     * Do not collapse any part of the number. Example: "3.2 thousand kilograms – 5.3 thousand kilograms"
     *
     * @stable ICU 63
     */
    UNUM_RANGE_COLLAPSE_NONE,

    /**
     * Collapse the unit part of the number, but not the notation, if present. Example: "3.2 thousand – 5.3 thousand
     * kilograms"
     *
     * @stable ICU 63
     */
    UNUM_RANGE_COLLAPSE_UNIT,

    /**
     * Collapse any field that is equal across the range sign. May introduce ambiguity on the magnitude of the
     * number. Example: "3.2 – 5.3 thousand kilograms"
     *
     * @stable ICU 63
     */
    UNUM_RANGE_COLLAPSE_ALL
} UNumberRangeCollapse;

/**
 * Defines the behavior when the two numbers in the range are identical after rounding. To programmatically detect
 * when the identity fallback is used, compare the lower and upper BigDecimals via FormattedNumber.
 *
 * @stable ICU 63
 * @see NumberRangeFormatter
 */
typedef enum UNumberRangeIdentityFallback {
    /**
     * Show the number as a single value rather than a range. Example: "$5"
     *
     * @stable ICU 63
     */
    UNUM_IDENTITY_FALLBACK_SINGLE_VALUE,

    /**
     * Show the number using a locale-sensitive approximation pattern. If the numbers were the same before rounding,
     * show the single value. Example: "~$5" or "$5"
     *
     * @stable ICU 63
     */
    UNUM_IDENTITY_FALLBACK_APPROXIMATELY_OR_SINGLE_VALUE,

    /**
     * Show the number using a locale-sensitive approximation pattern. Use the range pattern always, even if the
     * inputs are the same. Example: "~$5"
     *
     * @stable ICU 63
     */
    UNUM_IDENTITY_FALLBACK_APPROXIMATELY,

    /**
     * Show the number as the range of two equal values. Use the range pattern always, even if the inputs are the
     * same. Example (with RangeCollapse.NONE): "$5 – $5"
     *
     * @stable ICU 63
     */
    UNUM_IDENTITY_FALLBACK_RANGE
} UNumberRangeIdentityFallback;

/**
 * Used in the result class FormattedNumberRange to indicate to the user whether the numbers formatted in the range
 * were equal or not, and whether or not the identity fallback was applied.
 *
 * @stable ICU 63
 * @see NumberRangeFormatter
 */
typedef enum UNumberRangeIdentityResult {
    /**
     * Used to indicate that the two numbers in the range were equal, even before any rounding rules were applied.
     *
     * @stable ICU 63
     * @see NumberRangeFormatter
     */
    UNUM_IDENTITY_RESULT_EQUAL_BEFORE_ROUNDING,

    /**
     * Used to indicate that the two numbers in the range were equal, but only after rounding rules were applied.
     *
     * @stable ICU 63
     * @see NumberRangeFormatter
     */
    UNUM_IDENTITY_RESULT_EQUAL_AFTER_ROUNDING,

    /**
     * Used to indicate that the two numbers in the range were not equal, even after rounding rules were applied.
     *
     * @stable ICU 63
     * @see NumberRangeFormatter
     */
    UNUM_IDENTITY_RESULT_NOT_EQUAL,

#ifndef U_HIDE_INTERNAL_API
    /**
     * The number of entries in this enum.
     * @internal
     */
    UNUM_IDENTITY_RESULT_COUNT
#endif  /* U_HIDE_INTERNAL_API */

} UNumberRangeIdentityResult;


struct UNumberRangeFormatter;
/**
 * C-compatible version of icu::number::LocalizedNumberRangeFormatter.
 *
 * NOTE: This is a C-compatible API; C++ users should build against numberrangeformatter.h instead.
 *
 * @stable ICU 68
 */
typedef struct UNumberRangeFormatter UNumberRangeFormatter;


struct UFormattedNumberRange;
/**
 * C-compatible version of icu::number::FormattedNumberRange.
 *
 * NOTE: This is a C-compatible API; C++ users should build against numberrangeformatter.h instead.
 *
 * @stable ICU 68
 */
typedef struct UFormattedNumberRange UFormattedNumberRange;


/**
 * Creates a new UNumberFormatter for the given skeleton string, collapse option, identity fallback
 * option, and locale. This is currently the only method for creating a new UNumberRangeFormatter.
 *
 * Objects of type UNumberRangeFormatter returned by this method are threadsafe.
 *
 * For more details on skeleton strings, see the documentation in numberrangeformatter.h. For more
 * details on the usage of this API, see the documentation at the top of unumberrangeformatter.h.
 *
 * NOTE: This is a C-compatible API; C++ users should build against numberrangeformatter.h instead.
 *
 * @param skeleton The skeleton string, like u"percent precision-integer"
 * @param skeletonLen The number of UChars in the skeleton string, or -1 if it is NUL-terminated.
 * @param collapse Option for how to merge affixes (if unsure, use UNUM_RANGE_COLLAPSE_AUTO)
 * @param identityFallback Option for resolving when both sides of the range are equal.
 * @param locale The NUL-terminated locale ID.
 * @param perror A parse error struct populated if an error occurs when parsing. Can be NULL.
 *               If no error occurs, perror->offset will be set to -1.
 * @param ec Set if an error occurs.
 * @stable ICU 68
 */
U_CAPI UNumberRangeFormatter* U_EXPORT2
unumrf_openForSkeletonWithCollapseAndIdentityFallback(
    const UChar* skeleton,
    int32_t skeletonLen,
    UNumberRangeCollapse collapse,
    UNumberRangeIdentityFallback identityFallback,
    const char* locale,
    UParseError* perror,
    UErrorCode* ec);


/**
 * Creates an object to hold the result of a UNumberRangeFormatter
 * 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 68
 */
U_CAPI UFormattedNumberRange* U_EXPORT2
unumrf_openResult(UErrorCode* ec);


/**
 * Uses a UNumberRangeFormatter to format a range of doubles.
 *
 * The UNumberRangeFormatter can be shared between threads. Each thread should have its own local
 * UFormattedNumberRange, however, for storing the result of the formatting operation.
 *
 * NOTE: This is a C-compatible API; C++ users should build against numberrangeformatter.h instead.
 *
 * @param uformatter A formatter object; see unumberrangeformatter.h.
 * @param first The first (usually smaller) number in the range.
 * @param second The second (usually larger) number in the range.
 * @param uresult The object that will be mutated to store the result; see unumrf_openResult.
 * @param ec Set if an error occurs.
 * @stable ICU 68
 */
U_CAPI void U_EXPORT2
unumrf_formatDoubleRange(
    const UNumberRangeFormatter* uformatter,
    double first,
    double second,
    UFormattedNumberRange* uresult,
    UErrorCode* ec);


/**
 * Uses a UNumberRangeFormatter to format a range of decimal numbers.
 *
 * With a decimal number string, you can specify an input with arbitrary precision.
 *
 * The UNumberRangeFormatter can be shared between threads. Each thread should have its own local
 * UFormattedNumberRange, however, for storing the result of the formatting operation.
 *
 * NOTE: This is a C-compatible API; C++ users should build against numberrangeformatter.h instead.
 *
 * @param uformatter A formatter object; see unumberrangeformatter.h.
 * @param first The first (usually smaller) number in the range.
 * @param firstLen The length of the first decimal number string.
 * @param second The second (usually larger) number in the range.
 * @param secondLen The length of the second decimal number string.
 * @param uresult The object that will be mutated to store the result; see unumrf_openResult.
 * @param ec Set if an error occurs.
 * @stable ICU 68
 */
U_CAPI void U_EXPORT2
unumrf_formatDecimalRange(
    const UNumberRangeFormatter* uformatter,
    const char* first,
    int32_t firstLen,
    const char* second,
    int32_t secondLen,
    UFormattedNumberRange* uresult,
    UErrorCode* ec);


/**
 * Returns a representation of a UFormattedNumberRange as a UFormattedValue,
 * which can be subsequently passed to any API requiring that type.
 *
 * The returned object is owned by the UFormattedNumberRange 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 number range.
 * @param ec Set if an error occurs.
 * @return A UFormattedValue owned by the input object.
 * @stable ICU 68
 */
U_CAPI const UFormattedValue* U_EXPORT2
unumrf_resultAsValue(const UFormattedNumberRange* uresult, UErrorCode* ec);


/**
 * Extracts the identity result from a UFormattedNumberRange.
 *
 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
 *
 * @param uresult The object containing the formatted number range.
 * @param ec Set if an error occurs.
 * @return The identity result; see UNumberRangeIdentityResult.
 * @stable ICU 68
 */
U_CAPI UNumberRangeIdentityResult U_EXPORT2
unumrf_resultGetIdentityResult(
    const UFormattedNumberRange* uresult,
    UErrorCode* ec);


/**
 * Extracts the first formatted number as a decimal number. This endpoint
 * is useful for obtaining the exact number being printed after scaling
 * and rounding have been applied by the number range formatting pipeline.
 * 
 * The syntax of the unformatted number is a "numeric string"
 * as defined in the Decimal Arithmetic Specification, available at
 * http://speleotrove.com/decimal
 *
 * @param  uresult       The input object containing the formatted number range.
 * @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
unumrf_resultGetFirstDecimalNumber(
    const UFormattedNumberRange* uresult,
    char* dest,
    int32_t destCapacity,
    UErrorCode* ec);


/**
 * Extracts the second formatted number as a decimal number. This endpoint
 * is useful for obtaining the exact number being printed after scaling
 * and rounding have been applied by the number range formatting pipeline.
 * 
 * The syntax of the unformatted number is a "numeric string"
 * as defined in the Decimal Arithmetic Specification, available at
 * http://speleotrove.com/decimal
 *
 * @param  uresult       The input object containing the formatted number range.
 * @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
unumrf_resultGetSecondDecimalNumber(
    const UFormattedNumberRange* uresult,
    char* dest,
    int32_t destCapacity,
    UErrorCode* ec);


/**
 * Releases the UNumberFormatter created by unumf_openForSkeletonAndLocale().
 *
 * @param uformatter An object created by unumf_openForSkeletonAndLocale().
 * @stable ICU 68
 */
U_CAPI void U_EXPORT2
unumrf_close(UNumberRangeFormatter* uformatter);


/**
 * Releases the UFormattedNumber created by unumf_openResult().
 *
 * @param uresult An object created by unumf_openResult().
 * @stable ICU 68
 */
U_CAPI void U_EXPORT2
unumrf_closeResult(UFormattedNumberRange* uresult);


#if U_SHOW_CPLUSPLUS_API
U_NAMESPACE_BEGIN

/**
 * \class LocalUNumberRangeFormatterPointer
 * "Smart pointer" class; closes a UNumberFormatter via unumf_close().
 * For most methods see the LocalPointerBase base class.
 *
 * Usage:
 * <pre>
 * LocalUNumberRangeFormatterPointer uformatter(
 *     unumrf_openForSkeletonCollapseIdentityFallbackAndLocaleWithError(...));
 * // no need to explicitly call unumrf_close()
 * </pre>
 *
 * @see LocalPointerBase
 * @see LocalPointer
 * @stable ICU 68
 */
U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberRangeFormatterPointer, UNumberRangeFormatter, unumrf_close);

/**
 * \class LocalUFormattedNumberPointer
 * "Smart pointer" class; closes a UFormattedNumber via unumf_closeResult().
 * For most methods see the LocalPointerBase base class.
 *
 * Usage:
 * <pre>
 * LocalUFormattedNumberRangePointer uresult(unumrf_openResult(...));
 * // no need to explicitly call unumrf_closeResult()
 * </pre>
 *
 * @see LocalPointerBase
 * @see LocalPointer
 * @stable ICU 68
 */
U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedNumberRangePointer, UFormattedNumberRange, unumrf_closeResult);

U_NAMESPACE_END
#endif // U_SHOW_CPLUSPLUS_API

#endif /* #if !UCONFIG_NO_FORMATTING */
#endif //__UNUMBERRANGEFORMATTER_H__