1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 ********************************************************************************
5 * Copyright (C) 1997-2016, International Business Machines Corporation and others.
6 * All Rights Reserved.
7 ********************************************************************************
8 *
9 * File NUMFMT.H
10 *
11 * Modification History:
12 *
13 * Date Name Description
14 * 02/19/97 aliu Converted from java.
15 * 03/18/97 clhuang Updated per C++ implementation.
16 * 04/17/97 aliu Changed DigitCount to int per code review.
17 * 07/20/98 stephen JDK 1.2 sync up. Added scientific support.
18 * Changed naming conventions to match C++ guidelines
19 * Deprecated Java style constants (eg, INTEGER_FIELD)
20 ********************************************************************************
21 */
22
23 #ifndef NUMFMT_H
24 #define NUMFMT_H
25
26
27 #include "unicode/utypes.h"
28
29 #if U_SHOW_CPLUSPLUS_API
30
31 /**
32 * \file
33 * \brief C++ API: Compatibility APIs for number formatting.
34 */
35
36 #if !UCONFIG_NO_FORMATTING
37
38 #include "unicode/unistr.h"
39 #include "unicode/format.h"
40 #include "unicode/unum.h" // UNumberFormatStyle
41 #include "unicode/locid.h"
42 #include "unicode/stringpiece.h"
43 #include "unicode/curramt.h"
44 #include "unicode/udisplaycontext.h"
45
46 class NumberFormatTest;
47
48 U_NAMESPACE_BEGIN
49
50 class SharedNumberFormat;
51
52 #if !UCONFIG_NO_SERVICE
53 class NumberFormatFactory;
54 class StringEnumeration;
55 #endif
56
57 /**
58 * <p><strong>IMPORTANT:</strong> New users are strongly encouraged to see if
59 * numberformatter.h fits their use case. Although not deprecated, this header
60 * is provided for backwards compatibility only.
61 *
62 * Abstract base class for all number formats. Provides interface for
63 * formatting and parsing a number. Also provides methods for
64 * determining which locales have number formats, and what their names
65 * are.
66 *
67 * \headerfile unicode/numfmt.h "unicode/numfmt.h"
68 * <P>
69 * NumberFormat helps you to format and parse numbers for any locale.
70 * Your code can be completely independent of the locale conventions
71 * for decimal points, thousands-separators, or even the particular
72 * decimal digits used, or whether the number format is even decimal.
73 * <P>
74 * To format a number for the current Locale, use one of the static
75 * factory methods:
76 * \code
77 * #include <iostream>
78 * #include "unicode/numfmt.h"
79 * #include "unicode/unistr.h"
80 * #include "unicode/ustream.h"
81 * using namespace std;
82 *
83 * int main() {
84 * double myNumber = 7.0;
85 * UnicodeString myString;
86 * UErrorCode success = U_ZERO_ERROR;
87 * NumberFormat* nf = NumberFormat::createInstance(success);
88 * nf->format(myNumber, myString);
89 * cout << " Example 1: " << myString << endl;
90 * }
91 * \endcode
92 * Note that there are additional factory methods within subclasses of
93 * NumberFormat.
94 * <P>
95 * If you are formatting multiple numbers, it is more efficient to get
96 * the format and use it multiple times so that the system doesn't
97 * have to fetch the information about the local language and country
98 * conventions multiple times.
99 * \code
100 * UnicodeString myString;
101 * UErrorCode success = U_ZERO_ERROR;
102 * NumberFormat *nf = NumberFormat::createInstance( success );
103 * for (int32_t number: {123, 3333, -1234567}) {
104 * nf->format(number, myString);
105 * myString += "; ";
106 * }
107 * cout << " Example 2: " << myString << endl;
108 * \endcode
109 * To format a number for a different Locale, specify it in the
110 * call to \c createInstance().
111 * \code
112 * nf = NumberFormat::createInstance(Locale::getFrench(), success);
113 * \endcode
114 * You can use a \c NumberFormat to parse also.
115 * \code
116 * UErrorCode success;
117 * Formattable result(-999); // initialized with error code
118 * nf->parse(myString, result, success);
119 * \endcode
120 * Use \c createInstance() to get the normal number format for a \c Locale.
121 * There are other static factory methods available. Use \c createCurrencyInstance()
122 * to get the currency number format for that country. Use \c createPercentInstance()
123 * to get a format for displaying percentages. With this format, a
124 * fraction from 0.53 is displayed as 53%.
125 * <P>
126 * The type of number formatting can be specified by passing a 'style' parameter to \c createInstance().
127 * For example, use\n
128 * \c createInstance(locale, UNUM_DECIMAL, errorCode) to get the normal number format,\n
129 * \c createInstance(locale, UNUM_PERCENT, errorCode) to get a format for displaying percentage,\n
130 * \c createInstance(locale, UNUM_SCIENTIFIC, errorCode) to get a format for displaying scientific number,\n
131 * \c createInstance(locale, UNUM_CURRENCY, errorCode) to get the currency number format,
132 * in which the currency is represented by its symbol, for example, "$3.00".\n
133 * \c createInstance(locale, UNUM_CURRENCY_ISO, errorCode) to get the currency number format,
134 * in which the currency is represented by its ISO code, for example "USD3.00".\n
135 * \c createInstance(locale, UNUM_CURRENCY_PLURAL, errorCode) to get the currency number format,
136 * in which the currency is represented by its full name in plural format,
137 * for example, "3.00 US dollars" or "1.00 US dollar".
138 * <P>
139 * You can also control the display of numbers with such methods as
140 * \c getMinimumFractionDigits(). If you want even more control over the
141 * format or parsing, or want to give your users more control, you can
142 * try dynamic_casting the \c NumberFormat you get from the factory methods to a
143 * \c DecimalFormat. This will work for the vast majority of
144 * countries; just remember to test for nullptr in case you
145 * encounter an unusual one.
146 * <P>
147 * You can also use forms of the parse and format methods with
148 * \c ParsePosition and \c FieldPosition to allow you to:
149 * <ul type=round>
150 * <li>(a) progressively parse through pieces of a string.
151 * <li>(b) align the decimal point and other areas.
152 * </ul>
153 * For example, you can align numbers in two ways.
154 * <P>
155 * If you are using a monospaced font with spacing for alignment, you
156 * can pass the \c FieldPosition in your format call, with field =
157 * \c UNUM_INTEGER_FIELD. On output, \c getEndIndex will be set to the offset
158 * between the last character of the integer and the decimal. Add
159 * (desiredSpaceCount - getEndIndex) spaces at the front of the
160 * string.
161 * <P>
162 * If you are using proportional fonts, instead of padding with
163 * spaces, measure the width of the string in pixels from the start to
164 * getEndIndex. Then move the pen by (desiredPixelWidth -
165 * widthToAlignmentPoint) before drawing the text. It also works
166 * where there is no decimal, but possibly additional characters at
167 * the end, e.g. with parentheses in negative numbers: "(12)" for -12.
168 * <p>
169 * <em>User subclasses are not supported.</em> While clients may write
170 * subclasses, such code will not necessarily work and will not be
171 * guaranteed to work stably from release to release.
172 *
173 * @stable ICU 2.0
174 */
175 class U_I18N_API NumberFormat : public Format {
176 public:
177 /**
178 * Rounding mode.
179 *
180 * <p>
181 * For more detail on rounding modes, see:
182 * https://unicode-org.github.io/icu/userguide/format_parse/numbers/rounding-modes
183 *
184 * @stable ICU 2.4
185 */
186 enum ERoundingMode {
187 kRoundCeiling, /**< Round towards positive infinity */
188 kRoundFloor, /**< Round towards negative infinity */
189 kRoundDown, /**< Round towards zero */
190 kRoundUp, /**< Round away from zero */
191 kRoundHalfEven, /**< Round towards the nearest integer, or
192 towards the nearest even integer if equidistant */
193 kRoundHalfDown, /**< Round towards the nearest integer, or
194 towards zero if equidistant */
195 kRoundHalfUp, /**< Round towards the nearest integer, or
196 away from zero if equidistant */
197 /**
198 * Return U_FORMAT_INEXACT_ERROR if number does not format exactly.
199 * @stable ICU 4.8
200 */
201 kRoundUnnecessary,
202 #ifndef U_HIDE_DRAFT_API
203 /**
204 * Rounds ties toward the odd number.
205 * @draft ICU 73
206 */
207 kRoundHalfOdd,
208 /**
209 * Rounds ties toward +∞.
210 * @draft ICU 73
211 */
212 kRoundHalfCeiling,
213 /**
214 * Rounds ties toward -∞.
215 * @draft ICU 73
216 */
217 kRoundHalfFloor,
218 #endif /* U_HIDE_DRAFT_API */
219 };
220
221 /**
222 * Alignment Field constants used to construct a FieldPosition object.
223 * Signifies that the position of the integer part or fraction part of
224 * a formatted number should be returned.
225 *
226 * Note: as of ICU 4.4, the values in this enum have been extended to
227 * support identification of all number format fields, not just those
228 * pertaining to alignment.
229 *
230 * These constants are provided for backwards compatibility only.
231 * Please use the C style constants defined in the header file unum.h.
232 *
233 * @see FieldPosition
234 * @stable ICU 2.0
235 */
236 enum EAlignmentFields {
237 /** @stable ICU 2.0 */
238 kIntegerField = UNUM_INTEGER_FIELD,
239 /** @stable ICU 2.0 */
240 kFractionField = UNUM_FRACTION_FIELD,
241 /** @stable ICU 2.0 */
242 kDecimalSeparatorField = UNUM_DECIMAL_SEPARATOR_FIELD,
243 /** @stable ICU 2.0 */
244 kExponentSymbolField = UNUM_EXPONENT_SYMBOL_FIELD,
245 /** @stable ICU 2.0 */
246 kExponentSignField = UNUM_EXPONENT_SIGN_FIELD,
247 /** @stable ICU 2.0 */
248 kExponentField = UNUM_EXPONENT_FIELD,
249 /** @stable ICU 2.0 */
250 kGroupingSeparatorField = UNUM_GROUPING_SEPARATOR_FIELD,
251 /** @stable ICU 2.0 */
252 kCurrencyField = UNUM_CURRENCY_FIELD,
253 /** @stable ICU 2.0 */
254 kPercentField = UNUM_PERCENT_FIELD,
255 /** @stable ICU 2.0 */
256 kPermillField = UNUM_PERMILL_FIELD,
257 /** @stable ICU 2.0 */
258 kSignField = UNUM_SIGN_FIELD,
259 /** @stable ICU 64 */
260 kMeasureUnitField = UNUM_MEASURE_UNIT_FIELD,
261 /** @stable ICU 64 */
262 kCompactField = UNUM_COMPACT_FIELD,
263
264 /**
265 * These constants are provided for backwards compatibility only.
266 * Please use the constants defined in the header file unum.h.
267 */
268 /** @stable ICU 2.0 */
269 INTEGER_FIELD = UNUM_INTEGER_FIELD,
270 /** @stable ICU 2.0 */
271 FRACTION_FIELD = UNUM_FRACTION_FIELD
272 };
273
274 /**
275 * Destructor.
276 * @stable ICU 2.0
277 */
278 virtual ~NumberFormat();
279
280 /**
281 * Clones this object polymorphically.
282 * The caller owns the result and should delete it when done.
283 * @return clone, or nullptr if an error occurred
284 * @stable ICU 2.0
285 */
286 virtual NumberFormat* clone() const override = 0;
287
288 /**
289 * Return true if the given Format objects are semantically equal.
290 * Objects of different subclasses are considered unequal.
291 * @return true if the given Format objects are semantically equal.
292 * @stable ICU 2.0
293 */
294 virtual bool operator==(const Format& other) const override;
295
296
297 using Format::format;
298
299 /**
300 * Format an object to produce a string. This method handles
301 * Formattable objects with numeric types. If the Formattable
302 * object type is not a numeric type, then it returns a failing
303 * UErrorCode.
304 *
305 * @param obj The object to format.
306 * @param appendTo Output parameter to receive result.
307 * Result is appended to existing contents.
308 * @param pos On input: an alignment field, if desired.
309 * On output: the offsets of the alignment field.
310 * @param status Output param filled with success/failure status.
311 * @return Reference to 'appendTo' parameter.
312 * @stable ICU 2.0
313 */
314 virtual UnicodeString& format(const Formattable& obj,
315 UnicodeString& appendTo,
316 FieldPosition& pos,
317 UErrorCode& status) const override;
318
319 /**
320 * Format an object to produce a string. This method handles
321 * Formattable objects with numeric types. If the Formattable
322 * object type is not a numeric type, then it returns a failing
323 * UErrorCode.
324 *
325 * @param obj The object to format.
326 * @param appendTo Output parameter to receive result.
327 * Result is appended to existing contents.
328 * @param posIter On return, can be used to iterate over positions
329 * of fields generated by this format call. Can be
330 * nullptr.
331 * @param status Output param filled with success/failure status.
332 * @return Reference to 'appendTo' parameter.
333 * @stable ICU 4.4
334 */
335 virtual UnicodeString& format(const Formattable& obj,
336 UnicodeString& appendTo,
337 FieldPositionIterator* posIter,
338 UErrorCode& status) const override;
339
340 /**
341 * Parse a string to produce an object. This methods handles
342 * parsing of numeric strings into Formattable objects with numeric
343 * types.
344 * <P>
345 * Before calling, set parse_pos.index to the offset you want to
346 * start parsing at in the source. After calling, parse_pos.index
347 * indicates the position after the successfully parsed text. If
348 * an error occurs, parse_pos.index is unchanged.
349 * <P>
350 * When parsing, leading whitespace is discarded (with successful
351 * parse), while trailing whitespace is left as is.
352 * <P>
353 * See Format::parseObject() for more.
354 *
355 * @param source The string to be parsed into an object.
356 * @param result Formattable to be set to the parse result.
357 * If parse fails, return contents are undefined.
358 * @param parse_pos The position to start parsing at. Upon return
359 * this param is set to the position after the
360 * last character successfully parsed. If the
361 * source is not parsed successfully, this param
362 * will remain unchanged.
363 * @return A newly created Formattable* object, or nullptr
364 * on failure. The caller owns this and should
365 * delete it when done.
366 * @stable ICU 2.0
367 */
368 virtual void parseObject(const UnicodeString& source,
369 Formattable& result,
370 ParsePosition& parse_pos) const override;
371
372 /**
373 * Format a double number. These methods call the NumberFormat
374 * pure virtual format() methods with the default FieldPosition.
375 *
376 * @param number The value to be formatted.
377 * @param appendTo Output parameter to receive result.
378 * Result is appended to existing contents.
379 * @return Reference to 'appendTo' parameter.
380 * @stable ICU 2.0
381 */
382 UnicodeString& format( double number,
383 UnicodeString& appendTo) const;
384
385 /**
386 * Format a long number. These methods call the NumberFormat
387 * pure virtual format() methods with the default FieldPosition.
388 *
389 * @param number The value to be formatted.
390 * @param appendTo Output parameter to receive result.
391 * Result is appended to existing contents.
392 * @return Reference to 'appendTo' parameter.
393 * @stable ICU 2.0
394 */
395 UnicodeString& format( int32_t number,
396 UnicodeString& appendTo) const;
397
398 /**
399 * Format an int64 number. These methods call the NumberFormat
400 * pure virtual format() methods with the default FieldPosition.
401 *
402 * @param number The value to be formatted.
403 * @param appendTo Output parameter to receive result.
404 * Result is appended to existing contents.
405 * @return Reference to 'appendTo' parameter.
406 * @stable ICU 2.8
407 */
408 UnicodeString& format( int64_t number,
409 UnicodeString& appendTo) const;
410
411 /**
412 * Format a double number. Concrete subclasses must implement
413 * these pure virtual methods.
414 *
415 * @param number The value to be formatted.
416 * @param appendTo Output parameter to receive result.
417 * Result is appended to existing contents.
418 * @param pos On input: an alignment field, if desired.
419 * On output: the offsets of the alignment field.
420 * @return Reference to 'appendTo' parameter.
421 * @stable ICU 2.0
422 */
423 virtual UnicodeString& format(double number,
424 UnicodeString& appendTo,
425 FieldPosition& pos) const = 0;
426 /**
427 * Format a double number. By default, the parent function simply
428 * calls the base class and does not return an error status.
429 * Therefore, the status may be ignored in some subclasses.
430 *
431 * @param number The value to be formatted.
432 * @param appendTo Output parameter to receive result.
433 * Result is appended to existing contents.
434 * @param pos On input: an alignment field, if desired.
435 * On output: the offsets of the alignment field.
436 * @param status error status
437 * @return Reference to 'appendTo' parameter.
438 * @internal
439 */
440 virtual UnicodeString& format(double number,
441 UnicodeString& appendTo,
442 FieldPosition& pos,
443 UErrorCode &status) const;
444 /**
445 * Format a double number. Subclasses must implement
446 * this method.
447 *
448 * @param number The value to be formatted.
449 * @param appendTo Output parameter to receive result.
450 * Result is appended to existing contents.
451 * @param posIter On return, can be used to iterate over positions
452 * of fields generated by this format call.
453 * Can be nullptr.
454 * @param status Output param filled with success/failure status.
455 * @return Reference to 'appendTo' parameter.
456 * @stable ICU 4.4
457 */
458 virtual UnicodeString& format(double number,
459 UnicodeString& appendTo,
460 FieldPositionIterator* posIter,
461 UErrorCode& status) const;
462 /**
463 * Format a long number. Concrete subclasses must implement
464 * these pure virtual methods.
465 *
466 * @param number The value to be formatted.
467 * @param appendTo Output parameter to receive result.
468 * Result is appended to existing contents.
469 * @param pos On input: an alignment field, if desired.
470 * On output: the offsets of the alignment field.
471 * @return Reference to 'appendTo' parameter.
472 * @stable ICU 2.0
473 */
474 virtual UnicodeString& format(int32_t number,
475 UnicodeString& appendTo,
476 FieldPosition& pos) const = 0;
477
478 /**
479 * Format a long number. Concrete subclasses may override
480 * this function to provide status return.
481 *
482 * @param number The value to be formatted.
483 * @param appendTo Output parameter to receive result.
484 * Result is appended to existing contents.
485 * @param pos On input: an alignment field, if desired.
486 * On output: the offsets of the alignment field.
487 * @param status the output status.
488 * @return Reference to 'appendTo' parameter.
489 * @internal
490 */
491 virtual UnicodeString& format(int32_t number,
492 UnicodeString& appendTo,
493 FieldPosition& pos,
494 UErrorCode &status) const;
495
496 /**
497 * Format an int32 number. Subclasses must implement
498 * this method.
499 *
500 * @param number The value to be formatted.
501 * @param appendTo Output parameter to receive result.
502 * Result is appended to existing contents.
503 * @param posIter On return, can be used to iterate over positions
504 * of fields generated by this format call.
505 * Can be nullptr.
506 * @param status Output param filled with success/failure status.
507 * @return Reference to 'appendTo' parameter.
508 * @stable ICU 4.4
509 */
510 virtual UnicodeString& format(int32_t number,
511 UnicodeString& appendTo,
512 FieldPositionIterator* posIter,
513 UErrorCode& status) const;
514 /**
515 * Format an int64 number. (Not abstract to retain compatibility
516 * with earlier releases, however subclasses should override this
517 * method as it just delegates to format(int32_t number...);
518 *
519 * @param number The value to be formatted.
520 * @param appendTo Output parameter to receive result.
521 * Result is appended to existing contents.
522 * @param pos On input: an alignment field, if desired.
523 * On output: the offsets of the alignment field.
524 * @return Reference to 'appendTo' parameter.
525 * @stable ICU 2.8
526 */
527 virtual UnicodeString& format(int64_t number,
528 UnicodeString& appendTo,
529 FieldPosition& pos) const;
530
531 /**
532 * Format an int64 number. (Not abstract to retain compatibility
533 * with earlier releases, however subclasses should override this
534 * method as it just delegates to format(int32_t number...);
535 *
536 * @param number The value to be formatted.
537 * @param appendTo Output parameter to receive result.
538 * Result is appended to existing contents.
539 * @param pos On input: an alignment field, if desired.
540 * On output: the offsets of the alignment field.
541 * @param status Output param filled with success/failure status.
542 * @return Reference to 'appendTo' parameter.
543 * @internal
544 */
545 virtual UnicodeString& format(int64_t number,
546 UnicodeString& appendTo,
547 FieldPosition& pos,
548 UErrorCode& status) const;
549 /**
550 * Format an int64 number. Subclasses must implement
551 * this method.
552 *
553 * @param number The value to be formatted.
554 * @param appendTo Output parameter to receive result.
555 * Result is appended to existing contents.
556 * @param posIter On return, can be used to iterate over positions
557 * of fields generated by this format call.
558 * Can be nullptr.
559 * @param status Output param filled with success/failure status.
560 * @return Reference to 'appendTo' parameter.
561 * @stable ICU 4.4
562 */
563 virtual UnicodeString& format(int64_t number,
564 UnicodeString& appendTo,
565 FieldPositionIterator* posIter,
566 UErrorCode& status) const;
567
568 /**
569 * Format a decimal number. Subclasses must implement
570 * this method. The syntax of the unformatted number is a "numeric string"
571 * as defined in the Decimal Arithmetic Specification, available at
572 * http://speleotrove.com/decimal
573 *
574 * @param number The unformatted number, as a string, to be formatted.
575 * @param appendTo Output parameter to receive result.
576 * Result is appended to existing contents.
577 * @param posIter On return, can be used to iterate over positions
578 * of fields generated by this format call.
579 * Can be nullptr.
580 * @param status Output param filled with success/failure status.
581 * @return Reference to 'appendTo' parameter.
582 * @stable ICU 4.4
583 */
584 virtual UnicodeString& format(StringPiece number,
585 UnicodeString& appendTo,
586 FieldPositionIterator* posIter,
587 UErrorCode& status) const;
588
589 // Can't use #ifndef U_HIDE_INTERNAL_API because these are virtual methods
590
591 /**
592 * Format a decimal number.
593 * The number is a DecimalQuantity wrapper onto a floating point decimal number.
594 * The default implementation in NumberFormat converts the decimal number
595 * to a double and formats that. Subclasses of NumberFormat that want
596 * to specifically handle big decimal numbers must override this method.
597 * class DecimalFormat does so.
598 *
599 * @param number The number, a DecimalQuantity format Decimal Floating Point.
600 * @param appendTo Output parameter to receive result.
601 * Result is appended to existing contents.
602 * @param posIter On return, can be used to iterate over positions
603 * of fields generated by this format call.
604 * @param status Output param filled with success/failure status.
605 * @return Reference to 'appendTo' parameter.
606 * @internal
607 */
608 virtual UnicodeString& format(const number::impl::DecimalQuantity &number,
609 UnicodeString& appendTo,
610 FieldPositionIterator* posIter,
611 UErrorCode& status) const;
612
613 /**
614 * Format a decimal number.
615 * The number is a DecimalQuantity wrapper onto a floating point decimal number.
616 * The default implementation in NumberFormat converts the decimal number
617 * to a double and formats that. Subclasses of NumberFormat that want
618 * to specifically handle big decimal numbers must override this method.
619 * class DecimalFormat does so.
620 *
621 * @param number The number, a DecimalQuantity format Decimal Floating Point.
622 * @param appendTo Output parameter to receive result.
623 * Result is appended to existing contents.
624 * @param pos On input: an alignment field, if desired.
625 * On output: the offsets of the alignment field.
626 * @param status Output param filled with success/failure status.
627 * @return Reference to 'appendTo' parameter.
628 * @internal
629 */
630 virtual UnicodeString& format(const number::impl::DecimalQuantity &number,
631 UnicodeString& appendTo,
632 FieldPosition& pos,
633 UErrorCode& status) const;
634
635 /**
636 * Return a long if possible (e.g. within range LONG_MAX,
637 * LONG_MAX], and with no decimals), otherwise a double. If
638 * IntegerOnly is set, will stop at a decimal point (or equivalent;
639 * e.g. for rational numbers "1 2/3", will stop after the 1).
640 * <P>
641 * If no object can be parsed, index is unchanged, and nullptr is
642 * returned.
643 * <P>
644 * This is a pure virtual which concrete subclasses must implement.
645 *
646 * @param text The text to be parsed.
647 * @param result Formattable to be set to the parse result.
648 * If parse fails, return contents are undefined.
649 * @param parsePosition The position to start parsing at on input.
650 * On output, moved to after the last successfully
651 * parse character. On parse failure, does not change.
652 * @stable ICU 2.0
653 */
654 virtual void parse(const UnicodeString& text,
655 Formattable& result,
656 ParsePosition& parsePosition) const = 0;
657
658 /**
659 * Parse a string as a numeric value, and return a Formattable
660 * numeric object. This method parses integers only if IntegerOnly
661 * is set.
662 *
663 * @param text The text to be parsed.
664 * @param result Formattable to be set to the parse result.
665 * If parse fails, return contents are undefined.
666 * @param status Output parameter set to a failure error code
667 * when a failure occurs. The error code when the
668 * string fails to parse is U_INVALID_FORMAT_ERROR,
669 * unless overridden by a subclass.
670 * @see NumberFormat::isParseIntegerOnly
671 * @stable ICU 2.0
672 */
673 virtual void parse(const UnicodeString& text,
674 Formattable& result,
675 UErrorCode& status) const;
676
677 /**
678 * Parses text from the given string as a currency amount. Unlike
679 * the parse() method, this method will attempt to parse a generic
680 * currency name, searching for a match of this object's locale's
681 * currency display names, or for a 3-letter ISO currency code.
682 * This method will fail if this format is not a currency format,
683 * that is, if it does not contain the currency pattern symbol
684 * (U+00A4) in its prefix or suffix.
685 *
686 * @param text the string to parse
687 * @param pos input-output position; on input, the position within text
688 * to match; must have 0 <= pos.getIndex() < text.length();
689 * on output, the position after the last matched character.
690 * If the parse fails, the position in unchanged upon output.
691 * @return if parse succeeds, a pointer to a newly-created CurrencyAmount
692 * object (owned by the caller) containing information about
693 * the parsed currency; if parse fails, this is nullptr.
694 * @stable ICU 49
695 */
696 virtual CurrencyAmount* parseCurrency(const UnicodeString& text,
697 ParsePosition& pos) const;
698
699 /**
700 * Return true if this format will parse numbers as integers
701 * only. For example in the English locale, with ParseIntegerOnly
702 * true, the string "1234." would be parsed as the integer value
703 * 1234 and parsing would stop at the "." character. Of course,
704 * the exact format accepted by the parse operation is locale
705 * dependent and determined by sub-classes of NumberFormat.
706 * @return true if this format will parse numbers as integers
707 * only.
708 * @stable ICU 2.0
709 */
710 UBool isParseIntegerOnly(void) const;
711
712 /**
713 * Sets whether or not numbers should be parsed as integers only.
714 * @param value set True, this format will parse numbers as integers
715 * only.
716 * @see isParseIntegerOnly
717 * @stable ICU 2.0
718 */
719 virtual void setParseIntegerOnly(UBool value);
720
721 /**
722 * Sets whether lenient parsing should be enabled (it is off by default).
723 *
724 * @param enable \c true if lenient parsing should be used,
725 * \c false otherwise.
726 * @stable ICU 4.8
727 */
728 virtual void setLenient(UBool enable);
729
730 /**
731 * Returns whether lenient parsing is enabled (it is off by default).
732 *
733 * @return \c true if lenient parsing is enabled,
734 * \c false otherwise.
735 * @see #setLenient
736 * @stable ICU 4.8
737 */
738 virtual UBool isLenient(void) const;
739
740 /**
741 * Create a default style NumberFormat for the current default locale.
742 * The default formatting style is locale dependent.
743 * <p>
744 * <strong>NOTE:</strong> New users are strongly encouraged to use
745 * {@link icu::number::NumberFormatter} instead of NumberFormat.
746 * @stable ICU 2.0
747 */
748 static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
749
750 /**
751 * Create a default style NumberFormat for the specified locale.
752 * The default formatting style is locale dependent.
753 * @param inLocale the given locale.
754 * <p>
755 * <strong>NOTE:</strong> New users are strongly encouraged to use
756 * {@link icu::number::NumberFormatter} instead of NumberFormat.
757 * @stable ICU 2.0
758 */
759 static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale,
760 UErrorCode&);
761
762 /**
763 * Create a specific style NumberFormat for the specified locale.
764 * <p>
765 * <strong>NOTE:</strong> New users are strongly encouraged to use
766 * {@link icu::number::NumberFormatter} instead of NumberFormat.
767 * @param desiredLocale the given locale.
768 * @param style the given style.
769 * @param errorCode Output param filled with success/failure status.
770 * @return A new NumberFormat instance.
771 * @stable ICU 4.8
772 */
773 static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale,
774 UNumberFormatStyle style,
775 UErrorCode& errorCode);
776
777 #ifndef U_HIDE_INTERNAL_API
778
779 /**
780 * ICU use only.
781 * Creates NumberFormat instance without using the cache.
782 * @internal
783 */
784 static NumberFormat* internalCreateInstance(
785 const Locale& desiredLocale,
786 UNumberFormatStyle style,
787 UErrorCode& errorCode);
788
789 /**
790 * ICU use only.
791 * Returns handle to the shared, cached NumberFormat instance for given
792 * locale. On success, caller must call removeRef() on returned value
793 * once it is done with the shared instance.
794 * @internal
795 */
796 static const SharedNumberFormat* U_EXPORT2 createSharedInstance(
797 const Locale& inLocale, UNumberFormatStyle style, UErrorCode& status);
798
799 #endif /* U_HIDE_INTERNAL_API */
800
801 /**
802 * Returns a currency format for the current default locale.
803 * <p>
804 * <strong>NOTE:</strong> New users are strongly encouraged to use
805 * {@link icu::number::NumberFormatter} instead of NumberFormat.
806 * @stable ICU 2.0
807 */
808 static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&);
809
810 /**
811 * Returns a currency format for the specified locale.
812 * <p>
813 * <strong>NOTE:</strong> New users are strongly encouraged to use
814 * {@link icu::number::NumberFormatter} instead of NumberFormat.
815 * @param inLocale the given locale.
816 * @stable ICU 2.0
817 */
818 static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale,
819 UErrorCode&);
820
821 /**
822 * Returns a percentage format for the current default locale.
823 * <p>
824 * <strong>NOTE:</strong> New users are strongly encouraged to use
825 * {@link icu::number::NumberFormatter} instead of NumberFormat.
826 * @stable ICU 2.0
827 */
828 static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&);
829
830 /**
831 * Returns a percentage format for the specified locale.
832 * <p>
833 * <strong>NOTE:</strong> New users are strongly encouraged to use
834 * {@link icu::number::NumberFormatter} instead of NumberFormat.
835 * @param inLocale the given locale.
836 * @stable ICU 2.0
837 */
838 static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale,
839 UErrorCode&);
840
841 /**
842 * Returns a scientific format for the current default locale.
843 * <p>
844 * <strong>NOTE:</strong> New users are strongly encouraged to use
845 * {@link icu::number::NumberFormatter} instead of NumberFormat.
846 * @stable ICU 2.0
847 */
848 static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&);
849
850 /**
851 * Returns a scientific format for the specified locale.
852 * <p>
853 * <strong>NOTE:</strong> New users are strongly encouraged to use
854 * {@link icu::number::NumberFormatter} instead of NumberFormat.
855 * @param inLocale the given locale.
856 * @stable ICU 2.0
857 */
858 static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale,
859 UErrorCode&);
860
861 /**
862 * Get the set of Locales for which NumberFormats are installed.
863 * @param count Output param to receive the size of the locales
864 * @stable ICU 2.0
865 */
866 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
867
868 #if !UCONFIG_NO_SERVICE
869 /**
870 * Register a new NumberFormatFactory. The factory will be adopted.
871 * Because ICU may choose to cache NumberFormat objects internally,
872 * this must be called at application startup, prior to any calls to
873 * NumberFormat::createInstance to avoid undefined behavior.
874 * @param toAdopt the NumberFormatFactory instance to be adopted
875 * @param status the in/out status code, no special meanings are assigned
876 * @return a registry key that can be used to unregister this factory
877 * @stable ICU 2.6
878 */
879 static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status);
880
881 /**
882 * Unregister a previously-registered NumberFormatFactory using the key returned from the
883 * register call. Key becomes invalid after a successful call and should not be used again.
884 * The NumberFormatFactory corresponding to the key will be deleted.
885 * Because ICU may choose to cache NumberFormat objects internally,
886 * this should be called during application shutdown, after all calls to
887 * NumberFormat::createInstance to avoid undefined behavior.
888 * @param key the registry key returned by a previous call to registerFactory
889 * @param status the in/out status code, no special meanings are assigned
890 * @return true if the factory for the key was successfully unregistered
891 * @stable ICU 2.6
892 */
893 static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
894
895 /**
896 * Return a StringEnumeration over the locales available at the time of the call,
897 * including registered locales.
898 * @return a StringEnumeration over the locales available at the time of the call
899 * @stable ICU 2.6
900 */
901 static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
902 #endif /* UCONFIG_NO_SERVICE */
903
904 /**
905 * Returns true if grouping is used in this format. For example,
906 * in the English locale, with grouping on, the number 1234567
907 * might be formatted as "1,234,567". The grouping separator as
908 * well as the size of each group is locale dependent and is
909 * determined by sub-classes of NumberFormat.
910 * @see setGroupingUsed
911 * @stable ICU 2.0
912 */
913 UBool isGroupingUsed(void) const;
914
915 /**
916 * Set whether or not grouping will be used in this format.
917 * @param newValue True, grouping will be used in this format.
918 * @see getGroupingUsed
919 * @stable ICU 2.0
920 */
921 virtual void setGroupingUsed(UBool newValue);
922
923 /**
924 * Returns the maximum number of digits allowed in the integer portion of a
925 * number.
926 * @return the maximum number of digits allowed in the integer portion of a
927 * number.
928 * @see setMaximumIntegerDigits
929 * @stable ICU 2.0
930 */
931 int32_t getMaximumIntegerDigits(void) const;
932
933 /**
934 * Sets the maximum number of digits allowed in the integer portion of a
935 * number. maximumIntegerDigits must be >= minimumIntegerDigits. If the
936 * new value for maximumIntegerDigits is less than the current value
937 * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
938 * the new value.
939 *
940 * @param newValue the new value for the maximum number of digits
941 * allowed in the integer portion of a number.
942 * @see getMaximumIntegerDigits
943 * @stable ICU 2.0
944 */
945 virtual void setMaximumIntegerDigits(int32_t newValue);
946
947 /**
948 * Returns the minimum number of digits allowed in the integer portion of a
949 * number.
950 * @return the minimum number of digits allowed in the integer portion of a
951 * number.
952 * @see setMinimumIntegerDigits
953 * @stable ICU 2.0
954 */
955 int32_t getMinimumIntegerDigits(void) const;
956
957 /**
958 * Sets the minimum number of digits allowed in the integer portion of a
959 * number. minimumIntegerDigits must be <= maximumIntegerDigits. If the
960 * new value for minimumIntegerDigits exceeds the current value
961 * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
962 * the new value.
963 * @param newValue the new value to be set.
964 * @see getMinimumIntegerDigits
965 * @stable ICU 2.0
966 */
967 virtual void setMinimumIntegerDigits(int32_t newValue);
968
969 /**
970 * Returns the maximum number of digits allowed in the fraction portion of a
971 * number.
972 * @return the maximum number of digits allowed in the fraction portion of a
973 * number.
974 * @see setMaximumFractionDigits
975 * @stable ICU 2.0
976 */
977 int32_t getMaximumFractionDigits(void) const;
978
979 /**
980 * Sets the maximum number of digits allowed in the fraction portion of a
981 * number. maximumFractionDigits must be >= minimumFractionDigits. If the
982 * new value for maximumFractionDigits is less than the current value
983 * of minimumFractionDigits, then minimumFractionDigits will also be set to
984 * the new value.
985 * @param newValue the new value to be set.
986 * @see getMaximumFractionDigits
987 * @stable ICU 2.0
988 */
989 virtual void setMaximumFractionDigits(int32_t newValue);
990
991 /**
992 * Returns the minimum number of digits allowed in the fraction portion of a
993 * number.
994 * @return the minimum number of digits allowed in the fraction portion of a
995 * number.
996 * @see setMinimumFractionDigits
997 * @stable ICU 2.0
998 */
999 int32_t getMinimumFractionDigits(void) const;
1000
1001 /**
1002 * Sets the minimum number of digits allowed in the fraction portion of a
1003 * number. minimumFractionDigits must be <= maximumFractionDigits. If the
1004 * new value for minimumFractionDigits exceeds the current value
1005 * of maximumFractionDigits, then maximumIntegerDigits will also be set to
1006 * the new value
1007 * @param newValue the new value to be set.
1008 * @see getMinimumFractionDigits
1009 * @stable ICU 2.0
1010 */
1011 virtual void setMinimumFractionDigits(int32_t newValue);
1012
1013 /**
1014 * Sets the currency used to display currency
1015 * amounts. This takes effect immediately, if this format is a
1016 * currency format. If this format is not a currency format, then
1017 * the currency is used if and when this object becomes a
1018 * currency format.
1019 * @param theCurrency a 3-letter ISO code indicating new currency
1020 * to use. It need not be null-terminated. May be the empty
1021 * string or nullptr to indicate no currency.
1022 * @param ec input-output error code
1023 * @stable ICU 3.0
1024 */
1025 virtual void setCurrency(const char16_t* theCurrency, UErrorCode& ec);
1026
1027 /**
1028 * Gets the currency used to display currency
1029 * amounts. This may be an empty string for some subclasses.
1030 * @return a 3-letter null-terminated ISO code indicating
1031 * the currency in use, or a pointer to the empty string.
1032 * @stable ICU 2.6
1033 */
1034 const char16_t* getCurrency() const;
1035
1036 /**
1037 * Set a particular UDisplayContext value in the formatter, such as
1038 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE.
1039 * @param value The UDisplayContext value to set.
1040 * @param status Input/output status. If at entry this indicates a failure
1041 * status, the function will do nothing; otherwise this will be
1042 * updated with any new status from the function.
1043 * @stable ICU 53
1044 */
1045 virtual void setContext(UDisplayContext value, UErrorCode& status);
1046
1047 /**
1048 * Get the formatter's UDisplayContext value for the specified UDisplayContextType,
1049 * such as UDISPCTX_TYPE_CAPITALIZATION.
1050 * @param type The UDisplayContextType whose value to return
1051 * @param status Input/output status. If at entry this indicates a failure
1052 * status, the function will do nothing; otherwise this will be
1053 * updated with any new status from the function.
1054 * @return The UDisplayContextValue for the specified type.
1055 * @stable ICU 53
1056 */
1057 virtual UDisplayContext getContext(UDisplayContextType type, UErrorCode& status) const;
1058
1059 /**
1060 * Get the rounding mode. This will always return NumberFormat::ERoundingMode::kRoundUnnecessary
1061 * if the subclass does not support rounding.
1062 * @return A rounding mode
1063 * @stable ICU 60
1064 */
1065 virtual ERoundingMode getRoundingMode(void) const;
1066
1067 /**
1068 * Set the rounding mode. If a subclass does not support rounding, this will do nothing.
1069 * @param roundingMode A rounding mode
1070 * @stable ICU 60
1071 */
1072 virtual void setRoundingMode(ERoundingMode roundingMode);
1073
1074 public:
1075
1076 /**
1077 * Return the class ID for this class. This is useful for
1078 * comparing to a return value from getDynamicClassID(). Note that,
1079 * because NumberFormat is an abstract base class, no fully constructed object
1080 * will have the class ID returned by NumberFormat::getStaticClassID().
1081 * @return The class ID for all objects of this class.
1082 * @stable ICU 2.0
1083 */
1084 static UClassID U_EXPORT2 getStaticClassID(void);
1085
1086 /**
1087 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override.
1088 * This method is to implement a simple version of RTTI, since not all
1089 * C++ compilers support genuine RTTI. Polymorphic operator==() and
1090 * clone() methods call this method.
1091 * <P>
1092 * @return The class ID for this object. All objects of a
1093 * given class have the same class ID. Objects of
1094 * other classes have different class IDs.
1095 * @stable ICU 2.0
1096 */
1097 virtual UClassID getDynamicClassID(void) const override = 0;
1098
1099 protected:
1100
1101 /**
1102 * Default constructor for subclass use only.
1103 * @stable ICU 2.0
1104 */
1105 NumberFormat();
1106
1107 /**
1108 * Copy constructor.
1109 * @stable ICU 2.0
1110 */
1111 NumberFormat(const NumberFormat&);
1112
1113 /**
1114 * Assignment operator.
1115 * @stable ICU 2.0
1116 */
1117 NumberFormat& operator=(const NumberFormat&);
1118
1119 /**
1120 * Returns the currency in effect for this formatter. Subclasses
1121 * should override this method as needed. Unlike getCurrency(),
1122 * this method should never return "".
1123 * @result output parameter for null-terminated result, which must
1124 * have a capacity of at least 4
1125 * @internal
1126 */
1127 virtual void getEffectiveCurrency(char16_t* result, UErrorCode& ec) const;
1128
1129 #ifndef U_HIDE_INTERNAL_API
1130 /**
1131 * Creates the specified number format style of the desired locale.
1132 * If mustBeDecimalFormat is true, then the returned pointer is
1133 * either a DecimalFormat or it is nullptr.
1134 * @internal
1135 */
1136 static NumberFormat* makeInstance(const Locale& desiredLocale,
1137 UNumberFormatStyle style,
1138 UBool mustBeDecimalFormat,
1139 UErrorCode& errorCode);
1140 #endif /* U_HIDE_INTERNAL_API */
1141
1142 private:
1143
1144 static UBool isStyleSupported(UNumberFormatStyle style);
1145
1146 /**
1147 * Creates the specified decimal format style of the desired locale.
1148 * @param desiredLocale the given locale.
1149 * @param style the given style.
1150 * @param errorCode Output param filled with success/failure status.
1151 * @return A new NumberFormat instance.
1152 */
1153 static NumberFormat* makeInstance(const Locale& desiredLocale,
1154 UNumberFormatStyle style,
1155 UErrorCode& errorCode);
1156
1157 UBool fGroupingUsed;
1158 int32_t fMaxIntegerDigits;
1159 int32_t fMinIntegerDigits;
1160 int32_t fMaxFractionDigits;
1161 int32_t fMinFractionDigits;
1162
1163 protected:
1164 /** \internal */
1165 static const int32_t gDefaultMaxIntegerDigits;
1166 /** \internal */
1167 static const int32_t gDefaultMinIntegerDigits;
1168
1169 private:
1170 UBool fParseIntegerOnly;
1171 UBool fLenient; // true => lenient parse is enabled
1172
1173 // ISO currency code
1174 char16_t fCurrency[4];
1175
1176 UDisplayContext fCapitalizationContext;
1177
1178 friend class ICUNumberFormatFactory; // access to makeInstance
1179 friend class ICUNumberFormatService;
1180 friend class ::NumberFormatTest; // access to isStyleSupported()
1181 };
1182
1183 #if !UCONFIG_NO_SERVICE
1184 /**
1185 * A NumberFormatFactory is used to register new number formats. The factory
1186 * should be able to create any of the predefined formats for each locale it
1187 * supports. When registered, the locales it supports extend or override the
1188 * locale already supported by ICU.
1189 *
1190 * @stable ICU 2.6
1191 */
1192 class U_I18N_API NumberFormatFactory : public UObject {
1193 public:
1194
1195 /**
1196 * Destructor
1197 * @stable ICU 3.0
1198 */
1199 virtual ~NumberFormatFactory();
1200
1201 /**
1202 * Return true if this factory will be visible. Default is true.
1203 * If not visible, the locales supported by this factory will not
1204 * be listed by getAvailableLocales.
1205 * @stable ICU 2.6
1206 */
1207 virtual UBool visible(void) const = 0;
1208
1209 /**
1210 * Return the locale names directly supported by this factory. The number of names
1211 * is returned in count;
1212 * @stable ICU 2.6
1213 */
1214 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0;
1215
1216 /**
1217 * Return a number format of the appropriate type. If the locale
1218 * is not supported, return null. If the locale is supported, but
1219 * the type is not provided by this service, return null. Otherwise
1220 * return an appropriate instance of NumberFormat.
1221 * @stable ICU 2.6
1222 */
1223 virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0;
1224 };
1225
1226 /**
1227 * A NumberFormatFactory that supports a single locale. It can be visible or invisible.
1228 * @stable ICU 2.6
1229 */
1230 class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory {
1231 protected:
1232 /**
1233 * True if the locale supported by this factory is visible.
1234 * @stable ICU 2.6
1235 */
1236 const UBool _visible;
1237
1238 /**
1239 * The locale supported by this factory, as a UnicodeString.
1240 * @stable ICU 2.6
1241 */
1242 UnicodeString _id;
1243
1244 public:
1245 /**
1246 * @stable ICU 2.6
1247 */
1248 SimpleNumberFormatFactory(const Locale& locale, UBool visible = true);
1249
1250 /**
1251 * @stable ICU 3.0
1252 */
1253 virtual ~SimpleNumberFormatFactory();
1254
1255 /**
1256 * @stable ICU 2.6
1257 */
1258 virtual UBool visible(void) const override;
1259
1260 /**
1261 * @stable ICU 2.6
1262 */
1263 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const override;
1264 };
1265 #endif /* #if !UCONFIG_NO_SERVICE */
1266
1267 // -------------------------------------
1268
1269 inline UBool
isParseIntegerOnly()1270 NumberFormat::isParseIntegerOnly() const
1271 {
1272 return fParseIntegerOnly;
1273 }
1274
1275 inline UBool
isLenient()1276 NumberFormat::isLenient() const
1277 {
1278 return fLenient;
1279 }
1280
1281 U_NAMESPACE_END
1282
1283 #endif /* #if !UCONFIG_NO_FORMATTING */
1284
1285 #endif /* U_SHOW_CPLUSPLUS_API */
1286
1287 #endif // _NUMFMT
1288 //eof
1289