Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/unumberformatter.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2018 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3
jpayne@69 4 #include "unicode/utypes.h"
jpayne@69 5
jpayne@69 6 #if !UCONFIG_NO_FORMATTING
jpayne@69 7 #ifndef __UNUMBERFORMATTER_H__
jpayne@69 8 #define __UNUMBERFORMATTER_H__
jpayne@69 9
jpayne@69 10 #include "unicode/parseerr.h"
jpayne@69 11 #include "unicode/ufieldpositer.h"
jpayne@69 12 #include "unicode/umisc.h"
jpayne@69 13 #include "unicode/uformattedvalue.h"
jpayne@69 14
jpayne@69 15
jpayne@69 16 /**
jpayne@69 17 * \file
jpayne@69 18 * \brief C-compatible API for localized number formatting; not recommended for C++.
jpayne@69 19 *
jpayne@69 20 * This is the C-compatible version of the NumberFormatter API introduced in ICU 60. C++ users should
jpayne@69 21 * include unicode/numberformatter.h and use the proper C++ APIs.
jpayne@69 22 *
jpayne@69 23 * The C API accepts a number skeleton string for specifying the settings for formatting, which covers a
jpayne@69 24 * very large subset of all possible number formatting features. For more information on number skeleton
jpayne@69 25 * strings, see unicode/numberformatter.h.
jpayne@69 26 *
jpayne@69 27 * When using UNumberFormatter, which is treated as immutable, the results are exported to a mutable
jpayne@69 28 * UFormattedNumber object, which you subsequently use for populating your string buffer or iterating over
jpayne@69 29 * the fields.
jpayne@69 30 *
jpayne@69 31 * Example code:
jpayne@69 32 * <pre>
jpayne@69 33 * // Setup:
jpayne@69 34 * UErrorCode ec = U_ZERO_ERROR;
jpayne@69 35 * UNumberFormatter* uformatter = unumf_openForSkeletonAndLocale(u"precision-integer", -1, "en", &ec);
jpayne@69 36 * UFormattedNumber* uresult = unumf_openResult(&ec);
jpayne@69 37 * if (U_FAILURE(ec)) { return; }
jpayne@69 38 *
jpayne@69 39 * // Format a double:
jpayne@69 40 * unumf_formatDouble(uformatter, 5142.3, uresult, &ec);
jpayne@69 41 * if (U_FAILURE(ec)) { return; }
jpayne@69 42 *
jpayne@69 43 * // Export the string to a malloc'd buffer:
jpayne@69 44 * int32_t len = unumf_resultToString(uresult, NULL, 0, &ec);
jpayne@69 45 * // at this point, ec == U_BUFFER_OVERFLOW_ERROR
jpayne@69 46 * ec = U_ZERO_ERROR;
jpayne@69 47 * UChar* buffer = (UChar*) malloc((len+1)*sizeof(UChar));
jpayne@69 48 * unumf_resultToString(uresult, buffer, len+1, &ec);
jpayne@69 49 * if (U_FAILURE(ec)) { return; }
jpayne@69 50 * // buffer should equal "5,142"
jpayne@69 51 *
jpayne@69 52 * // Cleanup:
jpayne@69 53 * unumf_close(uformatter);
jpayne@69 54 * unumf_closeResult(uresult);
jpayne@69 55 * free(buffer);
jpayne@69 56 * </pre>
jpayne@69 57 *
jpayne@69 58 * If you are a C++ user linking against the C libraries, you can use the LocalPointer versions of these
jpayne@69 59 * APIs. The following example uses LocalPointer with the decimal number and field position APIs:
jpayne@69 60 *
jpayne@69 61 * <pre>
jpayne@69 62 * // Setup:
jpayne@69 63 * LocalUNumberFormatterPointer uformatter(unumf_openForSkeletonAndLocale(u"percent", -1, "en", &ec));
jpayne@69 64 * LocalUFormattedNumberPointer uresult(unumf_openResult(&ec));
jpayne@69 65 * if (U_FAILURE(ec)) { return; }
jpayne@69 66 *
jpayne@69 67 * // Format a decimal number:
jpayne@69 68 * unumf_formatDecimal(uformatter.getAlias(), "9.87E-3", -1, uresult.getAlias(), &ec);
jpayne@69 69 * if (U_FAILURE(ec)) { return; }
jpayne@69 70 *
jpayne@69 71 * // Get the location of the percent sign:
jpayne@69 72 * UFieldPosition ufpos = {UNUM_PERCENT_FIELD, 0, 0};
jpayne@69 73 * unumf_resultNextFieldPosition(uresult.getAlias(), &ufpos, &ec);
jpayne@69 74 * // ufpos should contain beginIndex=7 and endIndex=8 since the string is "0.00987%"
jpayne@69 75 *
jpayne@69 76 * // No need to do any cleanup since we are using LocalPointer.
jpayne@69 77 * </pre>
jpayne@69 78 */
jpayne@69 79
jpayne@69 80 /**
jpayne@69 81 * An enum declaring how to render units, including currencies. Example outputs when formatting 123 USD and 123
jpayne@69 82 * meters in <em>en-CA</em>:
jpayne@69 83 *
jpayne@69 84 * <p>
jpayne@69 85 * <ul>
jpayne@69 86 * <li>NARROW*: "$123.00" and "123 m"
jpayne@69 87 * <li>SHORT: "US$ 123.00" and "123 m"
jpayne@69 88 * <li>FULL_NAME: "123.00 US dollars" and "123 meters"
jpayne@69 89 * <li>ISO_CODE: "USD 123.00" and undefined behavior
jpayne@69 90 * <li>HIDDEN: "123.00" and "123"
jpayne@69 91 * </ul>
jpayne@69 92 *
jpayne@69 93 * <p>
jpayne@69 94 * This enum is similar to {@link UMeasureFormatWidth}.
jpayne@69 95 *
jpayne@69 96 * @stable ICU 60
jpayne@69 97 */
jpayne@69 98 typedef enum UNumberUnitWidth {
jpayne@69 99 /**
jpayne@69 100 * Print an abbreviated version of the unit name. Similar to SHORT, but always use the shortest available
jpayne@69 101 * abbreviation or symbol. This option can be used when the context hints at the identity of the unit. For more
jpayne@69 102 * information on the difference between NARROW and SHORT, see SHORT.
jpayne@69 103 *
jpayne@69 104 * <p>
jpayne@69 105 * In CLDR, this option corresponds to the "Narrow" format for measure units and the "¤¤¤¤¤" placeholder for
jpayne@69 106 * currencies.
jpayne@69 107 *
jpayne@69 108 * @stable ICU 60
jpayne@69 109 */
jpayne@69 110 UNUM_UNIT_WIDTH_NARROW,
jpayne@69 111
jpayne@69 112 /**
jpayne@69 113 * Print an abbreviated version of the unit name. Similar to NARROW, but use a slightly wider abbreviation or
jpayne@69 114 * symbol when there may be ambiguity. This is the default behavior.
jpayne@69 115 *
jpayne@69 116 * <p>
jpayne@69 117 * For example, in <em>es-US</em>, the SHORT form for Fahrenheit is "{0} °F", but the NARROW form is "{0}°",
jpayne@69 118 * since Fahrenheit is the customary unit for temperature in that locale.
jpayne@69 119 *
jpayne@69 120 * <p>
jpayne@69 121 * In CLDR, this option corresponds to the "Short" format for measure units and the "¤" placeholder for
jpayne@69 122 * currencies.
jpayne@69 123 *
jpayne@69 124 * @stable ICU 60
jpayne@69 125 */
jpayne@69 126 UNUM_UNIT_WIDTH_SHORT,
jpayne@69 127
jpayne@69 128 /**
jpayne@69 129 * Print the full name of the unit, without any abbreviations.
jpayne@69 130 *
jpayne@69 131 * <p>
jpayne@69 132 * In CLDR, this option corresponds to the default format for measure units and the "¤¤¤" placeholder for
jpayne@69 133 * currencies.
jpayne@69 134 *
jpayne@69 135 * @stable ICU 60
jpayne@69 136 */
jpayne@69 137 UNUM_UNIT_WIDTH_FULL_NAME,
jpayne@69 138
jpayne@69 139 /**
jpayne@69 140 * Use the three-digit ISO XXX code in place of the symbol for displaying currencies. The behavior of this
jpayne@69 141 * option is currently undefined for use with measure units.
jpayne@69 142 *
jpayne@69 143 * <p>
jpayne@69 144 * In CLDR, this option corresponds to the "¤¤" placeholder for currencies.
jpayne@69 145 *
jpayne@69 146 * @stable ICU 60
jpayne@69 147 */
jpayne@69 148 UNUM_UNIT_WIDTH_ISO_CODE,
jpayne@69 149
jpayne@69 150 /**
jpayne@69 151 * Format the number according to the specified unit, but do not display the unit. For currencies, apply
jpayne@69 152 * monetary symbols and formats as with SHORT, but omit the currency symbol. For measure units, the behavior is
jpayne@69 153 * equivalent to not specifying the unit at all.
jpayne@69 154 *
jpayne@69 155 * @stable ICU 60
jpayne@69 156 */
jpayne@69 157 UNUM_UNIT_WIDTH_HIDDEN,
jpayne@69 158
jpayne@69 159 /**
jpayne@69 160 * One more than the highest UNumberUnitWidth value.
jpayne@69 161 *
jpayne@69 162 * @internal ICU 60: The numeric value may change over time; see ICU ticket #12420.
jpayne@69 163 */
jpayne@69 164 UNUM_UNIT_WIDTH_COUNT
jpayne@69 165 } UNumberUnitWidth;
jpayne@69 166
jpayne@69 167 /**
jpayne@69 168 * An enum declaring the strategy for when and how to display grouping separators (i.e., the
jpayne@69 169 * separator, often a comma or period, after every 2-3 powers of ten). The choices are several
jpayne@69 170 * pre-built strategies for different use cases that employ locale data whenever possible. Example
jpayne@69 171 * outputs for 1234 and 1234567 in <em>en-IN</em>:
jpayne@69 172 *
jpayne@69 173 * <ul>
jpayne@69 174 * <li>OFF: 1234 and 12345
jpayne@69 175 * <li>MIN2: 1234 and 12,34,567
jpayne@69 176 * <li>AUTO: 1,234 and 12,34,567
jpayne@69 177 * <li>ON_ALIGNED: 1,234 and 12,34,567
jpayne@69 178 * <li>THOUSANDS: 1,234 and 1,234,567
jpayne@69 179 * </ul>
jpayne@69 180 *
jpayne@69 181 * <p>
jpayne@69 182 * The default is AUTO, which displays grouping separators unless the locale data says that grouping
jpayne@69 183 * is not customary. To force grouping for all numbers greater than 1000 consistently across locales,
jpayne@69 184 * use ON_ALIGNED. On the other hand, to display grouping less frequently than the default, use MIN2
jpayne@69 185 * or OFF. See the docs of each option for details.
jpayne@69 186 *
jpayne@69 187 * <p>
jpayne@69 188 * Note: This enum specifies the strategy for grouping sizes. To set which character to use as the
jpayne@69 189 * grouping separator, use the "symbols" setter.
jpayne@69 190 *
jpayne@69 191 * @stable ICU 63
jpayne@69 192 */
jpayne@69 193 typedef enum UNumberGroupingStrategy {
jpayne@69 194 /**
jpayne@69 195 * Do not display grouping separators in any locale.
jpayne@69 196 *
jpayne@69 197 * @stable ICU 61
jpayne@69 198 */
jpayne@69 199 UNUM_GROUPING_OFF,
jpayne@69 200
jpayne@69 201 /**
jpayne@69 202 * Display grouping using locale defaults, except do not show grouping on values smaller than
jpayne@69 203 * 10000 (such that there is a <em>minimum of two digits</em> before the first separator).
jpayne@69 204 *
jpayne@69 205 * <p>
jpayne@69 206 * Note that locales may restrict grouping separators to be displayed only on 1 million or
jpayne@69 207 * greater (for example, ee and hu) or disable grouping altogether (for example, bg currency).
jpayne@69 208 *
jpayne@69 209 * <p>
jpayne@69 210 * Locale data is used to determine whether to separate larger numbers into groups of 2
jpayne@69 211 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas).
jpayne@69 212 *
jpayne@69 213 * @stable ICU 61
jpayne@69 214 */
jpayne@69 215 UNUM_GROUPING_MIN2,
jpayne@69 216
jpayne@69 217 /**
jpayne@69 218 * Display grouping using the default strategy for all locales. This is the default behavior.
jpayne@69 219 *
jpayne@69 220 * <p>
jpayne@69 221 * Note that locales may restrict grouping separators to be displayed only on 1 million or
jpayne@69 222 * greater (for example, ee and hu) or disable grouping altogether (for example, bg currency).
jpayne@69 223 *
jpayne@69 224 * <p>
jpayne@69 225 * Locale data is used to determine whether to separate larger numbers into groups of 2
jpayne@69 226 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas).
jpayne@69 227 *
jpayne@69 228 * @stable ICU 61
jpayne@69 229 */
jpayne@69 230 UNUM_GROUPING_AUTO,
jpayne@69 231
jpayne@69 232 /**
jpayne@69 233 * Always display the grouping separator on values of at least 1000.
jpayne@69 234 *
jpayne@69 235 * <p>
jpayne@69 236 * This option ignores the locale data that restricts or disables grouping, described in MIN2 and
jpayne@69 237 * AUTO. This option may be useful to normalize the alignment of numbers, such as in a
jpayne@69 238 * spreadsheet.
jpayne@69 239 *
jpayne@69 240 * <p>
jpayne@69 241 * Locale data is used to determine whether to separate larger numbers into groups of 2
jpayne@69 242 * (customary in South Asia) or groups of 3 (customary in Europe and the Americas).
jpayne@69 243 *
jpayne@69 244 * @stable ICU 61
jpayne@69 245 */
jpayne@69 246 UNUM_GROUPING_ON_ALIGNED,
jpayne@69 247
jpayne@69 248 /**
jpayne@69 249 * Use the Western defaults: groups of 3 and enabled for all numbers 1000 or greater. Do not use
jpayne@69 250 * locale data for determining the grouping strategy.
jpayne@69 251 *
jpayne@69 252 * @stable ICU 61
jpayne@69 253 */
jpayne@69 254 UNUM_GROUPING_THOUSANDS
jpayne@69 255
jpayne@69 256 #ifndef U_HIDE_INTERNAL_API
jpayne@69 257 ,
jpayne@69 258 /**
jpayne@69 259 * One more than the highest UNumberGroupingStrategy value.
jpayne@69 260 *
jpayne@69 261 * @internal ICU 62: The numeric value may change over time; see ICU ticket #12420.
jpayne@69 262 */
jpayne@69 263 UNUM_GROUPING_COUNT
jpayne@69 264 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 265
jpayne@69 266 } UNumberGroupingStrategy;
jpayne@69 267
jpayne@69 268 /**
jpayne@69 269 * An enum declaring how to denote positive and negative numbers. Example outputs when formatting
jpayne@69 270 * 123, 0, and -123 in <em>en-US</em>:
jpayne@69 271 *
jpayne@69 272 * <ul>
jpayne@69 273 * <li>AUTO: "123", "0", and "-123"
jpayne@69 274 * <li>ALWAYS: "+123", "+0", and "-123"
jpayne@69 275 * <li>NEVER: "123", "0", and "123"
jpayne@69 276 * <li>ACCOUNTING: "$123", "$0", and "($123)"
jpayne@69 277 * <li>ACCOUNTING_ALWAYS: "+$123", "+$0", and "($123)"
jpayne@69 278 * <li>EXCEPT_ZERO: "+123", "0", and "-123"
jpayne@69 279 * <li>ACCOUNTING_EXCEPT_ZERO: "+$123", "$0", and "($123)"
jpayne@69 280 * </ul>
jpayne@69 281 *
jpayne@69 282 * <p>
jpayne@69 283 * The exact format, including the position and the code point of the sign, differ by locale.
jpayne@69 284 *
jpayne@69 285 * @stable ICU 60
jpayne@69 286 */
jpayne@69 287 typedef enum UNumberSignDisplay {
jpayne@69 288 /**
jpayne@69 289 * Show the minus sign on negative numbers, and do not show the sign on positive numbers. This is the default
jpayne@69 290 * behavior.
jpayne@69 291 *
jpayne@69 292 * @stable ICU 60
jpayne@69 293 */
jpayne@69 294 UNUM_SIGN_AUTO,
jpayne@69 295
jpayne@69 296 /**
jpayne@69 297 * Show the minus sign on negative numbers and the plus sign on positive numbers, including zero.
jpayne@69 298 * To hide the sign on zero, see {@link UNUM_SIGN_EXCEPT_ZERO}.
jpayne@69 299 *
jpayne@69 300 * @stable ICU 60
jpayne@69 301 */
jpayne@69 302 UNUM_SIGN_ALWAYS,
jpayne@69 303
jpayne@69 304 /**
jpayne@69 305 * Do not show the sign on positive or negative numbers.
jpayne@69 306 *
jpayne@69 307 * @stable ICU 60
jpayne@69 308 */
jpayne@69 309 UNUM_SIGN_NEVER,
jpayne@69 310
jpayne@69 311 /**
jpayne@69 312 * Use the locale-dependent accounting format on negative numbers, and do not show the sign on positive numbers.
jpayne@69 313 *
jpayne@69 314 * <p>
jpayne@69 315 * The accounting format is defined in CLDR and varies by locale; in many Western locales, the format is a pair
jpayne@69 316 * of parentheses around the number.
jpayne@69 317 *
jpayne@69 318 * <p>
jpayne@69 319 * Note: Since CLDR defines the accounting format in the monetary context only, this option falls back to the
jpayne@69 320 * AUTO sign display strategy when formatting without a currency unit. This limitation may be lifted in the
jpayne@69 321 * future.
jpayne@69 322 *
jpayne@69 323 * @stable ICU 60
jpayne@69 324 */
jpayne@69 325 UNUM_SIGN_ACCOUNTING,
jpayne@69 326
jpayne@69 327 /**
jpayne@69 328 * Use the locale-dependent accounting format on negative numbers, and show the plus sign on
jpayne@69 329 * positive numbers, including zero. For more information on the accounting format, see the
jpayne@69 330 * ACCOUNTING sign display strategy. To hide the sign on zero, see
jpayne@69 331 * {@link UNUM_SIGN_ACCOUNTING_EXCEPT_ZERO}.
jpayne@69 332 *
jpayne@69 333 * @stable ICU 60
jpayne@69 334 */
jpayne@69 335 UNUM_SIGN_ACCOUNTING_ALWAYS,
jpayne@69 336
jpayne@69 337 /**
jpayne@69 338 * Show the minus sign on negative numbers and the plus sign on positive numbers. Do not show a
jpayne@69 339 * sign on zero, numbers that round to zero, or NaN.
jpayne@69 340 *
jpayne@69 341 * @stable ICU 61
jpayne@69 342 */
jpayne@69 343 UNUM_SIGN_EXCEPT_ZERO,
jpayne@69 344
jpayne@69 345 /**
jpayne@69 346 * Use the locale-dependent accounting format on negative numbers, and show the plus sign on
jpayne@69 347 * positive numbers. Do not show a sign on zero, numbers that round to zero, or NaN. For more
jpayne@69 348 * information on the accounting format, see the ACCOUNTING sign display strategy.
jpayne@69 349 *
jpayne@69 350 * @stable ICU 61
jpayne@69 351 */
jpayne@69 352 UNUM_SIGN_ACCOUNTING_EXCEPT_ZERO,
jpayne@69 353
jpayne@69 354 /**
jpayne@69 355 * One more than the highest UNumberSignDisplay value.
jpayne@69 356 *
jpayne@69 357 * @internal ICU 60: The numeric value may change over time; see ICU ticket #12420.
jpayne@69 358 */
jpayne@69 359 UNUM_SIGN_COUNT
jpayne@69 360 } UNumberSignDisplay;
jpayne@69 361
jpayne@69 362 /**
jpayne@69 363 * An enum declaring how to render the decimal separator.
jpayne@69 364 *
jpayne@69 365 * <p>
jpayne@69 366 * <ul>
jpayne@69 367 * <li>UNUM_DECIMAL_SEPARATOR_AUTO: "1", "1.1"
jpayne@69 368 * <li>UNUM_DECIMAL_SEPARATOR_ALWAYS: "1.", "1.1"
jpayne@69 369 * </ul>
jpayne@69 370 *
jpayne@69 371 * @stable ICU 60
jpayne@69 372 */
jpayne@69 373 typedef enum UNumberDecimalSeparatorDisplay {
jpayne@69 374 /**
jpayne@69 375 * Show the decimal separator when there are one or more digits to display after the separator, and do not show
jpayne@69 376 * it otherwise. This is the default behavior.
jpayne@69 377 *
jpayne@69 378 * @stable ICU 60
jpayne@69 379 */
jpayne@69 380 UNUM_DECIMAL_SEPARATOR_AUTO,
jpayne@69 381
jpayne@69 382 /**
jpayne@69 383 * Always show the decimal separator, even if there are no digits to display after the separator.
jpayne@69 384 *
jpayne@69 385 * @stable ICU 60
jpayne@69 386 */
jpayne@69 387 UNUM_DECIMAL_SEPARATOR_ALWAYS,
jpayne@69 388
jpayne@69 389 /**
jpayne@69 390 * One more than the highest UNumberDecimalSeparatorDisplay value.
jpayne@69 391 *
jpayne@69 392 * @internal ICU 60: The numeric value may change over time; see ICU ticket #12420.
jpayne@69 393 */
jpayne@69 394 UNUM_DECIMAL_SEPARATOR_COUNT
jpayne@69 395 } UNumberDecimalSeparatorDisplay;
jpayne@69 396
jpayne@69 397 struct UNumberFormatter;
jpayne@69 398 /**
jpayne@69 399 * C-compatible version of icu::number::LocalizedNumberFormatter.
jpayne@69 400 *
jpayne@69 401 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
jpayne@69 402 *
jpayne@69 403 * @stable ICU 62
jpayne@69 404 */
jpayne@69 405 typedef struct UNumberFormatter UNumberFormatter;
jpayne@69 406
jpayne@69 407 struct UFormattedNumber;
jpayne@69 408 /**
jpayne@69 409 * C-compatible version of icu::number::FormattedNumber.
jpayne@69 410 *
jpayne@69 411 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
jpayne@69 412 *
jpayne@69 413 * @stable ICU 62
jpayne@69 414 */
jpayne@69 415 typedef struct UFormattedNumber UFormattedNumber;
jpayne@69 416
jpayne@69 417
jpayne@69 418 /**
jpayne@69 419 * Creates a new UNumberFormatter for the given skeleton string and locale. This is currently the only
jpayne@69 420 * method for creating a new UNumberFormatter.
jpayne@69 421 *
jpayne@69 422 * Objects of type UNumberFormatter returned by this method are threadsafe.
jpayne@69 423 *
jpayne@69 424 * For more details on skeleton strings, see the documentation in numberformatter.h. For more details on
jpayne@69 425 * the usage of this API, see the documentation at the top of unumberformatter.h.
jpayne@69 426 *
jpayne@69 427 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
jpayne@69 428 *
jpayne@69 429 * @param skeleton The skeleton string, like u"percent precision-integer"
jpayne@69 430 * @param skeletonLen The number of UChars in the skeleton string, or -1 if it is NUL-terminated.
jpayne@69 431 * @param locale The NUL-terminated locale ID.
jpayne@69 432 * @param ec Set if an error occurs.
jpayne@69 433 * @stable ICU 62
jpayne@69 434 */
jpayne@69 435 U_STABLE UNumberFormatter* U_EXPORT2
jpayne@69 436 unumf_openForSkeletonAndLocale(const UChar* skeleton, int32_t skeletonLen, const char* locale,
jpayne@69 437 UErrorCode* ec);
jpayne@69 438
jpayne@69 439
jpayne@69 440 /**
jpayne@69 441 * Like unumf_openForSkeletonAndLocale, but accepts a UParseError, which will be populated with the
jpayne@69 442 * location of a skeleton syntax error if such a syntax error exists.
jpayne@69 443 *
jpayne@69 444 * @param skeleton The skeleton string, like u"percent precision-integer"
jpayne@69 445 * @param skeletonLen The number of UChars in the skeleton string, or -1 if it is NUL-terminated.
jpayne@69 446 * @param locale The NUL-terminated locale ID.
jpayne@69 447 * @param perror A parse error struct populated if an error occurs when parsing. Can be NULL.
jpayne@69 448 * If no error occurs, perror->offset will be set to -1.
jpayne@69 449 * @param ec Set if an error occurs.
jpayne@69 450 * @stable ICU 64
jpayne@69 451 */
jpayne@69 452 U_STABLE UNumberFormatter* U_EXPORT2
jpayne@69 453 unumf_openForSkeletonAndLocaleWithError(
jpayne@69 454 const UChar* skeleton, int32_t skeletonLen, const char* locale, UParseError* perror, UErrorCode* ec);
jpayne@69 455
jpayne@69 456
jpayne@69 457 /**
jpayne@69 458 * Creates an object to hold the result of a UNumberFormatter
jpayne@69 459 * operation. The object can be used repeatedly; it is cleared whenever
jpayne@69 460 * passed to a format function.
jpayne@69 461 *
jpayne@69 462 * @param ec Set if an error occurs.
jpayne@69 463 * @stable ICU 62
jpayne@69 464 */
jpayne@69 465 U_STABLE UFormattedNumber* U_EXPORT2
jpayne@69 466 unumf_openResult(UErrorCode* ec);
jpayne@69 467
jpayne@69 468
jpayne@69 469 /**
jpayne@69 470 * Uses a UNumberFormatter to format an integer to a UFormattedNumber. A string, field position, and other
jpayne@69 471 * information can be retrieved from the UFormattedNumber.
jpayne@69 472 *
jpayne@69 473 * The UNumberFormatter can be shared between threads. Each thread should have its own local
jpayne@69 474 * UFormattedNumber, however, for storing the result of the formatting operation.
jpayne@69 475 *
jpayne@69 476 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
jpayne@69 477 *
jpayne@69 478 * @param uformatter A formatter object created by unumf_openForSkeletonAndLocale or similar.
jpayne@69 479 * @param value The number to be formatted.
jpayne@69 480 * @param uresult The object that will be mutated to store the result; see unumf_openResult.
jpayne@69 481 * @param ec Set if an error occurs.
jpayne@69 482 * @stable ICU 62
jpayne@69 483 */
jpayne@69 484 U_STABLE void U_EXPORT2
jpayne@69 485 unumf_formatInt(const UNumberFormatter* uformatter, int64_t value, UFormattedNumber* uresult,
jpayne@69 486 UErrorCode* ec);
jpayne@69 487
jpayne@69 488
jpayne@69 489 /**
jpayne@69 490 * Uses a UNumberFormatter to format a double to a UFormattedNumber. A string, field position, and other
jpayne@69 491 * information can be retrieved from the UFormattedNumber.
jpayne@69 492 *
jpayne@69 493 * The UNumberFormatter can be shared between threads. Each thread should have its own local
jpayne@69 494 * UFormattedNumber, however, for storing the result of the formatting operation.
jpayne@69 495 *
jpayne@69 496 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
jpayne@69 497 *
jpayne@69 498 * @param uformatter A formatter object created by unumf_openForSkeletonAndLocale or similar.
jpayne@69 499 * @param value The number to be formatted.
jpayne@69 500 * @param uresult The object that will be mutated to store the result; see unumf_openResult.
jpayne@69 501 * @param ec Set if an error occurs.
jpayne@69 502 * @stable ICU 62
jpayne@69 503 */
jpayne@69 504 U_STABLE void U_EXPORT2
jpayne@69 505 unumf_formatDouble(const UNumberFormatter* uformatter, double value, UFormattedNumber* uresult,
jpayne@69 506 UErrorCode* ec);
jpayne@69 507
jpayne@69 508
jpayne@69 509 /**
jpayne@69 510 * Uses a UNumberFormatter to format a decimal number to a UFormattedNumber. A string, field position, and
jpayne@69 511 * other information can be retrieved from the UFormattedNumber.
jpayne@69 512 *
jpayne@69 513 * The UNumberFormatter can be shared between threads. Each thread should have its own local
jpayne@69 514 * UFormattedNumber, however, for storing the result of the formatting operation.
jpayne@69 515 *
jpayne@69 516 * The syntax of the unformatted number is a "numeric string" as defined in the Decimal Arithmetic
jpayne@69 517 * Specification, available at http://speleotrove.com/decimal
jpayne@69 518 *
jpayne@69 519 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
jpayne@69 520 *
jpayne@69 521 * @param uformatter A formatter object created by unumf_openForSkeletonAndLocale or similar.
jpayne@69 522 * @param value The numeric string to be formatted.
jpayne@69 523 * @param valueLen The length of the numeric string, or -1 if it is NUL-terminated.
jpayne@69 524 * @param uresult The object that will be mutated to store the result; see unumf_openResult.
jpayne@69 525 * @param ec Set if an error occurs.
jpayne@69 526 * @stable ICU 62
jpayne@69 527 */
jpayne@69 528 U_STABLE void U_EXPORT2
jpayne@69 529 unumf_formatDecimal(const UNumberFormatter* uformatter, const char* value, int32_t valueLen,
jpayne@69 530 UFormattedNumber* uresult, UErrorCode* ec);
jpayne@69 531
jpayne@69 532 /**
jpayne@69 533 * Returns a representation of a UFormattedNumber as a UFormattedValue,
jpayne@69 534 * which can be subsequently passed to any API requiring that type.
jpayne@69 535 *
jpayne@69 536 * The returned object is owned by the UFormattedNumber and is valid
jpayne@69 537 * only as long as the UFormattedNumber is present and unchanged in memory.
jpayne@69 538 *
jpayne@69 539 * You can think of this method as a cast between types.
jpayne@69 540 *
jpayne@69 541 * @param uresult The object containing the formatted string.
jpayne@69 542 * @param ec Set if an error occurs.
jpayne@69 543 * @return A UFormattedValue owned by the input object.
jpayne@69 544 * @stable ICU 64
jpayne@69 545 */
jpayne@69 546 U_STABLE const UFormattedValue* U_EXPORT2
jpayne@69 547 unumf_resultAsValue(const UFormattedNumber* uresult, UErrorCode* ec);
jpayne@69 548
jpayne@69 549
jpayne@69 550 /**
jpayne@69 551 * Extracts the result number string out of a UFormattedNumber to a UChar buffer if possible.
jpayne@69 552 * If bufferCapacity is greater than the required length, a terminating NUL is written.
jpayne@69 553 * If bufferCapacity is less than the required length, an error code is set.
jpayne@69 554 *
jpayne@69 555 * Also see ufmtval_getString, which returns a NUL-terminated string:
jpayne@69 556 *
jpayne@69 557 * int32_t len;
jpayne@69 558 * const UChar* str = ufmtval_getString(unumf_resultAsValue(uresult, &ec), &len, &ec);
jpayne@69 559 *
jpayne@69 560 * NOTE: This is a C-compatible API; C++ users should build against numberformatter.h instead.
jpayne@69 561 *
jpayne@69 562 * @param uresult The object containing the formatted number.
jpayne@69 563 * @param buffer Where to save the string output.
jpayne@69 564 * @param bufferCapacity The number of UChars available in the buffer.
jpayne@69 565 * @param ec Set if an error occurs.
jpayne@69 566 * @return The required length.
jpayne@69 567 * @stable ICU 62
jpayne@69 568 */
jpayne@69 569 U_STABLE int32_t U_EXPORT2
jpayne@69 570 unumf_resultToString(const UFormattedNumber* uresult, UChar* buffer, int32_t bufferCapacity,
jpayne@69 571 UErrorCode* ec);
jpayne@69 572
jpayne@69 573
jpayne@69 574 /**
jpayne@69 575 * Determines the start and end indices of the next occurrence of the given <em>field</em> in the
jpayne@69 576 * output string. This allows you to determine the locations of, for example, the integer part,
jpayne@69 577 * fraction part, or symbols.
jpayne@69 578 *
jpayne@69 579 * This is a simpler but less powerful alternative to {@link ufmtval_nextPosition}.
jpayne@69 580 *
jpayne@69 581 * If a field occurs just once, calling this method will find that occurrence and return it. If a
jpayne@69 582 * field occurs multiple times, this method may be called repeatedly with the following pattern:
jpayne@69 583 *
jpayne@69 584 * <pre>
jpayne@69 585 * UFieldPosition ufpos = {UNUM_GROUPING_SEPARATOR_FIELD, 0, 0};
jpayne@69 586 * while (unumf_resultNextFieldPosition(uresult, ufpos, &ec)) {
jpayne@69 587 * // do something with ufpos.
jpayne@69 588 * }
jpayne@69 589 * </pre>
jpayne@69 590 *
jpayne@69 591 * This method is useful if you know which field to query. If you want all available field position
jpayne@69 592 * information, use unumf_resultGetAllFieldPositions().
jpayne@69 593 *
jpayne@69 594 * NOTE: All fields of the UFieldPosition must be initialized before calling this method.
jpayne@69 595 *
jpayne@69 596 * @param uresult The object containing the formatted number.
jpayne@69 597 * @param ufpos
jpayne@69 598 * Input+output variable. On input, the "field" property determines which field to look up,
jpayne@69 599 * and the "endIndex" property determines where to begin the search. On output, the
jpayne@69 600 * "beginIndex" field is set to the beginning of the first occurrence of the field after the
jpayne@69 601 * input "endIndex", and "endIndex" is set to the end of that occurrence of the field
jpayne@69 602 * (exclusive index). If a field position is not found, the FieldPosition is not changed and
jpayne@69 603 * the method returns FALSE.
jpayne@69 604 * @param ec Set if an error occurs.
jpayne@69 605 * @stable ICU 62
jpayne@69 606 */
jpayne@69 607 U_STABLE UBool U_EXPORT2
jpayne@69 608 unumf_resultNextFieldPosition(const UFormattedNumber* uresult, UFieldPosition* ufpos, UErrorCode* ec);
jpayne@69 609
jpayne@69 610
jpayne@69 611 /**
jpayne@69 612 * Populates the given iterator with all fields in the formatted output string. This allows you to
jpayne@69 613 * determine the locations of the integer part, fraction part, and sign.
jpayne@69 614 *
jpayne@69 615 * This is an alternative to the more powerful {@link ufmtval_nextPosition} API.
jpayne@69 616 *
jpayne@69 617 * If you need information on only one field, use {@link ufmtval_nextPosition} or
jpayne@69 618 * {@link unumf_resultNextFieldPosition}.
jpayne@69 619 *
jpayne@69 620 * @param uresult The object containing the formatted number.
jpayne@69 621 * @param ufpositer
jpayne@69 622 * A pointer to a UFieldPositionIterator created by {@link #ufieldpositer_open}. Iteration
jpayne@69 623 * information already present in the UFieldPositionIterator is deleted, and the iterator is reset
jpayne@69 624 * to apply to the fields in the formatted string created by this function call. The field values
jpayne@69 625 * and indexes returned by {@link #ufieldpositer_next} represent fields denoted by
jpayne@69 626 * the UNumberFormatFields enum. Fields are not returned in a guaranteed order. Fields cannot
jpayne@69 627 * overlap, but they may nest. For example, 1234 could format as "1,234" which might consist of a
jpayne@69 628 * grouping separator field for ',' and an integer field encompassing the entire string.
jpayne@69 629 * @param ec Set if an error occurs.
jpayne@69 630 * @stable ICU 62
jpayne@69 631 */
jpayne@69 632 U_STABLE void U_EXPORT2
jpayne@69 633 unumf_resultGetAllFieldPositions(const UFormattedNumber* uresult, UFieldPositionIterator* ufpositer,
jpayne@69 634 UErrorCode* ec);
jpayne@69 635
jpayne@69 636
jpayne@69 637 // TODO(ICU-20775): Propose this as API.
jpayne@69 638 // NOTE: This is not currently implemented.
jpayne@69 639 // U_DRAFT int32_t U_EXPORT2
jpayne@69 640 // unumf_resultToDecimalNumber(const UFormattedNumber* uresult, char* buffer, int32_t bufferCapacity,
jpayne@69 641 // UErrorCode* ec);
jpayne@69 642
jpayne@69 643
jpayne@69 644 /**
jpayne@69 645 * Releases the UNumberFormatter created by unumf_openForSkeletonAndLocale().
jpayne@69 646 *
jpayne@69 647 * @param uformatter An object created by unumf_openForSkeletonAndLocale().
jpayne@69 648 * @stable ICU 62
jpayne@69 649 */
jpayne@69 650 U_STABLE void U_EXPORT2
jpayne@69 651 unumf_close(UNumberFormatter* uformatter);
jpayne@69 652
jpayne@69 653
jpayne@69 654 /**
jpayne@69 655 * Releases the UFormattedNumber created by unumf_openResult().
jpayne@69 656 *
jpayne@69 657 * @param uresult An object created by unumf_openResult().
jpayne@69 658 * @stable ICU 62
jpayne@69 659 */
jpayne@69 660 U_STABLE void U_EXPORT2
jpayne@69 661 unumf_closeResult(UFormattedNumber* uresult);
jpayne@69 662
jpayne@69 663
jpayne@69 664 #if U_SHOW_CPLUSPLUS_API
jpayne@69 665 U_NAMESPACE_BEGIN
jpayne@69 666
jpayne@69 667 /**
jpayne@69 668 * \class LocalUNumberFormatterPointer
jpayne@69 669 * "Smart pointer" class; closes a UNumberFormatter via unumf_close().
jpayne@69 670 * For most methods see the LocalPointerBase base class.
jpayne@69 671 *
jpayne@69 672 * Usage:
jpayne@69 673 * <pre>
jpayne@69 674 * LocalUNumberFormatterPointer uformatter(unumf_openForSkeletonAndLocale(...));
jpayne@69 675 * // no need to explicitly call unumf_close()
jpayne@69 676 * </pre>
jpayne@69 677 *
jpayne@69 678 * @see LocalPointerBase
jpayne@69 679 * @see LocalPointer
jpayne@69 680 * @stable ICU 62
jpayne@69 681 */
jpayne@69 682 U_DEFINE_LOCAL_OPEN_POINTER(LocalUNumberFormatterPointer, UNumberFormatter, unumf_close);
jpayne@69 683
jpayne@69 684 /**
jpayne@69 685 * \class LocalUFormattedNumberPointer
jpayne@69 686 * "Smart pointer" class; closes a UFormattedNumber via unumf_closeResult().
jpayne@69 687 * For most methods see the LocalPointerBase base class.
jpayne@69 688 *
jpayne@69 689 * Usage:
jpayne@69 690 * <pre>
jpayne@69 691 * LocalUFormattedNumberPointer uformatter(unumf_openResult(...));
jpayne@69 692 * // no need to explicitly call unumf_closeResult()
jpayne@69 693 * </pre>
jpayne@69 694 *
jpayne@69 695 * @see LocalPointerBase
jpayne@69 696 * @see LocalPointer
jpayne@69 697 * @stable ICU 62
jpayne@69 698 */
jpayne@69 699 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedNumberPointer, UFormattedNumber, unumf_closeResult);
jpayne@69 700
jpayne@69 701 U_NAMESPACE_END
jpayne@69 702 #endif // U_SHOW_CPLUSPLUS_API
jpayne@69 703
jpayne@69 704 #endif //__UNUMBERFORMATTER_H__
jpayne@69 705 #endif /* #if !UCONFIG_NO_FORMATTING */