Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/numberformatter.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 // © 2017 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 #ifndef __NUMBERFORMATTER_H__
jpayne@69 5 #define __NUMBERFORMATTER_H__
jpayne@69 6
jpayne@69 7 #include "unicode/utypes.h"
jpayne@69 8
jpayne@69 9 #if U_SHOW_CPLUSPLUS_API
jpayne@69 10
jpayne@69 11 #if !UCONFIG_NO_FORMATTING
jpayne@69 12
jpayne@69 13 #include "unicode/appendable.h"
jpayne@69 14 #include "unicode/bytestream.h"
jpayne@69 15 #include "unicode/currunit.h"
jpayne@69 16 #include "unicode/dcfmtsym.h"
jpayne@69 17 #include "unicode/fieldpos.h"
jpayne@69 18 #include "unicode/formattedvalue.h"
jpayne@69 19 #include "unicode/fpositer.h"
jpayne@69 20 #include "unicode/measunit.h"
jpayne@69 21 #include "unicode/nounit.h"
jpayne@69 22 #include "unicode/parseerr.h"
jpayne@69 23 #include "unicode/plurrule.h"
jpayne@69 24 #include "unicode/ucurr.h"
jpayne@69 25 #include "unicode/unum.h"
jpayne@69 26 #include "unicode/unumberformatter.h"
jpayne@69 27 #include "unicode/uobject.h"
jpayne@69 28
jpayne@69 29 /**
jpayne@69 30 * \file
jpayne@69 31 * \brief C++ API: Library for localized number formatting introduced in ICU 60.
jpayne@69 32 *
jpayne@69 33 * This library was introduced in ICU 60 to simplify the process of formatting localized number strings.
jpayne@69 34 * Basic usage examples:
jpayne@69 35 *
jpayne@69 36 * <pre>
jpayne@69 37 * // Most basic usage:
jpayne@69 38 * NumberFormatter::withLocale(...).format(123).toString(); // 1,234 in en-US
jpayne@69 39 *
jpayne@69 40 * // Custom notation, unit, and rounding precision:
jpayne@69 41 * NumberFormatter::with()
jpayne@69 42 * .notation(Notation::compactShort())
jpayne@69 43 * .unit(CurrencyUnit("EUR", status))
jpayne@69 44 * .precision(Precision::maxDigits(2))
jpayne@69 45 * .locale(...)
jpayne@69 46 * .format(1234)
jpayne@69 47 * .toString(); // €1.2K in en-US
jpayne@69 48 *
jpayne@69 49 * // Create a formatter in a singleton by value for use later:
jpayne@69 50 * static const LocalizedNumberFormatter formatter = NumberFormatter::withLocale(...)
jpayne@69 51 * .unit(NoUnit::percent())
jpayne@69 52 * .precision(Precision::fixedFraction(3));
jpayne@69 53 * formatter.format(5.9831).toString(); // 5.983% in en-US
jpayne@69 54 *
jpayne@69 55 * // Create a "template" in a singleton unique_ptr but without setting a locale until the call site:
jpayne@69 56 * std::unique_ptr<UnlocalizedNumberFormatter> template = NumberFormatter::with()
jpayne@69 57 * .sign(UNumberSignDisplay::UNUM_SIGN_ALWAYS)
jpayne@69 58 * .unit(MeasureUnit::getMeter())
jpayne@69 59 * .unitWidth(UNumberUnitWidth::UNUM_UNIT_WIDTH_FULL_NAME)
jpayne@69 60 * .clone();
jpayne@69 61 * template->locale(...).format(1234).toString(); // +1,234 meters in en-US
jpayne@69 62 * </pre>
jpayne@69 63 *
jpayne@69 64 * <p>
jpayne@69 65 * This API offers more features than DecimalFormat and is geared toward new users of ICU.
jpayne@69 66 *
jpayne@69 67 * <p>
jpayne@69 68 * NumberFormatter instances (i.e., LocalizedNumberFormatter and UnlocalizedNumberFormatter)
jpayne@69 69 * are immutable and thread safe. This means that invoking a configuration method has no
jpayne@69 70 * effect on the receiving instance; you must store and use the new number formatter instance it returns instead.
jpayne@69 71 *
jpayne@69 72 * <pre>
jpayne@69 73 * UnlocalizedNumberFormatter formatter = UnlocalizedNumberFormatter::with().notation(Notation::scientific());
jpayne@69 74 * formatter.precision(Precision.maxFraction(2)); // does nothing!
jpayne@69 75 * formatter.locale(Locale.getEnglish()).format(9.8765).toString(); // prints "9.8765E0", not "9.88E0"
jpayne@69 76 * </pre>
jpayne@69 77 *
jpayne@69 78 * <p>
jpayne@69 79 * This API is based on the <em>fluent</em> design pattern popularized by libraries such as Google's Guava. For
jpayne@69 80 * extensive details on the design of this API, read <a href="https://goo.gl/szi5VB">the design doc</a>.
jpayne@69 81 *
jpayne@69 82 * @author Shane Carr
jpayne@69 83 */
jpayne@69 84
jpayne@69 85 U_NAMESPACE_BEGIN
jpayne@69 86
jpayne@69 87 // Forward declarations:
jpayne@69 88 class IFixedDecimal;
jpayne@69 89 class FieldPositionIteratorHandler;
jpayne@69 90 class FormattedStringBuilder;
jpayne@69 91
jpayne@69 92 namespace numparse {
jpayne@69 93 namespace impl {
jpayne@69 94
jpayne@69 95 // Forward declarations:
jpayne@69 96 class NumberParserImpl;
jpayne@69 97 class MultiplierParseHandler;
jpayne@69 98
jpayne@69 99 }
jpayne@69 100 }
jpayne@69 101
jpayne@69 102 namespace number { // icu::number
jpayne@69 103
jpayne@69 104 // Forward declarations:
jpayne@69 105 class UnlocalizedNumberFormatter;
jpayne@69 106 class LocalizedNumberFormatter;
jpayne@69 107 class FormattedNumber;
jpayne@69 108 class Notation;
jpayne@69 109 class ScientificNotation;
jpayne@69 110 class Precision;
jpayne@69 111 class FractionPrecision;
jpayne@69 112 class CurrencyPrecision;
jpayne@69 113 class IncrementPrecision;
jpayne@69 114 class IntegerWidth;
jpayne@69 115
jpayne@69 116 namespace impl {
jpayne@69 117
jpayne@69 118 // can't be #ifndef U_HIDE_INTERNAL_API; referenced throughout this file in public classes
jpayne@69 119 /**
jpayne@69 120 * Datatype for minimum/maximum fraction digits. Must be able to hold kMaxIntFracSig.
jpayne@69 121 *
jpayne@69 122 * @internal
jpayne@69 123 */
jpayne@69 124 typedef int16_t digits_t;
jpayne@69 125
jpayne@69 126 // can't be #ifndef U_HIDE_INTERNAL_API; needed for struct initialization
jpayne@69 127 /**
jpayne@69 128 * Use a default threshold of 3. This means that the third time .format() is called, the data structures get built
jpayne@69 129 * using the "safe" code path. The first two calls to .format() will trigger the unsafe code path.
jpayne@69 130 *
jpayne@69 131 * @internal
jpayne@69 132 */
jpayne@69 133 static constexpr int32_t kInternalDefaultThreshold = 3;
jpayne@69 134
jpayne@69 135 // Forward declarations:
jpayne@69 136 class Padder;
jpayne@69 137 struct MacroProps;
jpayne@69 138 struct MicroProps;
jpayne@69 139 class DecimalQuantity;
jpayne@69 140 class UFormattedNumberData;
jpayne@69 141 class NumberFormatterImpl;
jpayne@69 142 struct ParsedPatternInfo;
jpayne@69 143 class ScientificModifier;
jpayne@69 144 class MultiplierProducer;
jpayne@69 145 class RoundingImpl;
jpayne@69 146 class ScientificHandler;
jpayne@69 147 class Modifier;
jpayne@69 148 class AffixPatternProvider;
jpayne@69 149 class NumberPropertyMapper;
jpayne@69 150 struct DecimalFormatProperties;
jpayne@69 151 class MultiplierFormatHandler;
jpayne@69 152 class CurrencySymbols;
jpayne@69 153 class GeneratorHelpers;
jpayne@69 154 class DecNum;
jpayne@69 155 class NumberRangeFormatterImpl;
jpayne@69 156 struct RangeMacroProps;
jpayne@69 157 struct UFormattedNumberImpl;
jpayne@69 158 class MutablePatternModifier;
jpayne@69 159 class ImmutablePatternModifier;
jpayne@69 160
jpayne@69 161 /**
jpayne@69 162 * Used for NumberRangeFormatter and implemented in numrange_fluent.cpp.
jpayne@69 163 * Declared here so it can be friended.
jpayne@69 164 *
jpayne@69 165 * @internal
jpayne@69 166 */
jpayne@69 167 void touchRangeLocales(impl::RangeMacroProps& macros);
jpayne@69 168
jpayne@69 169 } // namespace impl
jpayne@69 170
jpayne@69 171 /**
jpayne@69 172 * Extra name reserved in case it is needed in the future.
jpayne@69 173 *
jpayne@69 174 * @stable ICU 63
jpayne@69 175 */
jpayne@69 176 typedef Notation CompactNotation;
jpayne@69 177
jpayne@69 178 /**
jpayne@69 179 * Extra name reserved in case it is needed in the future.
jpayne@69 180 *
jpayne@69 181 * @stable ICU 63
jpayne@69 182 */
jpayne@69 183 typedef Notation SimpleNotation;
jpayne@69 184
jpayne@69 185 /**
jpayne@69 186 * A class that defines the notation style to be used when formatting numbers in NumberFormatter.
jpayne@69 187 *
jpayne@69 188 * @stable ICU 60
jpayne@69 189 */
jpayne@69 190 class U_I18N_API Notation : public UMemory {
jpayne@69 191 public:
jpayne@69 192 /**
jpayne@69 193 * Print the number using scientific notation (also known as scientific form, standard index form, or standard form
jpayne@69 194 * in the UK). The format for scientific notation varies by locale; for example, many Western locales display the
jpayne@69 195 * number in the form "#E0", where the number is displayed with one digit before the decimal separator, zero or more
jpayne@69 196 * digits after the decimal separator, and the corresponding power of 10 displayed after the "E".
jpayne@69 197 *
jpayne@69 198 * <p>
jpayne@69 199 * Example outputs in <em>en-US</em> when printing 8.765E4 through 8.765E-3:
jpayne@69 200 *
jpayne@69 201 * <pre>
jpayne@69 202 * 8.765E4
jpayne@69 203 * 8.765E3
jpayne@69 204 * 8.765E2
jpayne@69 205 * 8.765E1
jpayne@69 206 * 8.765E0
jpayne@69 207 * 8.765E-1
jpayne@69 208 * 8.765E-2
jpayne@69 209 * 8.765E-3
jpayne@69 210 * 0E0
jpayne@69 211 * </pre>
jpayne@69 212 *
jpayne@69 213 * @return A ScientificNotation for chaining or passing to the NumberFormatter notation() setter.
jpayne@69 214 * @stable ICU 60
jpayne@69 215 */
jpayne@69 216 static ScientificNotation scientific();
jpayne@69 217
jpayne@69 218 /**
jpayne@69 219 * Print the number using engineering notation, a variant of scientific notation in which the exponent must be
jpayne@69 220 * divisible by 3.
jpayne@69 221 *
jpayne@69 222 * <p>
jpayne@69 223 * Example outputs in <em>en-US</em> when printing 8.765E4 through 8.765E-3:
jpayne@69 224 *
jpayne@69 225 * <pre>
jpayne@69 226 * 87.65E3
jpayne@69 227 * 8.765E3
jpayne@69 228 * 876.5E0
jpayne@69 229 * 87.65E0
jpayne@69 230 * 8.765E0
jpayne@69 231 * 876.5E-3
jpayne@69 232 * 87.65E-3
jpayne@69 233 * 8.765E-3
jpayne@69 234 * 0E0
jpayne@69 235 * </pre>
jpayne@69 236 *
jpayne@69 237 * @return A ScientificNotation for chaining or passing to the NumberFormatter notation() setter.
jpayne@69 238 * @stable ICU 60
jpayne@69 239 */
jpayne@69 240 static ScientificNotation engineering();
jpayne@69 241
jpayne@69 242 /**
jpayne@69 243 * Print the number using short-form compact notation.
jpayne@69 244 *
jpayne@69 245 * <p>
jpayne@69 246 * <em>Compact notation</em>, defined in Unicode Technical Standard #35 Part 3 Section 2.4.1, prints numbers with
jpayne@69 247 * localized prefixes or suffixes corresponding to different powers of ten. Compact notation is similar to
jpayne@69 248 * engineering notation in how it scales numbers.
jpayne@69 249 *
jpayne@69 250 * <p>
jpayne@69 251 * Compact notation is ideal for displaying large numbers (over ~1000) to humans while at the same time minimizing
jpayne@69 252 * screen real estate.
jpayne@69 253 *
jpayne@69 254 * <p>
jpayne@69 255 * In short form, the powers of ten are abbreviated. In <em>en-US</em>, the abbreviations are "K" for thousands, "M"
jpayne@69 256 * for millions, "B" for billions, and "T" for trillions. Example outputs in <em>en-US</em> when printing 8.765E7
jpayne@69 257 * through 8.765E0:
jpayne@69 258 *
jpayne@69 259 * <pre>
jpayne@69 260 * 88M
jpayne@69 261 * 8.8M
jpayne@69 262 * 876K
jpayne@69 263 * 88K
jpayne@69 264 * 8.8K
jpayne@69 265 * 876
jpayne@69 266 * 88
jpayne@69 267 * 8.8
jpayne@69 268 * </pre>
jpayne@69 269 *
jpayne@69 270 * <p>
jpayne@69 271 * When compact notation is specified without an explicit rounding precision, numbers are rounded off to the closest
jpayne@69 272 * integer after scaling the number by the corresponding power of 10, but with a digit shown after the decimal
jpayne@69 273 * separator if there is only one digit before the decimal separator. The default compact notation rounding precision
jpayne@69 274 * is equivalent to:
jpayne@69 275 *
jpayne@69 276 * <pre>
jpayne@69 277 * Precision::integer().withMinDigits(2)
jpayne@69 278 * </pre>
jpayne@69 279 *
jpayne@69 280 * @return A CompactNotation for passing to the NumberFormatter notation() setter.
jpayne@69 281 * @stable ICU 60
jpayne@69 282 */
jpayne@69 283 static CompactNotation compactShort();
jpayne@69 284
jpayne@69 285 /**
jpayne@69 286 * Print the number using long-form compact notation. For more information on compact notation, see
jpayne@69 287 * {@link #compactShort}.
jpayne@69 288 *
jpayne@69 289 * <p>
jpayne@69 290 * In long form, the powers of ten are spelled out fully. Example outputs in <em>en-US</em> when printing 8.765E7
jpayne@69 291 * through 8.765E0:
jpayne@69 292 *
jpayne@69 293 * <pre>
jpayne@69 294 * 88 million
jpayne@69 295 * 8.8 million
jpayne@69 296 * 876 thousand
jpayne@69 297 * 88 thousand
jpayne@69 298 * 8.8 thousand
jpayne@69 299 * 876
jpayne@69 300 * 88
jpayne@69 301 * 8.8
jpayne@69 302 * </pre>
jpayne@69 303 *
jpayne@69 304 * @return A CompactNotation for passing to the NumberFormatter notation() setter.
jpayne@69 305 * @stable ICU 60
jpayne@69 306 */
jpayne@69 307 static CompactNotation compactLong();
jpayne@69 308
jpayne@69 309 /**
jpayne@69 310 * Print the number using simple notation without any scaling by powers of ten. This is the default behavior.
jpayne@69 311 *
jpayne@69 312 * <p>
jpayne@69 313 * Since this is the default behavior, this method needs to be called only when it is necessary to override a
jpayne@69 314 * previous setting.
jpayne@69 315 *
jpayne@69 316 * <p>
jpayne@69 317 * Example outputs in <em>en-US</em> when printing 8.765E7 through 8.765E0:
jpayne@69 318 *
jpayne@69 319 * <pre>
jpayne@69 320 * 87,650,000
jpayne@69 321 * 8,765,000
jpayne@69 322 * 876,500
jpayne@69 323 * 87,650
jpayne@69 324 * 8,765
jpayne@69 325 * 876.5
jpayne@69 326 * 87.65
jpayne@69 327 * 8.765
jpayne@69 328 * </pre>
jpayne@69 329 *
jpayne@69 330 * @return A SimpleNotation for passing to the NumberFormatter notation() setter.
jpayne@69 331 * @stable ICU 60
jpayne@69 332 */
jpayne@69 333 static SimpleNotation simple();
jpayne@69 334
jpayne@69 335 private:
jpayne@69 336 enum NotationType {
jpayne@69 337 NTN_SCIENTIFIC, NTN_COMPACT, NTN_SIMPLE, NTN_ERROR
jpayne@69 338 } fType;
jpayne@69 339
jpayne@69 340 union NotationUnion {
jpayne@69 341 // For NTN_SCIENTIFIC
jpayne@69 342 /** @internal */
jpayne@69 343 struct ScientificSettings {
jpayne@69 344 /** @internal */
jpayne@69 345 int8_t fEngineeringInterval;
jpayne@69 346 /** @internal */
jpayne@69 347 bool fRequireMinInt;
jpayne@69 348 /** @internal */
jpayne@69 349 impl::digits_t fMinExponentDigits;
jpayne@69 350 /** @internal */
jpayne@69 351 UNumberSignDisplay fExponentSignDisplay;
jpayne@69 352 } scientific;
jpayne@69 353
jpayne@69 354 // For NTN_COMPACT
jpayne@69 355 UNumberCompactStyle compactStyle;
jpayne@69 356
jpayne@69 357 // For NTN_ERROR
jpayne@69 358 UErrorCode errorCode;
jpayne@69 359 } fUnion;
jpayne@69 360
jpayne@69 361 typedef NotationUnion::ScientificSettings ScientificSettings;
jpayne@69 362
jpayne@69 363 Notation(const NotationType &type, const NotationUnion &union_) : fType(type), fUnion(union_) {}
jpayne@69 364
jpayne@69 365 Notation(UErrorCode errorCode) : fType(NTN_ERROR) {
jpayne@69 366 fUnion.errorCode = errorCode;
jpayne@69 367 }
jpayne@69 368
jpayne@69 369 Notation() : fType(NTN_SIMPLE), fUnion() {}
jpayne@69 370
jpayne@69 371 UBool copyErrorTo(UErrorCode &status) const {
jpayne@69 372 if (fType == NTN_ERROR) {
jpayne@69 373 status = fUnion.errorCode;
jpayne@69 374 return TRUE;
jpayne@69 375 }
jpayne@69 376 return FALSE;
jpayne@69 377 }
jpayne@69 378
jpayne@69 379 // To allow MacroProps to initialize empty instances:
jpayne@69 380 friend struct impl::MacroProps;
jpayne@69 381 friend class ScientificNotation;
jpayne@69 382
jpayne@69 383 // To allow implementation to access internal types:
jpayne@69 384 friend class impl::NumberFormatterImpl;
jpayne@69 385 friend class impl::ScientificModifier;
jpayne@69 386 friend class impl::ScientificHandler;
jpayne@69 387
jpayne@69 388 // To allow access to the skeleton generation code:
jpayne@69 389 friend class impl::GeneratorHelpers;
jpayne@69 390 };
jpayne@69 391
jpayne@69 392 /**
jpayne@69 393 * A class that defines the scientific notation style to be used when formatting numbers in NumberFormatter.
jpayne@69 394 *
jpayne@69 395 * <p>
jpayne@69 396 * To create a ScientificNotation, use one of the factory methods in {@link Notation}.
jpayne@69 397 *
jpayne@69 398 * @stable ICU 60
jpayne@69 399 */
jpayne@69 400 class U_I18N_API ScientificNotation : public Notation {
jpayne@69 401 public:
jpayne@69 402 /**
jpayne@69 403 * Sets the minimum number of digits to show in the exponent of scientific notation, padding with zeros if
jpayne@69 404 * necessary. Useful for fixed-width display.
jpayne@69 405 *
jpayne@69 406 * <p>
jpayne@69 407 * For example, with minExponentDigits=2, the number 123 will be printed as "1.23E02" in <em>en-US</em> instead of
jpayne@69 408 * the default "1.23E2".
jpayne@69 409 *
jpayne@69 410 * @param minExponentDigits
jpayne@69 411 * The minimum number of digits to show in the exponent.
jpayne@69 412 * @return A ScientificNotation, for chaining.
jpayne@69 413 * @stable ICU 60
jpayne@69 414 */
jpayne@69 415 ScientificNotation withMinExponentDigits(int32_t minExponentDigits) const;
jpayne@69 416
jpayne@69 417 /**
jpayne@69 418 * Sets whether to show the sign on positive and negative exponents in scientific notation. The default is AUTO,
jpayne@69 419 * showing the minus sign but not the plus sign.
jpayne@69 420 *
jpayne@69 421 * <p>
jpayne@69 422 * For example, with exponentSignDisplay=ALWAYS, the number 123 will be printed as "1.23E+2" in <em>en-US</em>
jpayne@69 423 * instead of the default "1.23E2".
jpayne@69 424 *
jpayne@69 425 * @param exponentSignDisplay
jpayne@69 426 * The strategy for displaying the sign in the exponent.
jpayne@69 427 * @return A ScientificNotation, for chaining.
jpayne@69 428 * @stable ICU 60
jpayne@69 429 */
jpayne@69 430 ScientificNotation withExponentSignDisplay(UNumberSignDisplay exponentSignDisplay) const;
jpayne@69 431
jpayne@69 432 private:
jpayne@69 433 // Inherit constructor
jpayne@69 434 using Notation::Notation;
jpayne@69 435
jpayne@69 436 // Raw constructor for NumberPropertyMapper
jpayne@69 437 ScientificNotation(int8_t fEngineeringInterval, bool fRequireMinInt, impl::digits_t fMinExponentDigits,
jpayne@69 438 UNumberSignDisplay fExponentSignDisplay);
jpayne@69 439
jpayne@69 440 friend class Notation;
jpayne@69 441
jpayne@69 442 // So that NumberPropertyMapper can create instances
jpayne@69 443 friend class impl::NumberPropertyMapper;
jpayne@69 444 };
jpayne@69 445
jpayne@69 446 /**
jpayne@69 447 * Extra name reserved in case it is needed in the future.
jpayne@69 448 *
jpayne@69 449 * @stable ICU 63
jpayne@69 450 */
jpayne@69 451 typedef Precision SignificantDigitsPrecision;
jpayne@69 452
jpayne@69 453 /**
jpayne@69 454 * A class that defines the rounding precision to be used when formatting numbers in NumberFormatter.
jpayne@69 455 *
jpayne@69 456 * <p>
jpayne@69 457 * To create a Precision, use one of the factory methods.
jpayne@69 458 *
jpayne@69 459 * @stable ICU 60
jpayne@69 460 */
jpayne@69 461 class U_I18N_API Precision : public UMemory {
jpayne@69 462
jpayne@69 463 public:
jpayne@69 464 /**
jpayne@69 465 * Show all available digits to full precision.
jpayne@69 466 *
jpayne@69 467 * <p>
jpayne@69 468 * <strong>NOTE:</strong> When formatting a <em>double</em>, this method, along with {@link #minFraction} and
jpayne@69 469 * {@link #minSignificantDigits}, will trigger complex algorithm similar to <em>Dragon4</em> to determine the
jpayne@69 470 * low-order digits and the number of digits to display based on the value of the double.
jpayne@69 471 * If the number of fraction places or significant digits can be bounded, consider using {@link #maxFraction}
jpayne@69 472 * or {@link #maxSignificantDigits} instead to maximize performance.
jpayne@69 473 * For more information, read the following blog post.
jpayne@69 474 *
jpayne@69 475 * <p>
jpayne@69 476 * http://www.serpentine.com/blog/2011/06/29/here-be-dragons-advances-in-problems-you-didnt-even-know-you-had/
jpayne@69 477 *
jpayne@69 478 * @return A Precision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 479 * @stable ICU 60
jpayne@69 480 */
jpayne@69 481 static Precision unlimited();
jpayne@69 482
jpayne@69 483 /**
jpayne@69 484 * Show numbers rounded if necessary to the nearest integer.
jpayne@69 485 *
jpayne@69 486 * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 487 * @stable ICU 60
jpayne@69 488 */
jpayne@69 489 static FractionPrecision integer();
jpayne@69 490
jpayne@69 491 /**
jpayne@69 492 * Show numbers rounded if necessary to a certain number of fraction places (numerals after the decimal separator).
jpayne@69 493 * Additionally, pad with zeros to ensure that this number of places are always shown.
jpayne@69 494 *
jpayne@69 495 * <p>
jpayne@69 496 * Example output with minMaxFractionPlaces = 3:
jpayne@69 497 *
jpayne@69 498 * <p>
jpayne@69 499 * 87,650.000<br>
jpayne@69 500 * 8,765.000<br>
jpayne@69 501 * 876.500<br>
jpayne@69 502 * 87.650<br>
jpayne@69 503 * 8.765<br>
jpayne@69 504 * 0.876<br>
jpayne@69 505 * 0.088<br>
jpayne@69 506 * 0.009<br>
jpayne@69 507 * 0.000 (zero)
jpayne@69 508 *
jpayne@69 509 * <p>
jpayne@69 510 * This method is equivalent to {@link #minMaxFraction} with both arguments equal.
jpayne@69 511 *
jpayne@69 512 * @param minMaxFractionPlaces
jpayne@69 513 * The minimum and maximum number of numerals to display after the decimal separator (rounding if too
jpayne@69 514 * long or padding with zeros if too short).
jpayne@69 515 * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 516 * @stable ICU 60
jpayne@69 517 */
jpayne@69 518 static FractionPrecision fixedFraction(int32_t minMaxFractionPlaces);
jpayne@69 519
jpayne@69 520 /**
jpayne@69 521 * Always show at least a certain number of fraction places after the decimal separator, padding with zeros if
jpayne@69 522 * necessary. Do not perform rounding (display numbers to their full precision).
jpayne@69 523 *
jpayne@69 524 * <p>
jpayne@69 525 * <strong>NOTE:</strong> If you are formatting <em>doubles</em>, see the performance note in {@link #unlimited}.
jpayne@69 526 *
jpayne@69 527 * @param minFractionPlaces
jpayne@69 528 * The minimum number of numerals to display after the decimal separator (padding with zeros if
jpayne@69 529 * necessary).
jpayne@69 530 * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 531 * @stable ICU 60
jpayne@69 532 */
jpayne@69 533 static FractionPrecision minFraction(int32_t minFractionPlaces);
jpayne@69 534
jpayne@69 535 /**
jpayne@69 536 * Show numbers rounded if necessary to a certain number of fraction places (numerals after the decimal separator).
jpayne@69 537 * Unlike the other fraction rounding strategies, this strategy does <em>not</em> pad zeros to the end of the
jpayne@69 538 * number.
jpayne@69 539 *
jpayne@69 540 * @param maxFractionPlaces
jpayne@69 541 * The maximum number of numerals to display after the decimal mark (rounding if necessary).
jpayne@69 542 * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 543 * @stable ICU 60
jpayne@69 544 */
jpayne@69 545 static FractionPrecision maxFraction(int32_t maxFractionPlaces);
jpayne@69 546
jpayne@69 547 /**
jpayne@69 548 * Show numbers rounded if necessary to a certain number of fraction places (numerals after the decimal separator);
jpayne@69 549 * in addition, always show at least a certain number of places after the decimal separator, padding with zeros if
jpayne@69 550 * necessary.
jpayne@69 551 *
jpayne@69 552 * @param minFractionPlaces
jpayne@69 553 * The minimum number of numerals to display after the decimal separator (padding with zeros if
jpayne@69 554 * necessary).
jpayne@69 555 * @param maxFractionPlaces
jpayne@69 556 * The maximum number of numerals to display after the decimal separator (rounding if necessary).
jpayne@69 557 * @return A FractionPrecision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 558 * @stable ICU 60
jpayne@69 559 */
jpayne@69 560 static FractionPrecision minMaxFraction(int32_t minFractionPlaces, int32_t maxFractionPlaces);
jpayne@69 561
jpayne@69 562 /**
jpayne@69 563 * Show numbers rounded if necessary to a certain number of significant digits or significant figures. Additionally,
jpayne@69 564 * pad with zeros to ensure that this number of significant digits/figures are always shown.
jpayne@69 565 *
jpayne@69 566 * <p>
jpayne@69 567 * This method is equivalent to {@link #minMaxSignificantDigits} with both arguments equal.
jpayne@69 568 *
jpayne@69 569 * @param minMaxSignificantDigits
jpayne@69 570 * The minimum and maximum number of significant digits to display (rounding if too long or padding with
jpayne@69 571 * zeros if too short).
jpayne@69 572 * @return A precision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 573 * @stable ICU 62
jpayne@69 574 */
jpayne@69 575 static SignificantDigitsPrecision fixedSignificantDigits(int32_t minMaxSignificantDigits);
jpayne@69 576
jpayne@69 577 /**
jpayne@69 578 * Always show at least a certain number of significant digits/figures, padding with zeros if necessary. Do not
jpayne@69 579 * perform rounding (display numbers to their full precision).
jpayne@69 580 *
jpayne@69 581 * <p>
jpayne@69 582 * <strong>NOTE:</strong> If you are formatting <em>doubles</em>, see the performance note in {@link #unlimited}.
jpayne@69 583 *
jpayne@69 584 * @param minSignificantDigits
jpayne@69 585 * The minimum number of significant digits to display (padding with zeros if too short).
jpayne@69 586 * @return A precision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 587 * @stable ICU 62
jpayne@69 588 */
jpayne@69 589 static SignificantDigitsPrecision minSignificantDigits(int32_t minSignificantDigits);
jpayne@69 590
jpayne@69 591 /**
jpayne@69 592 * Show numbers rounded if necessary to a certain number of significant digits/figures.
jpayne@69 593 *
jpayne@69 594 * @param maxSignificantDigits
jpayne@69 595 * The maximum number of significant digits to display (rounding if too long).
jpayne@69 596 * @return A precision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 597 * @stable ICU 62
jpayne@69 598 */
jpayne@69 599 static SignificantDigitsPrecision maxSignificantDigits(int32_t maxSignificantDigits);
jpayne@69 600
jpayne@69 601 /**
jpayne@69 602 * Show numbers rounded if necessary to a certain number of significant digits/figures; in addition, always show at
jpayne@69 603 * least a certain number of significant digits, padding with zeros if necessary.
jpayne@69 604 *
jpayne@69 605 * @param minSignificantDigits
jpayne@69 606 * The minimum number of significant digits to display (padding with zeros if necessary).
jpayne@69 607 * @param maxSignificantDigits
jpayne@69 608 * The maximum number of significant digits to display (rounding if necessary).
jpayne@69 609 * @return A precision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 610 * @stable ICU 62
jpayne@69 611 */
jpayne@69 612 static SignificantDigitsPrecision minMaxSignificantDigits(int32_t minSignificantDigits,
jpayne@69 613 int32_t maxSignificantDigits);
jpayne@69 614
jpayne@69 615 /**
jpayne@69 616 * Show numbers rounded if necessary to the closest multiple of a certain rounding increment. For example, if the
jpayne@69 617 * rounding increment is 0.5, then round 1.2 to 1 and round 1.3 to 1.5.
jpayne@69 618 *
jpayne@69 619 * <p>
jpayne@69 620 * In order to ensure that numbers are padded to the appropriate number of fraction places, call
jpayne@69 621 * withMinFraction() on the return value of this method.
jpayne@69 622 * For example, to round to the nearest 0.5 and always display 2 numerals after the
jpayne@69 623 * decimal separator (to display 1.2 as "1.00" and 1.3 as "1.50"), you can run:
jpayne@69 624 *
jpayne@69 625 * <pre>
jpayne@69 626 * Precision::increment(0.5).withMinFraction(2)
jpayne@69 627 * </pre>
jpayne@69 628 *
jpayne@69 629 * @param roundingIncrement
jpayne@69 630 * The increment to which to round numbers.
jpayne@69 631 * @return A precision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 632 * @stable ICU 60
jpayne@69 633 */
jpayne@69 634 static IncrementPrecision increment(double roundingIncrement);
jpayne@69 635
jpayne@69 636 /**
jpayne@69 637 * Show numbers rounded and padded according to the rules for the currency unit. The most common
jpayne@69 638 * rounding precision settings for currencies include <code>Precision::fixedFraction(2)</code>,
jpayne@69 639 * <code>Precision::integer()</code>, and <code>Precision::increment(0.05)</code> for cash transactions
jpayne@69 640 * ("nickel rounding").
jpayne@69 641 *
jpayne@69 642 * <p>
jpayne@69 643 * The exact rounding details will be resolved at runtime based on the currency unit specified in the
jpayne@69 644 * NumberFormatter chain. To round according to the rules for one currency while displaying the symbol for another
jpayne@69 645 * currency, the withCurrency() method can be called on the return value of this method.
jpayne@69 646 *
jpayne@69 647 * @param currencyUsage
jpayne@69 648 * Either STANDARD (for digital transactions) or CASH (for transactions where the rounding increment may
jpayne@69 649 * be limited by the available denominations of cash or coins).
jpayne@69 650 * @return A CurrencyPrecision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 651 * @stable ICU 60
jpayne@69 652 */
jpayne@69 653 static CurrencyPrecision currency(UCurrencyUsage currencyUsage);
jpayne@69 654
jpayne@69 655 private:
jpayne@69 656 enum PrecisionType {
jpayne@69 657 RND_BOGUS,
jpayne@69 658 RND_NONE,
jpayne@69 659 RND_FRACTION,
jpayne@69 660 RND_SIGNIFICANT,
jpayne@69 661 RND_FRACTION_SIGNIFICANT,
jpayne@69 662
jpayne@69 663 // Used for strange increments like 3.14.
jpayne@69 664 RND_INCREMENT,
jpayne@69 665
jpayne@69 666 // Used for increments with 1 as the only digit. This is different than fraction
jpayne@69 667 // rounding because it supports having additional trailing zeros. For example, this
jpayne@69 668 // class is used to round with the increment 0.010.
jpayne@69 669 RND_INCREMENT_ONE,
jpayne@69 670
jpayne@69 671 // Used for increments with 5 as the only digit (nickel rounding).
jpayne@69 672 RND_INCREMENT_FIVE,
jpayne@69 673
jpayne@69 674 RND_CURRENCY,
jpayne@69 675 RND_ERROR
jpayne@69 676 } fType;
jpayne@69 677
jpayne@69 678 union PrecisionUnion {
jpayne@69 679 /** @internal */
jpayne@69 680 struct FractionSignificantSettings {
jpayne@69 681 // For RND_FRACTION, RND_SIGNIFICANT, and RND_FRACTION_SIGNIFICANT
jpayne@69 682 /** @internal */
jpayne@69 683 impl::digits_t fMinFrac;
jpayne@69 684 /** @internal */
jpayne@69 685 impl::digits_t fMaxFrac;
jpayne@69 686 /** @internal */
jpayne@69 687 impl::digits_t fMinSig;
jpayne@69 688 /** @internal */
jpayne@69 689 impl::digits_t fMaxSig;
jpayne@69 690 } fracSig;
jpayne@69 691 /** @internal */
jpayne@69 692 struct IncrementSettings {
jpayne@69 693 // For RND_INCREMENT, RND_INCREMENT_ONE, and RND_INCREMENT_FIVE
jpayne@69 694 /** @internal */
jpayne@69 695 double fIncrement;
jpayne@69 696 /** @internal */
jpayne@69 697 impl::digits_t fMinFrac;
jpayne@69 698 /** @internal */
jpayne@69 699 impl::digits_t fMaxFrac;
jpayne@69 700 } increment;
jpayne@69 701 UCurrencyUsage currencyUsage; // For RND_CURRENCY
jpayne@69 702 UErrorCode errorCode; // For RND_ERROR
jpayne@69 703 } fUnion;
jpayne@69 704
jpayne@69 705 typedef PrecisionUnion::FractionSignificantSettings FractionSignificantSettings;
jpayne@69 706 typedef PrecisionUnion::IncrementSettings IncrementSettings;
jpayne@69 707
jpayne@69 708 /** The Precision encapsulates the RoundingMode when used within the implementation. */
jpayne@69 709 UNumberFormatRoundingMode fRoundingMode;
jpayne@69 710
jpayne@69 711 Precision(const PrecisionType& type, const PrecisionUnion& union_,
jpayne@69 712 UNumberFormatRoundingMode roundingMode)
jpayne@69 713 : fType(type), fUnion(union_), fRoundingMode(roundingMode) {}
jpayne@69 714
jpayne@69 715 Precision(UErrorCode errorCode) : fType(RND_ERROR) {
jpayne@69 716 fUnion.errorCode = errorCode;
jpayne@69 717 }
jpayne@69 718
jpayne@69 719 Precision() : fType(RND_BOGUS) {}
jpayne@69 720
jpayne@69 721 bool isBogus() const {
jpayne@69 722 return fType == RND_BOGUS;
jpayne@69 723 }
jpayne@69 724
jpayne@69 725 UBool copyErrorTo(UErrorCode &status) const {
jpayne@69 726 if (fType == RND_ERROR) {
jpayne@69 727 status = fUnion.errorCode;
jpayne@69 728 return TRUE;
jpayne@69 729 }
jpayne@69 730 return FALSE;
jpayne@69 731 }
jpayne@69 732
jpayne@69 733 // On the parent type so that this method can be called internally on Precision instances.
jpayne@69 734 Precision withCurrency(const CurrencyUnit &currency, UErrorCode &status) const;
jpayne@69 735
jpayne@69 736 static FractionPrecision constructFraction(int32_t minFrac, int32_t maxFrac);
jpayne@69 737
jpayne@69 738 static Precision constructSignificant(int32_t minSig, int32_t maxSig);
jpayne@69 739
jpayne@69 740 static Precision
jpayne@69 741 constructFractionSignificant(const FractionPrecision &base, int32_t minSig, int32_t maxSig);
jpayne@69 742
jpayne@69 743 static IncrementPrecision constructIncrement(double increment, int32_t minFrac);
jpayne@69 744
jpayne@69 745 static CurrencyPrecision constructCurrency(UCurrencyUsage usage);
jpayne@69 746
jpayne@69 747 static Precision constructPassThrough();
jpayne@69 748
jpayne@69 749 // To allow MacroProps/MicroProps to initialize bogus instances:
jpayne@69 750 friend struct impl::MacroProps;
jpayne@69 751 friend struct impl::MicroProps;
jpayne@69 752
jpayne@69 753 // To allow NumberFormatterImpl to access isBogus() and other internal methods:
jpayne@69 754 friend class impl::NumberFormatterImpl;
jpayne@69 755
jpayne@69 756 // To allow NumberPropertyMapper to create instances from DecimalFormatProperties:
jpayne@69 757 friend class impl::NumberPropertyMapper;
jpayne@69 758
jpayne@69 759 // To allow access to the main implementation class:
jpayne@69 760 friend class impl::RoundingImpl;
jpayne@69 761
jpayne@69 762 // To allow child classes to call private methods:
jpayne@69 763 friend class FractionPrecision;
jpayne@69 764 friend class CurrencyPrecision;
jpayne@69 765 friend class IncrementPrecision;
jpayne@69 766
jpayne@69 767 // To allow access to the skeleton generation code:
jpayne@69 768 friend class impl::GeneratorHelpers;
jpayne@69 769 };
jpayne@69 770
jpayne@69 771 /**
jpayne@69 772 * A class that defines a rounding precision based on a number of fraction places and optionally significant digits to be
jpayne@69 773 * used when formatting numbers in NumberFormatter.
jpayne@69 774 *
jpayne@69 775 * <p>
jpayne@69 776 * To create a FractionPrecision, use one of the factory methods on Precision.
jpayne@69 777 *
jpayne@69 778 * @stable ICU 60
jpayne@69 779 */
jpayne@69 780 class U_I18N_API FractionPrecision : public Precision {
jpayne@69 781 public:
jpayne@69 782 /**
jpayne@69 783 * Ensure that no less than this number of significant digits are retained when rounding according to fraction
jpayne@69 784 * rules.
jpayne@69 785 *
jpayne@69 786 * <p>
jpayne@69 787 * For example, with integer rounding, the number 3.141 becomes "3". However, with minimum figures set to 2, 3.141
jpayne@69 788 * becomes "3.1" instead.
jpayne@69 789 *
jpayne@69 790 * <p>
jpayne@69 791 * This setting does not affect the number of trailing zeros. For example, 3.01 would print as "3", not "3.0".
jpayne@69 792 *
jpayne@69 793 * @param minSignificantDigits
jpayne@69 794 * The number of significant figures to guarantee.
jpayne@69 795 * @return A precision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 796 * @stable ICU 60
jpayne@69 797 */
jpayne@69 798 Precision withMinDigits(int32_t minSignificantDigits) const;
jpayne@69 799
jpayne@69 800 /**
jpayne@69 801 * Ensure that no more than this number of significant digits are retained when rounding according to fraction
jpayne@69 802 * rules.
jpayne@69 803 *
jpayne@69 804 * <p>
jpayne@69 805 * For example, with integer rounding, the number 123.4 becomes "123". However, with maximum figures set to 2, 123.4
jpayne@69 806 * becomes "120" instead.
jpayne@69 807 *
jpayne@69 808 * <p>
jpayne@69 809 * This setting does not affect the number of trailing zeros. For example, with fixed fraction of 2, 123.4 would
jpayne@69 810 * become "120.00".
jpayne@69 811 *
jpayne@69 812 * @param maxSignificantDigits
jpayne@69 813 * Round the number to no more than this number of significant figures.
jpayne@69 814 * @return A precision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 815 * @stable ICU 60
jpayne@69 816 */
jpayne@69 817 Precision withMaxDigits(int32_t maxSignificantDigits) const;
jpayne@69 818
jpayne@69 819 private:
jpayne@69 820 // Inherit constructor
jpayne@69 821 using Precision::Precision;
jpayne@69 822
jpayne@69 823 // To allow parent class to call this class's constructor:
jpayne@69 824 friend class Precision;
jpayne@69 825 };
jpayne@69 826
jpayne@69 827 /**
jpayne@69 828 * A class that defines a rounding precision parameterized by a currency to be used when formatting numbers in
jpayne@69 829 * NumberFormatter.
jpayne@69 830 *
jpayne@69 831 * <p>
jpayne@69 832 * To create a CurrencyPrecision, use one of the factory methods on Precision.
jpayne@69 833 *
jpayne@69 834 * @stable ICU 60
jpayne@69 835 */
jpayne@69 836 class U_I18N_API CurrencyPrecision : public Precision {
jpayne@69 837 public:
jpayne@69 838 /**
jpayne@69 839 * Associates a currency with this rounding precision.
jpayne@69 840 *
jpayne@69 841 * <p>
jpayne@69 842 * <strong>Calling this method is <em>not required</em></strong>, because the currency specified in unit()
jpayne@69 843 * is automatically applied to currency rounding precisions. However,
jpayne@69 844 * this method enables you to override that automatic association.
jpayne@69 845 *
jpayne@69 846 * <p>
jpayne@69 847 * This method also enables numbers to be formatted using currency rounding rules without explicitly using a
jpayne@69 848 * currency format.
jpayne@69 849 *
jpayne@69 850 * @param currency
jpayne@69 851 * The currency to associate with this rounding precision.
jpayne@69 852 * @return A precision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 853 * @stable ICU 60
jpayne@69 854 */
jpayne@69 855 Precision withCurrency(const CurrencyUnit &currency) const;
jpayne@69 856
jpayne@69 857 private:
jpayne@69 858 // Inherit constructor
jpayne@69 859 using Precision::Precision;
jpayne@69 860
jpayne@69 861 // To allow parent class to call this class's constructor:
jpayne@69 862 friend class Precision;
jpayne@69 863 };
jpayne@69 864
jpayne@69 865 /**
jpayne@69 866 * A class that defines a rounding precision parameterized by a rounding increment to be used when formatting numbers in
jpayne@69 867 * NumberFormatter.
jpayne@69 868 *
jpayne@69 869 * <p>
jpayne@69 870 * To create an IncrementPrecision, use one of the factory methods on Precision.
jpayne@69 871 *
jpayne@69 872 * @stable ICU 60
jpayne@69 873 */
jpayne@69 874 class U_I18N_API IncrementPrecision : public Precision {
jpayne@69 875 public:
jpayne@69 876 /**
jpayne@69 877 * Specifies the minimum number of fraction digits to render after the decimal separator, padding with zeros if
jpayne@69 878 * necessary. By default, no trailing zeros are added.
jpayne@69 879 *
jpayne@69 880 * <p>
jpayne@69 881 * For example, if the rounding increment is 0.5 and minFrac is 2, then the resulting strings include "0.00",
jpayne@69 882 * "0.50", "1.00", and "1.50".
jpayne@69 883 *
jpayne@69 884 * <p>
jpayne@69 885 * Note: In ICU4J, this functionality is accomplished via the scale of the BigDecimal rounding increment.
jpayne@69 886 *
jpayne@69 887 * @param minFrac The minimum number of digits after the decimal separator.
jpayne@69 888 * @return A precision for chaining or passing to the NumberFormatter precision() setter.
jpayne@69 889 * @stable ICU 60
jpayne@69 890 */
jpayne@69 891 Precision withMinFraction(int32_t minFrac) const;
jpayne@69 892
jpayne@69 893 private:
jpayne@69 894 // Inherit constructor
jpayne@69 895 using Precision::Precision;
jpayne@69 896
jpayne@69 897 // To allow parent class to call this class's constructor:
jpayne@69 898 friend class Precision;
jpayne@69 899 };
jpayne@69 900
jpayne@69 901 /**
jpayne@69 902 * A class that defines the strategy for padding and truncating integers before the decimal separator.
jpayne@69 903 *
jpayne@69 904 * <p>
jpayne@69 905 * To create an IntegerWidth, use one of the factory methods.
jpayne@69 906 *
jpayne@69 907 * @stable ICU 60
jpayne@69 908 * @see NumberFormatter
jpayne@69 909 */
jpayne@69 910 class U_I18N_API IntegerWidth : public UMemory {
jpayne@69 911 public:
jpayne@69 912 /**
jpayne@69 913 * Pad numbers at the beginning with zeros to guarantee a certain number of numerals before the decimal separator.
jpayne@69 914 *
jpayne@69 915 * <p>
jpayne@69 916 * For example, with minInt=3, the number 55 will get printed as "055".
jpayne@69 917 *
jpayne@69 918 * @param minInt
jpayne@69 919 * The minimum number of places before the decimal separator.
jpayne@69 920 * @return An IntegerWidth for chaining or passing to the NumberFormatter integerWidth() setter.
jpayne@69 921 * @stable ICU 60
jpayne@69 922 */
jpayne@69 923 static IntegerWidth zeroFillTo(int32_t minInt);
jpayne@69 924
jpayne@69 925 /**
jpayne@69 926 * Truncate numbers exceeding a certain number of numerals before the decimal separator.
jpayne@69 927 *
jpayne@69 928 * For example, with maxInt=3, the number 1234 will get printed as "234".
jpayne@69 929 *
jpayne@69 930 * @param maxInt
jpayne@69 931 * The maximum number of places before the decimal separator. maxInt == -1 means no
jpayne@69 932 * truncation.
jpayne@69 933 * @return An IntegerWidth for passing to the NumberFormatter integerWidth() setter.
jpayne@69 934 * @stable ICU 60
jpayne@69 935 */
jpayne@69 936 IntegerWidth truncateAt(int32_t maxInt);
jpayne@69 937
jpayne@69 938 private:
jpayne@69 939 union {
jpayne@69 940 struct {
jpayne@69 941 impl::digits_t fMinInt;
jpayne@69 942 impl::digits_t fMaxInt;
jpayne@69 943 bool fFormatFailIfMoreThanMaxDigits;
jpayne@69 944 } minMaxInt;
jpayne@69 945 UErrorCode errorCode;
jpayne@69 946 } fUnion;
jpayne@69 947 bool fHasError = false;
jpayne@69 948
jpayne@69 949 IntegerWidth(impl::digits_t minInt, impl::digits_t maxInt, bool formatFailIfMoreThanMaxDigits);
jpayne@69 950
jpayne@69 951 IntegerWidth(UErrorCode errorCode) { // NOLINT
jpayne@69 952 fUnion.errorCode = errorCode;
jpayne@69 953 fHasError = true;
jpayne@69 954 }
jpayne@69 955
jpayne@69 956 IntegerWidth() { // NOLINT
jpayne@69 957 fUnion.minMaxInt.fMinInt = -1;
jpayne@69 958 }
jpayne@69 959
jpayne@69 960 /** Returns the default instance. */
jpayne@69 961 static IntegerWidth standard() {
jpayne@69 962 return IntegerWidth::zeroFillTo(1);
jpayne@69 963 }
jpayne@69 964
jpayne@69 965 bool isBogus() const {
jpayne@69 966 return !fHasError && fUnion.minMaxInt.fMinInt == -1;
jpayne@69 967 }
jpayne@69 968
jpayne@69 969 UBool copyErrorTo(UErrorCode &status) const {
jpayne@69 970 if (fHasError) {
jpayne@69 971 status = fUnion.errorCode;
jpayne@69 972 return TRUE;
jpayne@69 973 }
jpayne@69 974 return FALSE;
jpayne@69 975 }
jpayne@69 976
jpayne@69 977 void apply(impl::DecimalQuantity &quantity, UErrorCode &status) const;
jpayne@69 978
jpayne@69 979 bool operator==(const IntegerWidth& other) const;
jpayne@69 980
jpayne@69 981 // To allow MacroProps/MicroProps to initialize empty instances:
jpayne@69 982 friend struct impl::MacroProps;
jpayne@69 983 friend struct impl::MicroProps;
jpayne@69 984
jpayne@69 985 // To allow NumberFormatterImpl to access isBogus():
jpayne@69 986 friend class impl::NumberFormatterImpl;
jpayne@69 987
jpayne@69 988 // To allow the use of this class when formatting:
jpayne@69 989 friend class impl::MutablePatternModifier;
jpayne@69 990 friend class impl::ImmutablePatternModifier;
jpayne@69 991
jpayne@69 992 // So that NumberPropertyMapper can create instances
jpayne@69 993 friend class impl::NumberPropertyMapper;
jpayne@69 994
jpayne@69 995 // To allow access to the skeleton generation code:
jpayne@69 996 friend class impl::GeneratorHelpers;
jpayne@69 997 };
jpayne@69 998
jpayne@69 999 /**
jpayne@69 1000 * A class that defines a quantity by which a number should be multiplied when formatting.
jpayne@69 1001 *
jpayne@69 1002 * <p>
jpayne@69 1003 * To create a Scale, use one of the factory methods.
jpayne@69 1004 *
jpayne@69 1005 * @stable ICU 62
jpayne@69 1006 */
jpayne@69 1007 class U_I18N_API Scale : public UMemory {
jpayne@69 1008 public:
jpayne@69 1009 /**
jpayne@69 1010 * Do not change the value of numbers when formatting or parsing.
jpayne@69 1011 *
jpayne@69 1012 * @return A Scale to prevent any multiplication.
jpayne@69 1013 * @stable ICU 62
jpayne@69 1014 */
jpayne@69 1015 static Scale none();
jpayne@69 1016
jpayne@69 1017 /**
jpayne@69 1018 * Multiply numbers by a power of ten before formatting. Useful for combining with a percent unit:
jpayne@69 1019 *
jpayne@69 1020 * <pre>
jpayne@69 1021 * NumberFormatter::with().unit(NoUnit::percent()).multiplier(Scale::powerOfTen(2))
jpayne@69 1022 * </pre>
jpayne@69 1023 *
jpayne@69 1024 * @return A Scale for passing to the setter in NumberFormatter.
jpayne@69 1025 * @stable ICU 62
jpayne@69 1026 */
jpayne@69 1027 static Scale powerOfTen(int32_t power);
jpayne@69 1028
jpayne@69 1029 /**
jpayne@69 1030 * Multiply numbers by an arbitrary value before formatting. Useful for unit conversions.
jpayne@69 1031 *
jpayne@69 1032 * This method takes a string in a decimal number format with syntax
jpayne@69 1033 * as defined in the Decimal Arithmetic Specification, available at
jpayne@69 1034 * http://speleotrove.com/decimal
jpayne@69 1035 *
jpayne@69 1036 * Also see the version of this method that takes a double.
jpayne@69 1037 *
jpayne@69 1038 * @return A Scale for passing to the setter in NumberFormatter.
jpayne@69 1039 * @stable ICU 62
jpayne@69 1040 */
jpayne@69 1041 static Scale byDecimal(StringPiece multiplicand);
jpayne@69 1042
jpayne@69 1043 /**
jpayne@69 1044 * Multiply numbers by an arbitrary value before formatting. Useful for unit conversions.
jpayne@69 1045 *
jpayne@69 1046 * This method takes a double; also see the version of this method that takes an exact decimal.
jpayne@69 1047 *
jpayne@69 1048 * @return A Scale for passing to the setter in NumberFormatter.
jpayne@69 1049 * @stable ICU 62
jpayne@69 1050 */
jpayne@69 1051 static Scale byDouble(double multiplicand);
jpayne@69 1052
jpayne@69 1053 /**
jpayne@69 1054 * Multiply a number by both a power of ten and by an arbitrary double value.
jpayne@69 1055 *
jpayne@69 1056 * @return A Scale for passing to the setter in NumberFormatter.
jpayne@69 1057 * @stable ICU 62
jpayne@69 1058 */
jpayne@69 1059 static Scale byDoubleAndPowerOfTen(double multiplicand, int32_t power);
jpayne@69 1060
jpayne@69 1061 // We need a custom destructor for the DecNum, which means we need to declare
jpayne@69 1062 // the copy/move constructor/assignment quartet.
jpayne@69 1063
jpayne@69 1064 /** @stable ICU 62 */
jpayne@69 1065 Scale(const Scale& other);
jpayne@69 1066
jpayne@69 1067 /** @stable ICU 62 */
jpayne@69 1068 Scale& operator=(const Scale& other);
jpayne@69 1069
jpayne@69 1070 /** @stable ICU 62 */
jpayne@69 1071 Scale(Scale&& src) U_NOEXCEPT;
jpayne@69 1072
jpayne@69 1073 /** @stable ICU 62 */
jpayne@69 1074 Scale& operator=(Scale&& src) U_NOEXCEPT;
jpayne@69 1075
jpayne@69 1076 /** @stable ICU 62 */
jpayne@69 1077 ~Scale();
jpayne@69 1078
jpayne@69 1079 #ifndef U_HIDE_INTERNAL_API
jpayne@69 1080 /** @internal */
jpayne@69 1081 Scale(int32_t magnitude, impl::DecNum* arbitraryToAdopt);
jpayne@69 1082 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 1083
jpayne@69 1084 private:
jpayne@69 1085 int32_t fMagnitude;
jpayne@69 1086 impl::DecNum* fArbitrary;
jpayne@69 1087 UErrorCode fError;
jpayne@69 1088
jpayne@69 1089 Scale(UErrorCode error) : fMagnitude(0), fArbitrary(nullptr), fError(error) {}
jpayne@69 1090
jpayne@69 1091 Scale() : fMagnitude(0), fArbitrary(nullptr), fError(U_ZERO_ERROR) {}
jpayne@69 1092
jpayne@69 1093 bool isValid() const {
jpayne@69 1094 return fMagnitude != 0 || fArbitrary != nullptr;
jpayne@69 1095 }
jpayne@69 1096
jpayne@69 1097 UBool copyErrorTo(UErrorCode &status) const {
jpayne@69 1098 if (fError != U_ZERO_ERROR) {
jpayne@69 1099 status = fError;
jpayne@69 1100 return TRUE;
jpayne@69 1101 }
jpayne@69 1102 return FALSE;
jpayne@69 1103 }
jpayne@69 1104
jpayne@69 1105 void applyTo(impl::DecimalQuantity& quantity) const;
jpayne@69 1106
jpayne@69 1107 void applyReciprocalTo(impl::DecimalQuantity& quantity) const;
jpayne@69 1108
jpayne@69 1109 // To allow MacroProps/MicroProps to initialize empty instances:
jpayne@69 1110 friend struct impl::MacroProps;
jpayne@69 1111 friend struct impl::MicroProps;
jpayne@69 1112
jpayne@69 1113 // To allow NumberFormatterImpl to access isBogus() and perform other operations:
jpayne@69 1114 friend class impl::NumberFormatterImpl;
jpayne@69 1115
jpayne@69 1116 // To allow the helper class MultiplierFormatHandler access to private fields:
jpayne@69 1117 friend class impl::MultiplierFormatHandler;
jpayne@69 1118
jpayne@69 1119 // To allow access to the skeleton generation code:
jpayne@69 1120 friend class impl::GeneratorHelpers;
jpayne@69 1121
jpayne@69 1122 // To allow access to parsing code:
jpayne@69 1123 friend class ::icu::numparse::impl::NumberParserImpl;
jpayne@69 1124 friend class ::icu::numparse::impl::MultiplierParseHandler;
jpayne@69 1125 };
jpayne@69 1126
jpayne@69 1127 namespace impl {
jpayne@69 1128
jpayne@69 1129 // Do not enclose entire SymbolsWrapper with #ifndef U_HIDE_INTERNAL_API, needed for a protected field
jpayne@69 1130 /** @internal */
jpayne@69 1131 class U_I18N_API SymbolsWrapper : public UMemory {
jpayne@69 1132 public:
jpayne@69 1133 /** @internal */
jpayne@69 1134 SymbolsWrapper() : fType(SYMPTR_NONE), fPtr{nullptr} {}
jpayne@69 1135
jpayne@69 1136 /** @internal */
jpayne@69 1137 SymbolsWrapper(const SymbolsWrapper &other);
jpayne@69 1138
jpayne@69 1139 /** @internal */
jpayne@69 1140 SymbolsWrapper &operator=(const SymbolsWrapper &other);
jpayne@69 1141
jpayne@69 1142 /** @internal */
jpayne@69 1143 SymbolsWrapper(SymbolsWrapper&& src) U_NOEXCEPT;
jpayne@69 1144
jpayne@69 1145 /** @internal */
jpayne@69 1146 SymbolsWrapper &operator=(SymbolsWrapper&& src) U_NOEXCEPT;
jpayne@69 1147
jpayne@69 1148 /** @internal */
jpayne@69 1149 ~SymbolsWrapper();
jpayne@69 1150
jpayne@69 1151 #ifndef U_HIDE_INTERNAL_API
jpayne@69 1152
jpayne@69 1153 /**
jpayne@69 1154 * The provided object is copied, but we do not adopt it.
jpayne@69 1155 * @internal
jpayne@69 1156 */
jpayne@69 1157 void setTo(const DecimalFormatSymbols &dfs);
jpayne@69 1158
jpayne@69 1159 /**
jpayne@69 1160 * Adopt the provided object.
jpayne@69 1161 * @internal
jpayne@69 1162 */
jpayne@69 1163 void setTo(const NumberingSystem *ns);
jpayne@69 1164
jpayne@69 1165 /**
jpayne@69 1166 * Whether the object is currently holding a DecimalFormatSymbols.
jpayne@69 1167 * @internal
jpayne@69 1168 */
jpayne@69 1169 bool isDecimalFormatSymbols() const;
jpayne@69 1170
jpayne@69 1171 /**
jpayne@69 1172 * Whether the object is currently holding a NumberingSystem.
jpayne@69 1173 * @internal
jpayne@69 1174 */
jpayne@69 1175 bool isNumberingSystem() const;
jpayne@69 1176
jpayne@69 1177 /**
jpayne@69 1178 * Get the DecimalFormatSymbols pointer. No ownership change.
jpayne@69 1179 * @internal
jpayne@69 1180 */
jpayne@69 1181 const DecimalFormatSymbols *getDecimalFormatSymbols() const;
jpayne@69 1182
jpayne@69 1183 /**
jpayne@69 1184 * Get the NumberingSystem pointer. No ownership change.
jpayne@69 1185 * @internal
jpayne@69 1186 */
jpayne@69 1187 const NumberingSystem *getNumberingSystem() const;
jpayne@69 1188
jpayne@69 1189 #endif // U_HIDE_INTERNAL_API
jpayne@69 1190
jpayne@69 1191 /** @internal */
jpayne@69 1192 UBool copyErrorTo(UErrorCode &status) const {
jpayne@69 1193 if (fType == SYMPTR_DFS && fPtr.dfs == nullptr) {
jpayne@69 1194 status = U_MEMORY_ALLOCATION_ERROR;
jpayne@69 1195 return TRUE;
jpayne@69 1196 } else if (fType == SYMPTR_NS && fPtr.ns == nullptr) {
jpayne@69 1197 status = U_MEMORY_ALLOCATION_ERROR;
jpayne@69 1198 return TRUE;
jpayne@69 1199 }
jpayne@69 1200 return FALSE;
jpayne@69 1201 }
jpayne@69 1202
jpayne@69 1203 private:
jpayne@69 1204 enum SymbolsPointerType {
jpayne@69 1205 SYMPTR_NONE, SYMPTR_DFS, SYMPTR_NS
jpayne@69 1206 } fType;
jpayne@69 1207
jpayne@69 1208 union {
jpayne@69 1209 const DecimalFormatSymbols *dfs;
jpayne@69 1210 const NumberingSystem *ns;
jpayne@69 1211 } fPtr;
jpayne@69 1212
jpayne@69 1213 void doCopyFrom(const SymbolsWrapper &other);
jpayne@69 1214
jpayne@69 1215 void doMoveFrom(SymbolsWrapper&& src);
jpayne@69 1216
jpayne@69 1217 void doCleanup();
jpayne@69 1218 };
jpayne@69 1219
jpayne@69 1220 // Do not enclose entire Grouper with #ifndef U_HIDE_INTERNAL_API, needed for a protected field
jpayne@69 1221 /** @internal */
jpayne@69 1222 class U_I18N_API Grouper : public UMemory {
jpayne@69 1223 public:
jpayne@69 1224 #ifndef U_HIDE_INTERNAL_API
jpayne@69 1225 /** @internal */
jpayne@69 1226 static Grouper forStrategy(UNumberGroupingStrategy grouping);
jpayne@69 1227
jpayne@69 1228 /**
jpayne@69 1229 * Resolve the values in Properties to a Grouper object.
jpayne@69 1230 * @internal
jpayne@69 1231 */
jpayne@69 1232 static Grouper forProperties(const DecimalFormatProperties& properties);
jpayne@69 1233
jpayne@69 1234 // Future: static Grouper forProperties(DecimalFormatProperties& properties);
jpayne@69 1235
jpayne@69 1236 /** @internal */
jpayne@69 1237 Grouper(int16_t grouping1, int16_t grouping2, int16_t minGrouping, UNumberGroupingStrategy strategy)
jpayne@69 1238 : fGrouping1(grouping1),
jpayne@69 1239 fGrouping2(grouping2),
jpayne@69 1240 fMinGrouping(minGrouping),
jpayne@69 1241 fStrategy(strategy) {}
jpayne@69 1242 #endif // U_HIDE_INTERNAL_API
jpayne@69 1243
jpayne@69 1244 /** @internal */
jpayne@69 1245 int16_t getPrimary() const;
jpayne@69 1246
jpayne@69 1247 /** @internal */
jpayne@69 1248 int16_t getSecondary() const;
jpayne@69 1249
jpayne@69 1250 private:
jpayne@69 1251 /**
jpayne@69 1252 * The grouping sizes, with the following special values:
jpayne@69 1253 * <ul>
jpayne@69 1254 * <li>-1 = no grouping
jpayne@69 1255 * <li>-2 = needs locale data
jpayne@69 1256 * <li>-4 = fall back to Western grouping if not in locale
jpayne@69 1257 * </ul>
jpayne@69 1258 */
jpayne@69 1259 int16_t fGrouping1;
jpayne@69 1260 int16_t fGrouping2;
jpayne@69 1261
jpayne@69 1262 /**
jpayne@69 1263 * The minimum grouping size, with the following special values:
jpayne@69 1264 * <ul>
jpayne@69 1265 * <li>-2 = needs locale data
jpayne@69 1266 * <li>-3 = no less than 2
jpayne@69 1267 * </ul>
jpayne@69 1268 */
jpayne@69 1269 int16_t fMinGrouping;
jpayne@69 1270
jpayne@69 1271 /**
jpayne@69 1272 * The UNumberGroupingStrategy that was used to create this Grouper, or UNUM_GROUPING_COUNT if this
jpayne@69 1273 * was not created from a UNumberGroupingStrategy.
jpayne@69 1274 */
jpayne@69 1275 UNumberGroupingStrategy fStrategy;
jpayne@69 1276
jpayne@69 1277 Grouper() : fGrouping1(-3) {}
jpayne@69 1278
jpayne@69 1279 bool isBogus() const {
jpayne@69 1280 return fGrouping1 == -3;
jpayne@69 1281 }
jpayne@69 1282
jpayne@69 1283 /** NON-CONST: mutates the current instance. */
jpayne@69 1284 void setLocaleData(const impl::ParsedPatternInfo &patternInfo, const Locale& locale);
jpayne@69 1285
jpayne@69 1286 bool groupAtPosition(int32_t position, const impl::DecimalQuantity &value) const;
jpayne@69 1287
jpayne@69 1288 // To allow MacroProps/MicroProps to initialize empty instances:
jpayne@69 1289 friend struct MacroProps;
jpayne@69 1290 friend struct MicroProps;
jpayne@69 1291
jpayne@69 1292 // To allow NumberFormatterImpl to access isBogus() and perform other operations:
jpayne@69 1293 friend class NumberFormatterImpl;
jpayne@69 1294
jpayne@69 1295 // To allow NumberParserImpl to perform setLocaleData():
jpayne@69 1296 friend class ::icu::numparse::impl::NumberParserImpl;
jpayne@69 1297
jpayne@69 1298 // To allow access to the skeleton generation code:
jpayne@69 1299 friend class impl::GeneratorHelpers;
jpayne@69 1300 };
jpayne@69 1301
jpayne@69 1302 // Do not enclose entire Padder with #ifndef U_HIDE_INTERNAL_API, needed for a protected field
jpayne@69 1303 /** @internal */
jpayne@69 1304 class U_I18N_API Padder : public UMemory {
jpayne@69 1305 public:
jpayne@69 1306 #ifndef U_HIDE_INTERNAL_API
jpayne@69 1307 /** @internal */
jpayne@69 1308 static Padder none();
jpayne@69 1309
jpayne@69 1310 /** @internal */
jpayne@69 1311 static Padder codePoints(UChar32 cp, int32_t targetWidth, UNumberFormatPadPosition position);
jpayne@69 1312 #endif // U_HIDE_INTERNAL_API
jpayne@69 1313
jpayne@69 1314 /** @internal */
jpayne@69 1315 static Padder forProperties(const DecimalFormatProperties& properties);
jpayne@69 1316
jpayne@69 1317 private:
jpayne@69 1318 UChar32 fWidth; // -3 = error; -2 = bogus; -1 = no padding
jpayne@69 1319 union {
jpayne@69 1320 struct {
jpayne@69 1321 int32_t fCp;
jpayne@69 1322 UNumberFormatPadPosition fPosition;
jpayne@69 1323 } padding;
jpayne@69 1324 UErrorCode errorCode;
jpayne@69 1325 } fUnion;
jpayne@69 1326
jpayne@69 1327 Padder(UChar32 cp, int32_t width, UNumberFormatPadPosition position);
jpayne@69 1328
jpayne@69 1329 Padder(int32_t width);
jpayne@69 1330
jpayne@69 1331 Padder(UErrorCode errorCode) : fWidth(-3) { // NOLINT
jpayne@69 1332 fUnion.errorCode = errorCode;
jpayne@69 1333 }
jpayne@69 1334
jpayne@69 1335 Padder() : fWidth(-2) {} // NOLINT
jpayne@69 1336
jpayne@69 1337 bool isBogus() const {
jpayne@69 1338 return fWidth == -2;
jpayne@69 1339 }
jpayne@69 1340
jpayne@69 1341 UBool copyErrorTo(UErrorCode &status) const {
jpayne@69 1342 if (fWidth == -3) {
jpayne@69 1343 status = fUnion.errorCode;
jpayne@69 1344 return TRUE;
jpayne@69 1345 }
jpayne@69 1346 return FALSE;
jpayne@69 1347 }
jpayne@69 1348
jpayne@69 1349 bool isValid() const {
jpayne@69 1350 return fWidth > 0;
jpayne@69 1351 }
jpayne@69 1352
jpayne@69 1353 int32_t padAndApply(const impl::Modifier &mod1, const impl::Modifier &mod2,
jpayne@69 1354 FormattedStringBuilder &string, int32_t leftIndex, int32_t rightIndex,
jpayne@69 1355 UErrorCode &status) const;
jpayne@69 1356
jpayne@69 1357 // To allow MacroProps/MicroProps to initialize empty instances:
jpayne@69 1358 friend struct MacroProps;
jpayne@69 1359 friend struct MicroProps;
jpayne@69 1360
jpayne@69 1361 // To allow NumberFormatterImpl to access isBogus() and perform other operations:
jpayne@69 1362 friend class impl::NumberFormatterImpl;
jpayne@69 1363
jpayne@69 1364 // To allow access to the skeleton generation code:
jpayne@69 1365 friend class impl::GeneratorHelpers;
jpayne@69 1366 };
jpayne@69 1367
jpayne@69 1368 // Do not enclose entire MacroProps with #ifndef U_HIDE_INTERNAL_API, needed for a protected field
jpayne@69 1369 /** @internal */
jpayne@69 1370 struct U_I18N_API MacroProps : public UMemory {
jpayne@69 1371 /** @internal */
jpayne@69 1372 Notation notation;
jpayne@69 1373
jpayne@69 1374 /** @internal */
jpayne@69 1375 MeasureUnit unit; // = NoUnit::base();
jpayne@69 1376
jpayne@69 1377 /** @internal */
jpayne@69 1378 MeasureUnit perUnit; // = NoUnit::base();
jpayne@69 1379
jpayne@69 1380 /** @internal */
jpayne@69 1381 Precision precision; // = Precision(); (bogus)
jpayne@69 1382
jpayne@69 1383 /** @internal */
jpayne@69 1384 UNumberFormatRoundingMode roundingMode = UNUM_ROUND_HALFEVEN;
jpayne@69 1385
jpayne@69 1386 /** @internal */
jpayne@69 1387 Grouper grouper; // = Grouper(); (bogus)
jpayne@69 1388
jpayne@69 1389 /** @internal */
jpayne@69 1390 Padder padder; // = Padder(); (bogus)
jpayne@69 1391
jpayne@69 1392 /** @internal */
jpayne@69 1393 IntegerWidth integerWidth; // = IntegerWidth(); (bogus)
jpayne@69 1394
jpayne@69 1395 /** @internal */
jpayne@69 1396 SymbolsWrapper symbols;
jpayne@69 1397
jpayne@69 1398 // UNUM_XYZ_COUNT denotes null (bogus) values.
jpayne@69 1399
jpayne@69 1400 /** @internal */
jpayne@69 1401 UNumberUnitWidth unitWidth = UNUM_UNIT_WIDTH_COUNT;
jpayne@69 1402
jpayne@69 1403 /** @internal */
jpayne@69 1404 UNumberSignDisplay sign = UNUM_SIGN_COUNT;
jpayne@69 1405
jpayne@69 1406 /** @internal */
jpayne@69 1407 UNumberDecimalSeparatorDisplay decimal = UNUM_DECIMAL_SEPARATOR_COUNT;
jpayne@69 1408
jpayne@69 1409 /** @internal */
jpayne@69 1410 Scale scale; // = Scale(); (benign value)
jpayne@69 1411
jpayne@69 1412 /** @internal */
jpayne@69 1413 const AffixPatternProvider* affixProvider = nullptr; // no ownership
jpayne@69 1414
jpayne@69 1415 /** @internal */
jpayne@69 1416 const PluralRules* rules = nullptr; // no ownership
jpayne@69 1417
jpayne@69 1418 /** @internal */
jpayne@69 1419 int32_t threshold = kInternalDefaultThreshold;
jpayne@69 1420
jpayne@69 1421 /** @internal */
jpayne@69 1422 Locale locale;
jpayne@69 1423
jpayne@69 1424 // NOTE: Uses default copy and move constructors.
jpayne@69 1425
jpayne@69 1426 /**
jpayne@69 1427 * Check all members for errors.
jpayne@69 1428 * @internal
jpayne@69 1429 */
jpayne@69 1430 bool copyErrorTo(UErrorCode &status) const {
jpayne@69 1431 return notation.copyErrorTo(status) || precision.copyErrorTo(status) ||
jpayne@69 1432 padder.copyErrorTo(status) || integerWidth.copyErrorTo(status) ||
jpayne@69 1433 symbols.copyErrorTo(status) || scale.copyErrorTo(status);
jpayne@69 1434 }
jpayne@69 1435 };
jpayne@69 1436
jpayne@69 1437 } // namespace impl
jpayne@69 1438
jpayne@69 1439 #if (U_PF_WINDOWS <= U_PLATFORM && U_PLATFORM <= U_PF_CYGWIN) && defined(_MSC_VER)
jpayne@69 1440 // Ignore MSVC warning 4661. This is generated for NumberFormatterSettings<>::toSkeleton() as this method
jpayne@69 1441 // is defined elsewhere (in number_skeletons.cpp). The compiler is warning that the explicit template instantiation
jpayne@69 1442 // inside this single translation unit (CPP file) is incomplete, and thus it isn't sure if the template class is
jpayne@69 1443 // fully defined. However, since each translation unit explicitly instantiates all the necessary template classes,
jpayne@69 1444 // they will all be passed to the linker, and the linker will still find and export all the class members.
jpayne@69 1445 #pragma warning(push)
jpayne@69 1446 #pragma warning(disable: 4661)
jpayne@69 1447 #endif
jpayne@69 1448
jpayne@69 1449 /**
jpayne@69 1450 * An abstract base class for specifying settings related to number formatting. This class is implemented by
jpayne@69 1451 * {@link UnlocalizedNumberFormatter} and {@link LocalizedNumberFormatter}. This class is not intended for
jpayne@69 1452 * public subclassing.
jpayne@69 1453 */
jpayne@69 1454 template<typename Derived>
jpayne@69 1455 class U_I18N_API NumberFormatterSettings {
jpayne@69 1456 public:
jpayne@69 1457 /**
jpayne@69 1458 * Specifies the notation style (simple, scientific, or compact) for rendering numbers.
jpayne@69 1459 *
jpayne@69 1460 * <ul>
jpayne@69 1461 * <li>Simple notation: "12,300"
jpayne@69 1462 * <li>Scientific notation: "1.23E4"
jpayne@69 1463 * <li>Compact notation: "12K"
jpayne@69 1464 * </ul>
jpayne@69 1465 *
jpayne@69 1466 * <p>
jpayne@69 1467 * All notation styles will be properly localized with locale data, and all notation styles are compatible with
jpayne@69 1468 * units, rounding precisions, and other number formatter settings.
jpayne@69 1469 *
jpayne@69 1470 * <p>
jpayne@69 1471 * Pass this method the return value of a {@link Notation} factory method. For example:
jpayne@69 1472 *
jpayne@69 1473 * <pre>
jpayne@69 1474 * NumberFormatter::with().notation(Notation::compactShort())
jpayne@69 1475 * </pre>
jpayne@69 1476 *
jpayne@69 1477 * The default is to use simple notation.
jpayne@69 1478 *
jpayne@69 1479 * @param notation
jpayne@69 1480 * The notation strategy to use.
jpayne@69 1481 * @return The fluent chain.
jpayne@69 1482 * @see Notation
jpayne@69 1483 * @stable ICU 60
jpayne@69 1484 */
jpayne@69 1485 Derived notation(const Notation &notation) const &;
jpayne@69 1486
jpayne@69 1487 /**
jpayne@69 1488 * Overload of notation() for use on an rvalue reference.
jpayne@69 1489 *
jpayne@69 1490 * @param notation
jpayne@69 1491 * The notation strategy to use.
jpayne@69 1492 * @return The fluent chain.
jpayne@69 1493 * @see #notation
jpayne@69 1494 * @stable ICU 62
jpayne@69 1495 */
jpayne@69 1496 Derived notation(const Notation &notation) &&;
jpayne@69 1497
jpayne@69 1498 /**
jpayne@69 1499 * Specifies the unit (unit of measure, currency, or percent) to associate with rendered numbers.
jpayne@69 1500 *
jpayne@69 1501 * <ul>
jpayne@69 1502 * <li>Unit of measure: "12.3 meters"
jpayne@69 1503 * <li>Currency: "$12.30"
jpayne@69 1504 * <li>Percent: "12.3%"
jpayne@69 1505 * </ul>
jpayne@69 1506 *
jpayne@69 1507 * All units will be properly localized with locale data, and all units are compatible with notation styles,
jpayne@69 1508 * rounding precisions, and other number formatter settings.
jpayne@69 1509 *
jpayne@69 1510 * Pass this method any instance of {@link MeasureUnit}. For units of measure:
jpayne@69 1511 *
jpayne@69 1512 * <pre>
jpayne@69 1513 * NumberFormatter::with().unit(MeasureUnit::getMeter())
jpayne@69 1514 * </pre>
jpayne@69 1515 *
jpayne@69 1516 * Currency:
jpayne@69 1517 *
jpayne@69 1518 * <pre>
jpayne@69 1519 * NumberFormatter::with().unit(CurrencyUnit(u"USD", status))
jpayne@69 1520 * </pre>
jpayne@69 1521 *
jpayne@69 1522 * Percent:
jpayne@69 1523 *
jpayne@69 1524 * <pre>
jpayne@69 1525 * NumberFormatter::with().unit(NoUnit.percent())
jpayne@69 1526 * </pre>
jpayne@69 1527 *
jpayne@69 1528 * See {@link #perUnit} for information on how to format strings like "5 meters per second".
jpayne@69 1529 *
jpayne@69 1530 * The default is to render without units (equivalent to NoUnit.base()).
jpayne@69 1531 *
jpayne@69 1532 * @param unit
jpayne@69 1533 * The unit to render.
jpayne@69 1534 * @return The fluent chain.
jpayne@69 1535 * @see MeasureUnit
jpayne@69 1536 * @see Currency
jpayne@69 1537 * @see NoUnit
jpayne@69 1538 * @see #perUnit
jpayne@69 1539 * @stable ICU 60
jpayne@69 1540 */
jpayne@69 1541 Derived unit(const icu::MeasureUnit &unit) const &;
jpayne@69 1542
jpayne@69 1543 /**
jpayne@69 1544 * Overload of unit() for use on an rvalue reference.
jpayne@69 1545 *
jpayne@69 1546 * @param unit
jpayne@69 1547 * The unit to render.
jpayne@69 1548 * @return The fluent chain.
jpayne@69 1549 * @see #unit
jpayne@69 1550 * @stable ICU 62
jpayne@69 1551 */
jpayne@69 1552 Derived unit(const icu::MeasureUnit &unit) &&;
jpayne@69 1553
jpayne@69 1554 /**
jpayne@69 1555 * Like unit(), but takes ownership of a pointer. Convenient for use with the MeasureFormat factory
jpayne@69 1556 * methods that return pointers that need ownership.
jpayne@69 1557 *
jpayne@69 1558 * Note: consider using the MeasureFormat factory methods that return by value.
jpayne@69 1559 *
jpayne@69 1560 * @param unit
jpayne@69 1561 * The unit to render.
jpayne@69 1562 * @return The fluent chain.
jpayne@69 1563 * @see #unit
jpayne@69 1564 * @see MeasureUnit
jpayne@69 1565 * @stable ICU 60
jpayne@69 1566 */
jpayne@69 1567 Derived adoptUnit(icu::MeasureUnit *unit) const &;
jpayne@69 1568
jpayne@69 1569 /**
jpayne@69 1570 * Overload of adoptUnit() for use on an rvalue reference.
jpayne@69 1571 *
jpayne@69 1572 * @param unit
jpayne@69 1573 * The unit to render.
jpayne@69 1574 * @return The fluent chain.
jpayne@69 1575 * @see #adoptUnit
jpayne@69 1576 * @stable ICU 62
jpayne@69 1577 */
jpayne@69 1578 Derived adoptUnit(icu::MeasureUnit *unit) &&;
jpayne@69 1579
jpayne@69 1580 /**
jpayne@69 1581 * Sets a unit to be used in the denominator. For example, to format "3 m/s", pass METER to the unit and SECOND to
jpayne@69 1582 * the perUnit.
jpayne@69 1583 *
jpayne@69 1584 * Pass this method any instance of {@link MeasureUnit}. Example:
jpayne@69 1585 *
jpayne@69 1586 * <pre>
jpayne@69 1587 * NumberFormatter::with()
jpayne@69 1588 * .unit(MeasureUnit::getMeter())
jpayne@69 1589 * .perUnit(MeasureUnit::getSecond())
jpayne@69 1590 * </pre>
jpayne@69 1591 *
jpayne@69 1592 * The default is not to display any unit in the denominator.
jpayne@69 1593 *
jpayne@69 1594 * If a per-unit is specified without a primary unit via {@link #unit}, the behavior is undefined.
jpayne@69 1595 *
jpayne@69 1596 * @param perUnit
jpayne@69 1597 * The unit to render in the denominator.
jpayne@69 1598 * @return The fluent chain
jpayne@69 1599 * @see #unit
jpayne@69 1600 * @stable ICU 61
jpayne@69 1601 */
jpayne@69 1602 Derived perUnit(const icu::MeasureUnit &perUnit) const &;
jpayne@69 1603
jpayne@69 1604 /**
jpayne@69 1605 * Overload of perUnit() for use on an rvalue reference.
jpayne@69 1606 *
jpayne@69 1607 * @param perUnit
jpayne@69 1608 * The unit to render in the denominator.
jpayne@69 1609 * @return The fluent chain.
jpayne@69 1610 * @see #perUnit
jpayne@69 1611 * @stable ICU 62
jpayne@69 1612 */
jpayne@69 1613 Derived perUnit(const icu::MeasureUnit &perUnit) &&;
jpayne@69 1614
jpayne@69 1615 /**
jpayne@69 1616 * Like perUnit(), but takes ownership of a pointer. Convenient for use with the MeasureFormat factory
jpayne@69 1617 * methods that return pointers that need ownership.
jpayne@69 1618 *
jpayne@69 1619 * Note: consider using the MeasureFormat factory methods that return by value.
jpayne@69 1620 *
jpayne@69 1621 * @param perUnit
jpayne@69 1622 * The unit to render in the denominator.
jpayne@69 1623 * @return The fluent chain.
jpayne@69 1624 * @see #perUnit
jpayne@69 1625 * @see MeasureUnit
jpayne@69 1626 * @stable ICU 61
jpayne@69 1627 */
jpayne@69 1628 Derived adoptPerUnit(icu::MeasureUnit *perUnit) const &;
jpayne@69 1629
jpayne@69 1630 /**
jpayne@69 1631 * Overload of adoptPerUnit() for use on an rvalue reference.
jpayne@69 1632 *
jpayne@69 1633 * @param perUnit
jpayne@69 1634 * The unit to render in the denominator.
jpayne@69 1635 * @return The fluent chain.
jpayne@69 1636 * @see #adoptPerUnit
jpayne@69 1637 * @stable ICU 62
jpayne@69 1638 */
jpayne@69 1639 Derived adoptPerUnit(icu::MeasureUnit *perUnit) &&;
jpayne@69 1640
jpayne@69 1641 /**
jpayne@69 1642 * Specifies the rounding precision to use when formatting numbers.
jpayne@69 1643 *
jpayne@69 1644 * <ul>
jpayne@69 1645 * <li>Round to 3 decimal places: "3.142"
jpayne@69 1646 * <li>Round to 3 significant figures: "3.14"
jpayne@69 1647 * <li>Round to the closest nickel: "3.15"
jpayne@69 1648 * <li>Do not perform rounding: "3.1415926..."
jpayne@69 1649 * </ul>
jpayne@69 1650 *
jpayne@69 1651 * <p>
jpayne@69 1652 * Pass this method the return value of one of the factory methods on {@link Precision}. For example:
jpayne@69 1653 *
jpayne@69 1654 * <pre>
jpayne@69 1655 * NumberFormatter::with().precision(Precision::fixedFraction(2))
jpayne@69 1656 * </pre>
jpayne@69 1657 *
jpayne@69 1658 * <p>
jpayne@69 1659 * In most cases, the default rounding strategy is to round to 6 fraction places; i.e.,
jpayne@69 1660 * <code>Precision.maxFraction(6)</code>. The exceptions are if compact notation is being used, then the compact
jpayne@69 1661 * notation rounding strategy is used (see {@link Notation#compactShort} for details), or if the unit is a currency,
jpayne@69 1662 * then standard currency rounding is used, which varies from currency to currency (see {@link Precision#currency} for
jpayne@69 1663 * details).
jpayne@69 1664 *
jpayne@69 1665 * @param precision
jpayne@69 1666 * The rounding precision to use.
jpayne@69 1667 * @return The fluent chain.
jpayne@69 1668 * @see Precision
jpayne@69 1669 * @stable ICU 62
jpayne@69 1670 */
jpayne@69 1671 Derived precision(const Precision& precision) const &;
jpayne@69 1672
jpayne@69 1673 /**
jpayne@69 1674 * Overload of precision() for use on an rvalue reference.
jpayne@69 1675 *
jpayne@69 1676 * @param precision
jpayne@69 1677 * The rounding precision to use.
jpayne@69 1678 * @return The fluent chain.
jpayne@69 1679 * @see #precision
jpayne@69 1680 * @stable ICU 62
jpayne@69 1681 */
jpayne@69 1682 Derived precision(const Precision& precision) &&;
jpayne@69 1683
jpayne@69 1684 /**
jpayne@69 1685 * Specifies how to determine the direction to round a number when it has more digits than fit in the
jpayne@69 1686 * desired precision. When formatting 1.235:
jpayne@69 1687 *
jpayne@69 1688 * <ul>
jpayne@69 1689 * <li>Ceiling rounding mode with integer precision: "2"
jpayne@69 1690 * <li>Half-down rounding mode with 2 fixed fraction digits: "1.23"
jpayne@69 1691 * <li>Half-up rounding mode with 2 fixed fraction digits: "1.24"
jpayne@69 1692 * </ul>
jpayne@69 1693 *
jpayne@69 1694 * The default is HALF_EVEN. For more information on rounding mode, see the ICU userguide here:
jpayne@69 1695 *
jpayne@69 1696 * http://userguide.icu-project.org/formatparse/numbers/rounding-modes
jpayne@69 1697 *
jpayne@69 1698 * @param roundingMode The rounding mode to use.
jpayne@69 1699 * @return The fluent chain.
jpayne@69 1700 * @stable ICU 62
jpayne@69 1701 */
jpayne@69 1702 Derived roundingMode(UNumberFormatRoundingMode roundingMode) const &;
jpayne@69 1703
jpayne@69 1704 /**
jpayne@69 1705 * Overload of roundingMode() for use on an rvalue reference.
jpayne@69 1706 *
jpayne@69 1707 * @param roundingMode The rounding mode to use.
jpayne@69 1708 * @return The fluent chain.
jpayne@69 1709 * @see #roundingMode
jpayne@69 1710 * @stable ICU 62
jpayne@69 1711 */
jpayne@69 1712 Derived roundingMode(UNumberFormatRoundingMode roundingMode) &&;
jpayne@69 1713
jpayne@69 1714 /**
jpayne@69 1715 * Specifies the grouping strategy to use when formatting numbers.
jpayne@69 1716 *
jpayne@69 1717 * <ul>
jpayne@69 1718 * <li>Default grouping: "12,300" and "1,230"
jpayne@69 1719 * <li>Grouping with at least 2 digits: "12,300" and "1230"
jpayne@69 1720 * <li>No grouping: "12300" and "1230"
jpayne@69 1721 * </ul>
jpayne@69 1722 *
jpayne@69 1723 * <p>
jpayne@69 1724 * The exact grouping widths will be chosen based on the locale.
jpayne@69 1725 *
jpayne@69 1726 * <p>
jpayne@69 1727 * Pass this method an element from the {@link UNumberGroupingStrategy} enum. For example:
jpayne@69 1728 *
jpayne@69 1729 * <pre>
jpayne@69 1730 * NumberFormatter::with().grouping(UNUM_GROUPING_MIN2)
jpayne@69 1731 * </pre>
jpayne@69 1732 *
jpayne@69 1733 * The default is to perform grouping according to locale data; most locales, but not all locales,
jpayne@69 1734 * enable it by default.
jpayne@69 1735 *
jpayne@69 1736 * @param strategy
jpayne@69 1737 * The grouping strategy to use.
jpayne@69 1738 * @return The fluent chain.
jpayne@69 1739 * @stable ICU 61
jpayne@69 1740 */
jpayne@69 1741 Derived grouping(UNumberGroupingStrategy strategy) const &;
jpayne@69 1742
jpayne@69 1743 /**
jpayne@69 1744 * Overload of grouping() for use on an rvalue reference.
jpayne@69 1745 *
jpayne@69 1746 * @param strategy
jpayne@69 1747 * The grouping strategy to use.
jpayne@69 1748 * @return The fluent chain.
jpayne@69 1749 * @see #grouping
jpayne@69 1750 * @stable ICU 62
jpayne@69 1751 */
jpayne@69 1752 Derived grouping(UNumberGroupingStrategy strategy) &&;
jpayne@69 1753
jpayne@69 1754 /**
jpayne@69 1755 * Specifies the minimum and maximum number of digits to render before the decimal mark.
jpayne@69 1756 *
jpayne@69 1757 * <ul>
jpayne@69 1758 * <li>Zero minimum integer digits: ".08"
jpayne@69 1759 * <li>One minimum integer digit: "0.08"
jpayne@69 1760 * <li>Two minimum integer digits: "00.08"
jpayne@69 1761 * </ul>
jpayne@69 1762 *
jpayne@69 1763 * <p>
jpayne@69 1764 * Pass this method the return value of {@link IntegerWidth#zeroFillTo}. For example:
jpayne@69 1765 *
jpayne@69 1766 * <pre>
jpayne@69 1767 * NumberFormatter::with().integerWidth(IntegerWidth::zeroFillTo(2))
jpayne@69 1768 * </pre>
jpayne@69 1769 *
jpayne@69 1770 * The default is to have one minimum integer digit.
jpayne@69 1771 *
jpayne@69 1772 * @param style
jpayne@69 1773 * The integer width to use.
jpayne@69 1774 * @return The fluent chain.
jpayne@69 1775 * @see IntegerWidth
jpayne@69 1776 * @stable ICU 60
jpayne@69 1777 */
jpayne@69 1778 Derived integerWidth(const IntegerWidth &style) const &;
jpayne@69 1779
jpayne@69 1780 /**
jpayne@69 1781 * Overload of integerWidth() for use on an rvalue reference.
jpayne@69 1782 *
jpayne@69 1783 * @param style
jpayne@69 1784 * The integer width to use.
jpayne@69 1785 * @return The fluent chain.
jpayne@69 1786 * @see #integerWidth
jpayne@69 1787 * @stable ICU 62
jpayne@69 1788 */
jpayne@69 1789 Derived integerWidth(const IntegerWidth &style) &&;
jpayne@69 1790
jpayne@69 1791 /**
jpayne@69 1792 * Specifies the symbols (decimal separator, grouping separator, percent sign, numerals, etc.) to use when rendering
jpayne@69 1793 * numbers.
jpayne@69 1794 *
jpayne@69 1795 * <ul>
jpayne@69 1796 * <li><em>en_US</em> symbols: "12,345.67"
jpayne@69 1797 * <li><em>fr_FR</em> symbols: "12&nbsp;345,67"
jpayne@69 1798 * <li><em>de_CH</em> symbols: "12’345.67"
jpayne@69 1799 * <li><em>my_MY</em> symbols: "၁၂,၃၄၅.၆၇"
jpayne@69 1800 * </ul>
jpayne@69 1801 *
jpayne@69 1802 * <p>
jpayne@69 1803 * Pass this method an instance of {@link DecimalFormatSymbols}. For example:
jpayne@69 1804 *
jpayne@69 1805 * <pre>
jpayne@69 1806 * NumberFormatter::with().symbols(DecimalFormatSymbols(Locale("de_CH"), status))
jpayne@69 1807 * </pre>
jpayne@69 1808 *
jpayne@69 1809 * <p>
jpayne@69 1810 * <strong>Note:</strong> DecimalFormatSymbols automatically chooses the best numbering system based on the locale.
jpayne@69 1811 * In the examples above, the first three are using the Latin numbering system, and the fourth is using the Myanmar
jpayne@69 1812 * numbering system.
jpayne@69 1813 *
jpayne@69 1814 * <p>
jpayne@69 1815 * <strong>Note:</strong> The instance of DecimalFormatSymbols will be copied: changes made to the symbols object
jpayne@69 1816 * after passing it into the fluent chain will not be seen.
jpayne@69 1817 *
jpayne@69 1818 * <p>
jpayne@69 1819 * <strong>Note:</strong> Calling this method will override any previously specified DecimalFormatSymbols
jpayne@69 1820 * or NumberingSystem.
jpayne@69 1821 *
jpayne@69 1822 * <p>
jpayne@69 1823 * The default is to choose the symbols based on the locale specified in the fluent chain.
jpayne@69 1824 *
jpayne@69 1825 * @param symbols
jpayne@69 1826 * The DecimalFormatSymbols to use.
jpayne@69 1827 * @return The fluent chain.
jpayne@69 1828 * @see DecimalFormatSymbols
jpayne@69 1829 * @stable ICU 60
jpayne@69 1830 */
jpayne@69 1831 Derived symbols(const DecimalFormatSymbols &symbols) const &;
jpayne@69 1832
jpayne@69 1833 /**
jpayne@69 1834 * Overload of symbols() for use on an rvalue reference.
jpayne@69 1835 *
jpayne@69 1836 * @param symbols
jpayne@69 1837 * The DecimalFormatSymbols to use.
jpayne@69 1838 * @return The fluent chain.
jpayne@69 1839 * @see #symbols
jpayne@69 1840 * @stable ICU 62
jpayne@69 1841 */
jpayne@69 1842 Derived symbols(const DecimalFormatSymbols &symbols) &&;
jpayne@69 1843
jpayne@69 1844 /**
jpayne@69 1845 * Specifies that the given numbering system should be used when fetching symbols.
jpayne@69 1846 *
jpayne@69 1847 * <ul>
jpayne@69 1848 * <li>Latin numbering system: "12,345"
jpayne@69 1849 * <li>Myanmar numbering system: "၁၂,၃၄၅"
jpayne@69 1850 * <li>Math Sans Bold numbering system: "𝟭𝟮,𝟯𝟰𝟱"
jpayne@69 1851 * </ul>
jpayne@69 1852 *
jpayne@69 1853 * <p>
jpayne@69 1854 * Pass this method an instance of {@link NumberingSystem}. For example, to force the locale to always use the Latin
jpayne@69 1855 * alphabet numbering system (ASCII digits):
jpayne@69 1856 *
jpayne@69 1857 * <pre>
jpayne@69 1858 * NumberFormatter::with().adoptSymbols(NumberingSystem::createInstanceByName("latn", status))
jpayne@69 1859 * </pre>
jpayne@69 1860 *
jpayne@69 1861 * <p>
jpayne@69 1862 * <strong>Note:</strong> Calling this method will override any previously specified DecimalFormatSymbols
jpayne@69 1863 * or NumberingSystem.
jpayne@69 1864 *
jpayne@69 1865 * <p>
jpayne@69 1866 * The default is to choose the best numbering system for the locale.
jpayne@69 1867 *
jpayne@69 1868 * <p>
jpayne@69 1869 * This method takes ownership of a pointer in order to work nicely with the NumberingSystem factory methods.
jpayne@69 1870 *
jpayne@69 1871 * @param symbols
jpayne@69 1872 * The NumberingSystem to use.
jpayne@69 1873 * @return The fluent chain.
jpayne@69 1874 * @see NumberingSystem
jpayne@69 1875 * @stable ICU 60
jpayne@69 1876 */
jpayne@69 1877 Derived adoptSymbols(NumberingSystem *symbols) const &;
jpayne@69 1878
jpayne@69 1879 /**
jpayne@69 1880 * Overload of adoptSymbols() for use on an rvalue reference.
jpayne@69 1881 *
jpayne@69 1882 * @param symbols
jpayne@69 1883 * The NumberingSystem to use.
jpayne@69 1884 * @return The fluent chain.
jpayne@69 1885 * @see #adoptSymbols
jpayne@69 1886 * @stable ICU 62
jpayne@69 1887 */
jpayne@69 1888 Derived adoptSymbols(NumberingSystem *symbols) &&;
jpayne@69 1889
jpayne@69 1890 /**
jpayne@69 1891 * Sets the width of the unit (measure unit or currency). Most common values:
jpayne@69 1892 *
jpayne@69 1893 * <ul>
jpayne@69 1894 * <li>Short: "$12.00", "12 m"
jpayne@69 1895 * <li>ISO Code: "USD 12.00"
jpayne@69 1896 * <li>Full name: "12.00 US dollars", "12 meters"
jpayne@69 1897 * </ul>
jpayne@69 1898 *
jpayne@69 1899 * <p>
jpayne@69 1900 * Pass an element from the {@link UNumberUnitWidth} enum to this setter. For example:
jpayne@69 1901 *
jpayne@69 1902 * <pre>
jpayne@69 1903 * NumberFormatter::with().unitWidth(UNumberUnitWidth::UNUM_UNIT_WIDTH_FULL_NAME)
jpayne@69 1904 * </pre>
jpayne@69 1905 *
jpayne@69 1906 * <p>
jpayne@69 1907 * The default is the SHORT width.
jpayne@69 1908 *
jpayne@69 1909 * @param width
jpayne@69 1910 * The width to use when rendering numbers.
jpayne@69 1911 * @return The fluent chain
jpayne@69 1912 * @see UNumberUnitWidth
jpayne@69 1913 * @stable ICU 60
jpayne@69 1914 */
jpayne@69 1915 Derived unitWidth(UNumberUnitWidth width) const &;
jpayne@69 1916
jpayne@69 1917 /**
jpayne@69 1918 * Overload of unitWidth() for use on an rvalue reference.
jpayne@69 1919 *
jpayne@69 1920 * @param width
jpayne@69 1921 * The width to use when rendering numbers.
jpayne@69 1922 * @return The fluent chain.
jpayne@69 1923 * @see #unitWidth
jpayne@69 1924 * @stable ICU 62
jpayne@69 1925 */
jpayne@69 1926 Derived unitWidth(UNumberUnitWidth width) &&;
jpayne@69 1927
jpayne@69 1928 /**
jpayne@69 1929 * Sets the plus/minus sign display strategy. Most common values:
jpayne@69 1930 *
jpayne@69 1931 * <ul>
jpayne@69 1932 * <li>Auto: "123", "-123"
jpayne@69 1933 * <li>Always: "+123", "-123"
jpayne@69 1934 * <li>Accounting: "$123", "($123)"
jpayne@69 1935 * </ul>
jpayne@69 1936 *
jpayne@69 1937 * <p>
jpayne@69 1938 * Pass an element from the {@link UNumberSignDisplay} enum to this setter. For example:
jpayne@69 1939 *
jpayne@69 1940 * <pre>
jpayne@69 1941 * NumberFormatter::with().sign(UNumberSignDisplay::UNUM_SIGN_ALWAYS)
jpayne@69 1942 * </pre>
jpayne@69 1943 *
jpayne@69 1944 * <p>
jpayne@69 1945 * The default is AUTO sign display.
jpayne@69 1946 *
jpayne@69 1947 * @param style
jpayne@69 1948 * The sign display strategy to use when rendering numbers.
jpayne@69 1949 * @return The fluent chain
jpayne@69 1950 * @see UNumberSignDisplay
jpayne@69 1951 * @stable ICU 60
jpayne@69 1952 */
jpayne@69 1953 Derived sign(UNumberSignDisplay style) const &;
jpayne@69 1954
jpayne@69 1955 /**
jpayne@69 1956 * Overload of sign() for use on an rvalue reference.
jpayne@69 1957 *
jpayne@69 1958 * @param style
jpayne@69 1959 * The sign display strategy to use when rendering numbers.
jpayne@69 1960 * @return The fluent chain.
jpayne@69 1961 * @see #sign
jpayne@69 1962 * @stable ICU 62
jpayne@69 1963 */
jpayne@69 1964 Derived sign(UNumberSignDisplay style) &&;
jpayne@69 1965
jpayne@69 1966 /**
jpayne@69 1967 * Sets the decimal separator display strategy. This affects integer numbers with no fraction part. Most common
jpayne@69 1968 * values:
jpayne@69 1969 *
jpayne@69 1970 * <ul>
jpayne@69 1971 * <li>Auto: "1"
jpayne@69 1972 * <li>Always: "1."
jpayne@69 1973 * </ul>
jpayne@69 1974 *
jpayne@69 1975 * <p>
jpayne@69 1976 * Pass an element from the {@link UNumberDecimalSeparatorDisplay} enum to this setter. For example:
jpayne@69 1977 *
jpayne@69 1978 * <pre>
jpayne@69 1979 * NumberFormatter::with().decimal(UNumberDecimalSeparatorDisplay::UNUM_DECIMAL_SEPARATOR_ALWAYS)
jpayne@69 1980 * </pre>
jpayne@69 1981 *
jpayne@69 1982 * <p>
jpayne@69 1983 * The default is AUTO decimal separator display.
jpayne@69 1984 *
jpayne@69 1985 * @param style
jpayne@69 1986 * The decimal separator display strategy to use when rendering numbers.
jpayne@69 1987 * @return The fluent chain
jpayne@69 1988 * @see UNumberDecimalSeparatorDisplay
jpayne@69 1989 * @stable ICU 60
jpayne@69 1990 */
jpayne@69 1991 Derived decimal(UNumberDecimalSeparatorDisplay style) const &;
jpayne@69 1992
jpayne@69 1993 /**
jpayne@69 1994 * Overload of decimal() for use on an rvalue reference.
jpayne@69 1995 *
jpayne@69 1996 * @param style
jpayne@69 1997 * The decimal separator display strategy to use when rendering numbers.
jpayne@69 1998 * @return The fluent chain.
jpayne@69 1999 * @see #decimal
jpayne@69 2000 * @stable ICU 62
jpayne@69 2001 */
jpayne@69 2002 Derived decimal(UNumberDecimalSeparatorDisplay style) &&;
jpayne@69 2003
jpayne@69 2004 /**
jpayne@69 2005 * Sets a scale (multiplier) to be used to scale the number by an arbitrary amount before formatting.
jpayne@69 2006 * Most common values:
jpayne@69 2007 *
jpayne@69 2008 * <ul>
jpayne@69 2009 * <li>Multiply by 100: useful for percentages.
jpayne@69 2010 * <li>Multiply by an arbitrary value: useful for unit conversions.
jpayne@69 2011 * </ul>
jpayne@69 2012 *
jpayne@69 2013 * <p>
jpayne@69 2014 * Pass an element from a {@link Scale} factory method to this setter. For example:
jpayne@69 2015 *
jpayne@69 2016 * <pre>
jpayne@69 2017 * NumberFormatter::with().scale(Scale::powerOfTen(2))
jpayne@69 2018 * </pre>
jpayne@69 2019 *
jpayne@69 2020 * <p>
jpayne@69 2021 * The default is to not apply any multiplier.
jpayne@69 2022 *
jpayne@69 2023 * @param scale
jpayne@69 2024 * The scale to apply when rendering numbers.
jpayne@69 2025 * @return The fluent chain
jpayne@69 2026 * @stable ICU 62
jpayne@69 2027 */
jpayne@69 2028 Derived scale(const Scale &scale) const &;
jpayne@69 2029
jpayne@69 2030 /**
jpayne@69 2031 * Overload of scale() for use on an rvalue reference.
jpayne@69 2032 *
jpayne@69 2033 * @param scale
jpayne@69 2034 * The scale to apply when rendering numbers.
jpayne@69 2035 * @return The fluent chain.
jpayne@69 2036 * @see #scale
jpayne@69 2037 * @stable ICU 62
jpayne@69 2038 */
jpayne@69 2039 Derived scale(const Scale &scale) &&;
jpayne@69 2040
jpayne@69 2041 #ifndef U_HIDE_INTERNAL_API
jpayne@69 2042
jpayne@69 2043 /**
jpayne@69 2044 * Set the padding strategy. May be added in the future; see #13338.
jpayne@69 2045 *
jpayne@69 2046 * @internal ICU 60: This API is ICU internal only.
jpayne@69 2047 */
jpayne@69 2048 Derived padding(const impl::Padder &padder) const &;
jpayne@69 2049
jpayne@69 2050 /** @internal */
jpayne@69 2051 Derived padding(const impl::Padder &padder) &&;
jpayne@69 2052
jpayne@69 2053 /**
jpayne@69 2054 * Internal fluent setter to support a custom regulation threshold. A threshold of 1 causes the data structures to
jpayne@69 2055 * be built right away. A threshold of 0 prevents the data structures from being built.
jpayne@69 2056 *
jpayne@69 2057 * @internal ICU 60: This API is ICU internal only.
jpayne@69 2058 */
jpayne@69 2059 Derived threshold(int32_t threshold) const &;
jpayne@69 2060
jpayne@69 2061 /** @internal */
jpayne@69 2062 Derived threshold(int32_t threshold) &&;
jpayne@69 2063
jpayne@69 2064 /**
jpayne@69 2065 * Internal fluent setter to overwrite the entire macros object.
jpayne@69 2066 *
jpayne@69 2067 * @internal ICU 60: This API is ICU internal only.
jpayne@69 2068 */
jpayne@69 2069 Derived macros(const impl::MacroProps& macros) const &;
jpayne@69 2070
jpayne@69 2071 /** @internal */
jpayne@69 2072 Derived macros(const impl::MacroProps& macros) &&;
jpayne@69 2073
jpayne@69 2074 /** @internal */
jpayne@69 2075 Derived macros(impl::MacroProps&& macros) const &;
jpayne@69 2076
jpayne@69 2077 /** @internal */
jpayne@69 2078 Derived macros(impl::MacroProps&& macros) &&;
jpayne@69 2079
jpayne@69 2080 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 2081
jpayne@69 2082 /**
jpayne@69 2083 * Creates a skeleton string representation of this number formatter. A skeleton string is a
jpayne@69 2084 * locale-agnostic serialized form of a number formatter.
jpayne@69 2085 *
jpayne@69 2086 * Not all options are capable of being represented in the skeleton string; for example, a
jpayne@69 2087 * DecimalFormatSymbols object. If any such option is encountered, the error code is set to
jpayne@69 2088 * U_UNSUPPORTED_ERROR.
jpayne@69 2089 *
jpayne@69 2090 * The returned skeleton is in normalized form, such that two number formatters with equivalent
jpayne@69 2091 * behavior should produce the same skeleton.
jpayne@69 2092 *
jpayne@69 2093 * @return A number skeleton string with behavior corresponding to this number formatter.
jpayne@69 2094 * @stable ICU 62
jpayne@69 2095 */
jpayne@69 2096 UnicodeString toSkeleton(UErrorCode& status) const;
jpayne@69 2097
jpayne@69 2098 /**
jpayne@69 2099 * Returns the current (Un)LocalizedNumberFormatter as a LocalPointer
jpayne@69 2100 * wrapping a heap-allocated copy of the current object.
jpayne@69 2101 *
jpayne@69 2102 * This is equivalent to new-ing the move constructor with a value object
jpayne@69 2103 * as the argument.
jpayne@69 2104 *
jpayne@69 2105 * @return A wrapped (Un)LocalizedNumberFormatter pointer, or a wrapped
jpayne@69 2106 * nullptr on failure.
jpayne@69 2107 * @stable ICU 64
jpayne@69 2108 */
jpayne@69 2109 LocalPointer<Derived> clone() const &;
jpayne@69 2110
jpayne@69 2111 /**
jpayne@69 2112 * Overload of clone for use on an rvalue reference.
jpayne@69 2113 *
jpayne@69 2114 * @return A wrapped (Un)LocalizedNumberFormatter pointer, or a wrapped
jpayne@69 2115 * nullptr on failure.
jpayne@69 2116 * @stable ICU 64
jpayne@69 2117 */
jpayne@69 2118 LocalPointer<Derived> clone() &&;
jpayne@69 2119
jpayne@69 2120 /**
jpayne@69 2121 * Sets the UErrorCode if an error occurred in the fluent chain.
jpayne@69 2122 * Preserves older error codes in the outErrorCode.
jpayne@69 2123 * @return TRUE if U_FAILURE(outErrorCode)
jpayne@69 2124 * @stable ICU 60
jpayne@69 2125 */
jpayne@69 2126 UBool copyErrorTo(UErrorCode &outErrorCode) const {
jpayne@69 2127 if (U_FAILURE(outErrorCode)) {
jpayne@69 2128 // Do not overwrite the older error code
jpayne@69 2129 return TRUE;
jpayne@69 2130 }
jpayne@69 2131 fMacros.copyErrorTo(outErrorCode);
jpayne@69 2132 return U_FAILURE(outErrorCode);
jpayne@69 2133 }
jpayne@69 2134
jpayne@69 2135 // NOTE: Uses default copy and move constructors.
jpayne@69 2136
jpayne@69 2137 private:
jpayne@69 2138 impl::MacroProps fMacros;
jpayne@69 2139
jpayne@69 2140 // Don't construct me directly! Use (Un)LocalizedNumberFormatter.
jpayne@69 2141 NumberFormatterSettings() = default;
jpayne@69 2142
jpayne@69 2143 friend class LocalizedNumberFormatter;
jpayne@69 2144 friend class UnlocalizedNumberFormatter;
jpayne@69 2145
jpayne@69 2146 // Give NumberRangeFormatter access to the MacroProps
jpayne@69 2147 friend void impl::touchRangeLocales(impl::RangeMacroProps& macros);
jpayne@69 2148 friend class impl::NumberRangeFormatterImpl;
jpayne@69 2149 };
jpayne@69 2150
jpayne@69 2151 /**
jpayne@69 2152 * A NumberFormatter that does not yet have a locale. In order to format numbers, a locale must be specified.
jpayne@69 2153 *
jpayne@69 2154 * Instances of this class are immutable and thread-safe.
jpayne@69 2155 *
jpayne@69 2156 * @see NumberFormatter
jpayne@69 2157 * @stable ICU 60
jpayne@69 2158 */
jpayne@69 2159 class U_I18N_API UnlocalizedNumberFormatter
jpayne@69 2160 : public NumberFormatterSettings<UnlocalizedNumberFormatter>, public UMemory {
jpayne@69 2161
jpayne@69 2162 public:
jpayne@69 2163 /**
jpayne@69 2164 * Associate the given locale with the number formatter. The locale is used for picking the appropriate symbols,
jpayne@69 2165 * formats, and other data for number display.
jpayne@69 2166 *
jpayne@69 2167 * @param locale
jpayne@69 2168 * The locale to use when loading data for number formatting.
jpayne@69 2169 * @return The fluent chain.
jpayne@69 2170 * @stable ICU 60
jpayne@69 2171 */
jpayne@69 2172 LocalizedNumberFormatter locale(const icu::Locale &locale) const &;
jpayne@69 2173
jpayne@69 2174 /**
jpayne@69 2175 * Overload of locale() for use on an rvalue reference.
jpayne@69 2176 *
jpayne@69 2177 * @param locale
jpayne@69 2178 * The locale to use when loading data for number formatting.
jpayne@69 2179 * @return The fluent chain.
jpayne@69 2180 * @see #locale
jpayne@69 2181 * @stable ICU 62
jpayne@69 2182 */
jpayne@69 2183 LocalizedNumberFormatter locale(const icu::Locale &locale) &&;
jpayne@69 2184
jpayne@69 2185 /**
jpayne@69 2186 * Default constructor: puts the formatter into a valid but undefined state.
jpayne@69 2187 *
jpayne@69 2188 * @stable ICU 62
jpayne@69 2189 */
jpayne@69 2190 UnlocalizedNumberFormatter() = default;
jpayne@69 2191
jpayne@69 2192 /**
jpayne@69 2193 * Returns a copy of this UnlocalizedNumberFormatter.
jpayne@69 2194 * @stable ICU 60
jpayne@69 2195 */
jpayne@69 2196 UnlocalizedNumberFormatter(const UnlocalizedNumberFormatter &other);
jpayne@69 2197
jpayne@69 2198 /**
jpayne@69 2199 * Move constructor:
jpayne@69 2200 * The source UnlocalizedNumberFormatter will be left in a valid but undefined state.
jpayne@69 2201 * @stable ICU 62
jpayne@69 2202 */
jpayne@69 2203 UnlocalizedNumberFormatter(UnlocalizedNumberFormatter&& src) U_NOEXCEPT;
jpayne@69 2204
jpayne@69 2205 /**
jpayne@69 2206 * Copy assignment operator.
jpayne@69 2207 * @stable ICU 62
jpayne@69 2208 */
jpayne@69 2209 UnlocalizedNumberFormatter& operator=(const UnlocalizedNumberFormatter& other);
jpayne@69 2210
jpayne@69 2211 /**
jpayne@69 2212 * Move assignment operator:
jpayne@69 2213 * The source UnlocalizedNumberFormatter will be left in a valid but undefined state.
jpayne@69 2214 * @stable ICU 62
jpayne@69 2215 */
jpayne@69 2216 UnlocalizedNumberFormatter& operator=(UnlocalizedNumberFormatter&& src) U_NOEXCEPT;
jpayne@69 2217
jpayne@69 2218 private:
jpayne@69 2219 explicit UnlocalizedNumberFormatter(const NumberFormatterSettings<UnlocalizedNumberFormatter>& other);
jpayne@69 2220
jpayne@69 2221 explicit UnlocalizedNumberFormatter(
jpayne@69 2222 NumberFormatterSettings<UnlocalizedNumberFormatter>&& src) U_NOEXCEPT;
jpayne@69 2223
jpayne@69 2224 // To give the fluent setters access to this class's constructor:
jpayne@69 2225 friend class NumberFormatterSettings<UnlocalizedNumberFormatter>;
jpayne@69 2226
jpayne@69 2227 // To give NumberFormatter::with() access to this class's constructor:
jpayne@69 2228 friend class NumberFormatter;
jpayne@69 2229 };
jpayne@69 2230
jpayne@69 2231 /**
jpayne@69 2232 * A NumberFormatter that has a locale associated with it; this means .format() methods are available.
jpayne@69 2233 *
jpayne@69 2234 * Instances of this class are immutable and thread-safe.
jpayne@69 2235 *
jpayne@69 2236 * @see NumberFormatter
jpayne@69 2237 * @stable ICU 60
jpayne@69 2238 */
jpayne@69 2239 class U_I18N_API LocalizedNumberFormatter
jpayne@69 2240 : public NumberFormatterSettings<LocalizedNumberFormatter>, public UMemory {
jpayne@69 2241 public:
jpayne@69 2242 /**
jpayne@69 2243 * Format the given integer number to a string using the settings specified in the NumberFormatter fluent
jpayne@69 2244 * setting chain.
jpayne@69 2245 *
jpayne@69 2246 * @param value
jpayne@69 2247 * The number to format.
jpayne@69 2248 * @param status
jpayne@69 2249 * Set to an ErrorCode if one occurred in the setter chain or during formatting.
jpayne@69 2250 * @return A FormattedNumber object; call .toString() to get the string.
jpayne@69 2251 * @stable ICU 60
jpayne@69 2252 */
jpayne@69 2253 FormattedNumber formatInt(int64_t value, UErrorCode &status) const;
jpayne@69 2254
jpayne@69 2255 /**
jpayne@69 2256 * Format the given float or double to a string using the settings specified in the NumberFormatter fluent setting
jpayne@69 2257 * chain.
jpayne@69 2258 *
jpayne@69 2259 * @param value
jpayne@69 2260 * The number to format.
jpayne@69 2261 * @param status
jpayne@69 2262 * Set to an ErrorCode if one occurred in the setter chain or during formatting.
jpayne@69 2263 * @return A FormattedNumber object; call .toString() to get the string.
jpayne@69 2264 * @stable ICU 60
jpayne@69 2265 */
jpayne@69 2266 FormattedNumber formatDouble(double value, UErrorCode &status) const;
jpayne@69 2267
jpayne@69 2268 /**
jpayne@69 2269 * Format the given decimal number to a string using the settings
jpayne@69 2270 * specified in the NumberFormatter fluent setting chain.
jpayne@69 2271 * The syntax of the unformatted number is a "numeric string"
jpayne@69 2272 * as defined in the Decimal Arithmetic Specification, available at
jpayne@69 2273 * http://speleotrove.com/decimal
jpayne@69 2274 *
jpayne@69 2275 * @param value
jpayne@69 2276 * The number to format.
jpayne@69 2277 * @param status
jpayne@69 2278 * Set to an ErrorCode if one occurred in the setter chain or during formatting.
jpayne@69 2279 * @return A FormattedNumber object; call .toString() to get the string.
jpayne@69 2280 * @stable ICU 60
jpayne@69 2281 */
jpayne@69 2282 FormattedNumber formatDecimal(StringPiece value, UErrorCode& status) const;
jpayne@69 2283
jpayne@69 2284 #ifndef U_HIDE_INTERNAL_API
jpayne@69 2285
jpayne@69 2286 /** Internal method.
jpayne@69 2287 * @internal
jpayne@69 2288 */
jpayne@69 2289 FormattedNumber formatDecimalQuantity(const impl::DecimalQuantity& dq, UErrorCode& status) const;
jpayne@69 2290
jpayne@69 2291 /** Internal method for DecimalFormat compatibility.
jpayne@69 2292 * @internal
jpayne@69 2293 */
jpayne@69 2294 void getAffixImpl(bool isPrefix, bool isNegative, UnicodeString& result, UErrorCode& status) const;
jpayne@69 2295
jpayne@69 2296 /**
jpayne@69 2297 * Internal method for testing.
jpayne@69 2298 * @internal
jpayne@69 2299 */
jpayne@69 2300 const impl::NumberFormatterImpl* getCompiled() const;
jpayne@69 2301
jpayne@69 2302 /**
jpayne@69 2303 * Internal method for testing.
jpayne@69 2304 * @internal
jpayne@69 2305 */
jpayne@69 2306 int32_t getCallCount() const;
jpayne@69 2307
jpayne@69 2308 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 2309
jpayne@69 2310 /**
jpayne@69 2311 * Creates a representation of this LocalizedNumberFormat as an icu::Format, enabling the use
jpayne@69 2312 * of this number formatter with APIs that need an object of that type, such as MessageFormat.
jpayne@69 2313 *
jpayne@69 2314 * This API is not intended to be used other than for enabling API compatibility. The formatDouble,
jpayne@69 2315 * formatInt, and formatDecimal methods should normally be used when formatting numbers, not the Format
jpayne@69 2316 * object returned by this method.
jpayne@69 2317 *
jpayne@69 2318 * The caller owns the returned object and must delete it when finished.
jpayne@69 2319 *
jpayne@69 2320 * @return A Format wrapping this LocalizedNumberFormatter.
jpayne@69 2321 * @stable ICU 62
jpayne@69 2322 */
jpayne@69 2323 Format* toFormat(UErrorCode& status) const;
jpayne@69 2324
jpayne@69 2325 /**
jpayne@69 2326 * Default constructor: puts the formatter into a valid but undefined state.
jpayne@69 2327 *
jpayne@69 2328 * @stable ICU 62
jpayne@69 2329 */
jpayne@69 2330 LocalizedNumberFormatter() = default;
jpayne@69 2331
jpayne@69 2332 /**
jpayne@69 2333 * Returns a copy of this LocalizedNumberFormatter.
jpayne@69 2334 * @stable ICU 60
jpayne@69 2335 */
jpayne@69 2336 LocalizedNumberFormatter(const LocalizedNumberFormatter &other);
jpayne@69 2337
jpayne@69 2338 /**
jpayne@69 2339 * Move constructor:
jpayne@69 2340 * The source LocalizedNumberFormatter will be left in a valid but undefined state.
jpayne@69 2341 * @stable ICU 62
jpayne@69 2342 */
jpayne@69 2343 LocalizedNumberFormatter(LocalizedNumberFormatter&& src) U_NOEXCEPT;
jpayne@69 2344
jpayne@69 2345 /**
jpayne@69 2346 * Copy assignment operator.
jpayne@69 2347 * @stable ICU 62
jpayne@69 2348 */
jpayne@69 2349 LocalizedNumberFormatter& operator=(const LocalizedNumberFormatter& other);
jpayne@69 2350
jpayne@69 2351 /**
jpayne@69 2352 * Move assignment operator:
jpayne@69 2353 * The source LocalizedNumberFormatter will be left in a valid but undefined state.
jpayne@69 2354 * @stable ICU 62
jpayne@69 2355 */
jpayne@69 2356 LocalizedNumberFormatter& operator=(LocalizedNumberFormatter&& src) U_NOEXCEPT;
jpayne@69 2357
jpayne@69 2358 #ifndef U_HIDE_INTERNAL_API
jpayne@69 2359
jpayne@69 2360 /**
jpayne@69 2361 * This is the core entrypoint to the number formatting pipeline. It performs self-regulation: a static code path
jpayne@69 2362 * for the first few calls, and compiling a more efficient data structure if called repeatedly.
jpayne@69 2363 *
jpayne@69 2364 * <p>
jpayne@69 2365 * This function is very hot, being called in every call to the number formatting pipeline.
jpayne@69 2366 *
jpayne@69 2367 * @param results
jpayne@69 2368 * The results object. This method will mutate it to save the results.
jpayne@69 2369 * @param status
jpayne@69 2370 * @internal
jpayne@69 2371 */
jpayne@69 2372 void formatImpl(impl::UFormattedNumberData *results, UErrorCode &status) const;
jpayne@69 2373
jpayne@69 2374 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 2375
jpayne@69 2376 /**
jpayne@69 2377 * Destruct this LocalizedNumberFormatter, cleaning up any memory it might own.
jpayne@69 2378 * @stable ICU 60
jpayne@69 2379 */
jpayne@69 2380 ~LocalizedNumberFormatter();
jpayne@69 2381
jpayne@69 2382 private:
jpayne@69 2383 // Note: fCompiled can't be a LocalPointer because impl::NumberFormatterImpl is defined in an internal
jpayne@69 2384 // header, and LocalPointer needs the full class definition in order to delete the instance.
jpayne@69 2385 const impl::NumberFormatterImpl* fCompiled {nullptr};
jpayne@69 2386 char fUnsafeCallCount[8] {}; // internally cast to u_atomic_int32_t
jpayne@69 2387
jpayne@69 2388 explicit LocalizedNumberFormatter(const NumberFormatterSettings<LocalizedNumberFormatter>& other);
jpayne@69 2389
jpayne@69 2390 explicit LocalizedNumberFormatter(NumberFormatterSettings<LocalizedNumberFormatter>&& src) U_NOEXCEPT;
jpayne@69 2391
jpayne@69 2392 LocalizedNumberFormatter(const impl::MacroProps &macros, const Locale &locale);
jpayne@69 2393
jpayne@69 2394 LocalizedNumberFormatter(impl::MacroProps &&macros, const Locale &locale);
jpayne@69 2395
jpayne@69 2396 void clear();
jpayne@69 2397
jpayne@69 2398 void lnfMoveHelper(LocalizedNumberFormatter&& src);
jpayne@69 2399
jpayne@69 2400 /**
jpayne@69 2401 * @return true if the compiled formatter is available.
jpayne@69 2402 */
jpayne@69 2403 bool computeCompiled(UErrorCode& status) const;
jpayne@69 2404
jpayne@69 2405 // To give the fluent setters access to this class's constructor:
jpayne@69 2406 friend class NumberFormatterSettings<UnlocalizedNumberFormatter>;
jpayne@69 2407 friend class NumberFormatterSettings<LocalizedNumberFormatter>;
jpayne@69 2408
jpayne@69 2409 // To give UnlocalizedNumberFormatter::locale() access to this class's constructor:
jpayne@69 2410 friend class UnlocalizedNumberFormatter;
jpayne@69 2411 };
jpayne@69 2412
jpayne@69 2413 #if (U_PF_WINDOWS <= U_PLATFORM && U_PLATFORM <= U_PF_CYGWIN) && defined(_MSC_VER)
jpayne@69 2414 // Warning 4661.
jpayne@69 2415 #pragma warning(pop)
jpayne@69 2416 #endif
jpayne@69 2417
jpayne@69 2418 /**
jpayne@69 2419 * The result of a number formatting operation. This class allows the result to be exported in several data types,
jpayne@69 2420 * including a UnicodeString and a FieldPositionIterator.
jpayne@69 2421 *
jpayne@69 2422 * Instances of this class are immutable and thread-safe.
jpayne@69 2423 *
jpayne@69 2424 * @stable ICU 60
jpayne@69 2425 */
jpayne@69 2426 class U_I18N_API FormattedNumber : public UMemory, public FormattedValue {
jpayne@69 2427 public:
jpayne@69 2428
jpayne@69 2429 /**
jpayne@69 2430 * Default constructor; makes an empty FormattedNumber.
jpayne@69 2431 * @stable ICU 64
jpayne@69 2432 */
jpayne@69 2433 FormattedNumber()
jpayne@69 2434 : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {}
jpayne@69 2435
jpayne@69 2436 /**
jpayne@69 2437 * Move constructor: Leaves the source FormattedNumber in an undefined state.
jpayne@69 2438 * @stable ICU 62
jpayne@69 2439 */
jpayne@69 2440 FormattedNumber(FormattedNumber&& src) U_NOEXCEPT;
jpayne@69 2441
jpayne@69 2442 /**
jpayne@69 2443 * Destruct an instance of FormattedNumber.
jpayne@69 2444 * @stable ICU 60
jpayne@69 2445 */
jpayne@69 2446 virtual ~FormattedNumber() U_OVERRIDE;
jpayne@69 2447
jpayne@69 2448 /** Copying not supported; use move constructor instead. */
jpayne@69 2449 FormattedNumber(const FormattedNumber&) = delete;
jpayne@69 2450
jpayne@69 2451 /** Copying not supported; use move assignment instead. */
jpayne@69 2452 FormattedNumber& operator=(const FormattedNumber&) = delete;
jpayne@69 2453
jpayne@69 2454 /**
jpayne@69 2455 * Move assignment: Leaves the source FormattedNumber in an undefined state.
jpayne@69 2456 * @stable ICU 62
jpayne@69 2457 */
jpayne@69 2458 FormattedNumber& operator=(FormattedNumber&& src) U_NOEXCEPT;
jpayne@69 2459
jpayne@69 2460 // Copybrief: this method is older than the parent method
jpayne@69 2461 /**
jpayne@69 2462 * @copybrief FormattedValue::toString()
jpayne@69 2463 *
jpayne@69 2464 * For more information, see FormattedValue::toString()
jpayne@69 2465 *
jpayne@69 2466 * @stable ICU 62
jpayne@69 2467 */
jpayne@69 2468 UnicodeString toString(UErrorCode& status) const U_OVERRIDE;
jpayne@69 2469
jpayne@69 2470 // Copydoc: this method is new in ICU 64
jpayne@69 2471 /** @copydoc FormattedValue::toTempString() */
jpayne@69 2472 UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE;
jpayne@69 2473
jpayne@69 2474 // Copybrief: this method is older than the parent method
jpayne@69 2475 /**
jpayne@69 2476 * @copybrief FormattedValue::appendTo()
jpayne@69 2477 *
jpayne@69 2478 * For more information, see FormattedValue::appendTo()
jpayne@69 2479 *
jpayne@69 2480 * @stable ICU 62
jpayne@69 2481 */
jpayne@69 2482 Appendable &appendTo(Appendable& appendable, UErrorCode& status) const U_OVERRIDE;
jpayne@69 2483
jpayne@69 2484 // Copydoc: this method is new in ICU 64
jpayne@69 2485 /** @copydoc FormattedValue::nextPosition() */
jpayne@69 2486 UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE;
jpayne@69 2487
jpayne@69 2488 #ifndef U_HIDE_DRAFT_API
jpayne@69 2489 /**
jpayne@69 2490 * Export the formatted number as a "numeric string" conforming to the
jpayne@69 2491 * syntax defined in the Decimal Arithmetic Specification, available at
jpayne@69 2492 * http://speleotrove.com/decimal
jpayne@69 2493 *
jpayne@69 2494 * This endpoint is useful for obtaining the exact number being printed
jpayne@69 2495 * after scaling and rounding have been applied by the number formatter.
jpayne@69 2496 *
jpayne@69 2497 * Example call site:
jpayne@69 2498 *
jpayne@69 2499 * auto decimalNumber = fn.toDecimalNumber<std::string>(status);
jpayne@69 2500 *
jpayne@69 2501 * @tparam StringClass A string class compatible with StringByteSink;
jpayne@69 2502 * for example, std::string.
jpayne@69 2503 * @param status Set if an error occurs.
jpayne@69 2504 * @return A StringClass containing the numeric string.
jpayne@69 2505 * @draft ICU 65
jpayne@69 2506 */
jpayne@69 2507 template<typename StringClass>
jpayne@69 2508 inline StringClass toDecimalNumber(UErrorCode& status) const;
jpayne@69 2509 #endif // U_HIDE_DRAFT_API
jpayne@69 2510
jpayne@69 2511 #ifndef U_HIDE_INTERNAL_API
jpayne@69 2512
jpayne@69 2513 /**
jpayne@69 2514 * Gets the raw DecimalQuantity for plural rule selection.
jpayne@69 2515 * @internal
jpayne@69 2516 */
jpayne@69 2517 void getDecimalQuantity(impl::DecimalQuantity& output, UErrorCode& status) const;
jpayne@69 2518
jpayne@69 2519 /**
jpayne@69 2520 * Populates the mutable builder type FieldPositionIteratorHandler.
jpayne@69 2521 * @internal
jpayne@69 2522 */
jpayne@69 2523 void getAllFieldPositionsImpl(FieldPositionIteratorHandler& fpih, UErrorCode& status) const;
jpayne@69 2524
jpayne@69 2525 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 2526
jpayne@69 2527 private:
jpayne@69 2528 // Can't use LocalPointer because UFormattedNumberData is forward-declared
jpayne@69 2529 const impl::UFormattedNumberData *fData;
jpayne@69 2530
jpayne@69 2531 // Error code for the terminal methods
jpayne@69 2532 UErrorCode fErrorCode;
jpayne@69 2533
jpayne@69 2534 /**
jpayne@69 2535 * Internal constructor from data type. Adopts the data pointer.
jpayne@69 2536 * @internal
jpayne@69 2537 */
jpayne@69 2538 explicit FormattedNumber(impl::UFormattedNumberData *results)
jpayne@69 2539 : fData(results), fErrorCode(U_ZERO_ERROR) {}
jpayne@69 2540
jpayne@69 2541 explicit FormattedNumber(UErrorCode errorCode)
jpayne@69 2542 : fData(nullptr), fErrorCode(errorCode) {}
jpayne@69 2543
jpayne@69 2544 // TODO(ICU-20775): Propose this as API.
jpayne@69 2545 void toDecimalNumber(ByteSink& sink, UErrorCode& status) const;
jpayne@69 2546
jpayne@69 2547 // To give LocalizedNumberFormatter format methods access to this class's constructor:
jpayne@69 2548 friend class LocalizedNumberFormatter;
jpayne@69 2549
jpayne@69 2550 // To give C API access to internals
jpayne@69 2551 friend struct impl::UFormattedNumberImpl;
jpayne@69 2552 };
jpayne@69 2553
jpayne@69 2554 #ifndef U_HIDE_DRAFT_API
jpayne@69 2555 // Note: This is draft ICU 65
jpayne@69 2556 template<typename StringClass>
jpayne@69 2557 StringClass FormattedNumber::toDecimalNumber(UErrorCode& status) const {
jpayne@69 2558 StringClass result;
jpayne@69 2559 StringByteSink<StringClass> sink(&result);
jpayne@69 2560 toDecimalNumber(sink, status);
jpayne@69 2561 return result;
jpayne@69 2562 }
jpayne@69 2563 #endif // U_HIDE_DRAFT_API
jpayne@69 2564
jpayne@69 2565 /**
jpayne@69 2566 * See the main description in numberformatter.h for documentation and examples.
jpayne@69 2567 *
jpayne@69 2568 * @stable ICU 60
jpayne@69 2569 */
jpayne@69 2570 class U_I18N_API NumberFormatter final {
jpayne@69 2571 public:
jpayne@69 2572 /**
jpayne@69 2573 * Call this method at the beginning of a NumberFormatter fluent chain in which the locale is not currently known at
jpayne@69 2574 * the call site.
jpayne@69 2575 *
jpayne@69 2576 * @return An {@link UnlocalizedNumberFormatter}, to be used for chaining.
jpayne@69 2577 * @stable ICU 60
jpayne@69 2578 */
jpayne@69 2579 static UnlocalizedNumberFormatter with();
jpayne@69 2580
jpayne@69 2581 /**
jpayne@69 2582 * Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known at the call
jpayne@69 2583 * site.
jpayne@69 2584 *
jpayne@69 2585 * @param locale
jpayne@69 2586 * The locale from which to load formats and symbols for number formatting.
jpayne@69 2587 * @return A {@link LocalizedNumberFormatter}, to be used for chaining.
jpayne@69 2588 * @stable ICU 60
jpayne@69 2589 */
jpayne@69 2590 static LocalizedNumberFormatter withLocale(const Locale &locale);
jpayne@69 2591
jpayne@69 2592 /**
jpayne@69 2593 * Call this method at the beginning of a NumberFormatter fluent chain to create an instance based
jpayne@69 2594 * on a given number skeleton string.
jpayne@69 2595 *
jpayne@69 2596 * It is possible for an error to occur while parsing. See the overload of this method if you are
jpayne@69 2597 * interested in the location of a possible parse error.
jpayne@69 2598 *
jpayne@69 2599 * @param skeleton
jpayne@69 2600 * The skeleton string off of which to base this NumberFormatter.
jpayne@69 2601 * @param status
jpayne@69 2602 * Set to U_NUMBER_SKELETON_SYNTAX_ERROR if the skeleton was invalid.
jpayne@69 2603 * @return An UnlocalizedNumberFormatter, to be used for chaining.
jpayne@69 2604 * @stable ICU 62
jpayne@69 2605 */
jpayne@69 2606 static UnlocalizedNumberFormatter forSkeleton(const UnicodeString& skeleton, UErrorCode& status);
jpayne@69 2607
jpayne@69 2608 /**
jpayne@69 2609 * Call this method at the beginning of a NumberFormatter fluent chain to create an instance based
jpayne@69 2610 * on a given number skeleton string.
jpayne@69 2611 *
jpayne@69 2612 * If an error occurs while parsing the skeleton string, the offset into the skeleton string at
jpayne@69 2613 * which the error occurred will be saved into the UParseError, if provided.
jpayne@69 2614 *
jpayne@69 2615 * @param skeleton
jpayne@69 2616 * The skeleton string off of which to base this NumberFormatter.
jpayne@69 2617 * @param perror
jpayne@69 2618 * A parse error struct populated if an error occurs when parsing.
jpayne@69 2619 * If no error occurs, perror.offset will be set to -1.
jpayne@69 2620 * @param status
jpayne@69 2621 * Set to U_NUMBER_SKELETON_SYNTAX_ERROR if the skeleton was invalid.
jpayne@69 2622 * @return An UnlocalizedNumberFormatter, to be used for chaining.
jpayne@69 2623 * @stable ICU 64
jpayne@69 2624 */
jpayne@69 2625 static UnlocalizedNumberFormatter forSkeleton(const UnicodeString& skeleton,
jpayne@69 2626 UParseError& perror, UErrorCode& status);
jpayne@69 2627
jpayne@69 2628 /**
jpayne@69 2629 * Use factory methods instead of the constructor to create a NumberFormatter.
jpayne@69 2630 */
jpayne@69 2631 NumberFormatter() = delete;
jpayne@69 2632 };
jpayne@69 2633
jpayne@69 2634 } // namespace number
jpayne@69 2635 U_NAMESPACE_END
jpayne@69 2636
jpayne@69 2637 #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69 2638
jpayne@69 2639 #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69 2640
jpayne@69 2641 #endif // __NUMBERFORMATTER_H__
jpayne@69 2642