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* Derecated 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
46class NumberFormatTest;
47
48U_NAMESPACE_BEGIN
49
50class SharedNumberFormat;
51
52#if !UCONFIG_NO_SERVICE
53class NumberFormatFactory;
54class 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 NULL 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 */
175class U_I18N_API NumberFormat : public Format {
176public:
177 /**
178 * Rounding mode.
179 *
180 * <p>
181 * For more detail on rounding modes, see:
182 * http://userguide.icu-project.org/formatparse/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 };
203
204 /**
205 * Alignment Field constants used to construct a FieldPosition object.
206 * Signifies that the position of the integer part or fraction part of
207 * a formatted number should be returned.
208 *
209 * Note: as of ICU 4.4, the values in this enum have been extended to
210 * support identification of all number format fields, not just those
211 * pertaining to alignment.
212 *
213 * These constants are provided for backwards compatibility only.
214 * Please use the C style constants defined in the header file unum.h.
215 *
216 * @see FieldPosition
217 * @stable ICU 2.0
218 */
219 enum EAlignmentFields {
220 /** @stable ICU 2.0 */
221 kIntegerField = UNUM_INTEGER_FIELD,
222 /** @stable ICU 2.0 */
223 kFractionField = UNUM_FRACTION_FIELD,
224 /** @stable ICU 2.0 */
225 kDecimalSeparatorField = UNUM_DECIMAL_SEPARATOR_FIELD,
226 /** @stable ICU 2.0 */
227 kExponentSymbolField = UNUM_EXPONENT_SYMBOL_FIELD,
228 /** @stable ICU 2.0 */
229 kExponentSignField = UNUM_EXPONENT_SIGN_FIELD,
230 /** @stable ICU 2.0 */
231 kExponentField = UNUM_EXPONENT_FIELD,
232 /** @stable ICU 2.0 */
233 kGroupingSeparatorField = UNUM_GROUPING_SEPARATOR_FIELD,
234 /** @stable ICU 2.0 */
235 kCurrencyField = UNUM_CURRENCY_FIELD,
236 /** @stable ICU 2.0 */
237 kPercentField = UNUM_PERCENT_FIELD,
238 /** @stable ICU 2.0 */
239 kPermillField = UNUM_PERMILL_FIELD,
240 /** @stable ICU 2.0 */
241 kSignField = UNUM_SIGN_FIELD,
242#ifndef U_HIDE_DRAFT_API
243 /** @draft ICU 64 */
244 kMeasureUnitField = UNUM_MEASURE_UNIT_FIELD,
245 /** @draft ICU 64 */
246 kCompactField = UNUM_COMPACT_FIELD,
247#endif // U_HIDE_DRAFT_API
248
249 /**
250 * These constants are provided for backwards compatibility only.
251 * Please use the constants defined in the header file unum.h.
252 */
253 /** @stable ICU 2.0 */
254 INTEGER_FIELD = UNUM_INTEGER_FIELD,
255 /** @stable ICU 2.0 */
256 FRACTION_FIELD = UNUM_FRACTION_FIELD
257 };
258
259 /**
260 * Destructor.
261 * @stable ICU 2.0
262 */
263 virtual ~NumberFormat();
264
265 /**
266 * Clones this object polymorphically.
267 * The caller owns the result and should delete it when done.
268 * @return clone, or nullptr if an error occurred
269 * @stable ICU 2.0
270 */
271 virtual NumberFormat* clone() const = 0;
272
273 /**
274 * Return true if the given Format objects are semantically equal.
275 * Objects of different subclasses are considered unequal.
276 * @return true if the given Format objects are semantically equal.
277 * @stable ICU 2.0
278 */
279 virtual UBool operator==(const Format& other) const;
280
281
282 using Format::format;
283
284 /**
285 * Format an object to produce a string. This method handles
286 * Formattable objects with numeric types. If the Formattable
287 * object type is not a numeric type, then it returns a failing
288 * UErrorCode.
289 *
290 * @param obj The object to format.
291 * @param appendTo Output parameter to receive result.
292 * Result is appended to existing contents.
293 * @param pos On input: an alignment field, if desired.
294 * On output: the offsets of the alignment field.
295 * @param status Output param filled with success/failure status.
296 * @return Reference to 'appendTo' parameter.
297 * @stable ICU 2.0
298 */
299 virtual UnicodeString& format(const Formattable& obj,
300 UnicodeString& appendTo,
301 FieldPosition& pos,
302 UErrorCode& status) const;
303
304 /**
305 * Format an object to produce a string. This method handles
306 * Formattable objects with numeric types. If the Formattable
307 * object type is not a numeric type, then it returns a failing
308 * UErrorCode.
309 *
310 * @param obj The object to format.
311 * @param appendTo Output parameter to receive result.
312 * Result is appended to existing contents.
313 * @param posIter On return, can be used to iterate over positions
314 * of fields generated by this format call. Can be
315 * NULL.
316 * @param status Output param filled with success/failure status.
317 * @return Reference to 'appendTo' parameter.
318 * @stable ICU 4.4
319 */
320 virtual UnicodeString& format(const Formattable& obj,
321 UnicodeString& appendTo,
322 FieldPositionIterator* posIter,
323 UErrorCode& status) const;
324
325 /**
326 * Parse a string to produce an object. This methods handles
327 * parsing of numeric strings into Formattable objects with numeric
328 * types.
329 * <P>
330 * Before calling, set parse_pos.index to the offset you want to
331 * start parsing at in the source. After calling, parse_pos.index
332 * indicates the position after the successfully parsed text. If
333 * an error occurs, parse_pos.index is unchanged.
334 * <P>
335 * When parsing, leading whitespace is discarded (with successful
336 * parse), while trailing whitespace is left as is.
337 * <P>
338 * See Format::parseObject() for more.
339 *
340 * @param source The string to be parsed into an object.
341 * @param result Formattable to be set to the parse result.
342 * If parse fails, return contents are undefined.
343 * @param parse_pos The position to start parsing at. Upon return
344 * this param is set to the position after the
345 * last character successfully parsed. If the
346 * source is not parsed successfully, this param
347 * will remain unchanged.
348 * @return A newly created Formattable* object, or NULL
349 * on failure. The caller owns this and should
350 * delete it when done.
351 * @stable ICU 2.0
352 */
353 virtual void parseObject(const UnicodeString& source,
354 Formattable& result,
355 ParsePosition& parse_pos) const;
356
357 /**
358 * Format a double number. These methods call the NumberFormat
359 * pure virtual format() methods with the default FieldPosition.
360 *
361 * @param number The value to be formatted.
362 * @param appendTo Output parameter to receive result.
363 * Result is appended to existing contents.
364 * @return Reference to 'appendTo' parameter.
365 * @stable ICU 2.0
366 */
367 UnicodeString& format( double number,
368 UnicodeString& appendTo) const;
369
370 /**
371 * Format a long number. These methods call the NumberFormat
372 * pure virtual format() methods with the default FieldPosition.
373 *
374 * @param number The value to be formatted.
375 * @param appendTo Output parameter to receive result.
376 * Result is appended to existing contents.
377 * @return Reference to 'appendTo' parameter.
378 * @stable ICU 2.0
379 */
380 UnicodeString& format( int32_t number,
381 UnicodeString& appendTo) const;
382
383 /**
384 * Format an int64 number. These methods call the NumberFormat
385 * pure virtual format() methods with the default FieldPosition.
386 *
387 * @param number The value to be formatted.
388 * @param appendTo Output parameter to receive result.
389 * Result is appended to existing contents.
390 * @return Reference to 'appendTo' parameter.
391 * @stable ICU 2.8
392 */
393 UnicodeString& format( int64_t number,
394 UnicodeString& appendTo) const;
395
396 /**
397 * Format a double number. Concrete subclasses must implement
398 * these pure virtual methods.
399 *
400 * @param number The value to be formatted.
401 * @param appendTo Output parameter to receive result.
402 * Result is appended to existing contents.
403 * @param pos On input: an alignment field, if desired.
404 * On output: the offsets of the alignment field.
405 * @return Reference to 'appendTo' parameter.
406 * @stable ICU 2.0
407 */
408 virtual UnicodeString& format(double number,
409 UnicodeString& appendTo,
410 FieldPosition& pos) const = 0;
411 /**
412 * Format a double number. By default, the parent function simply
413 * calls the base class and does not return an error status.
414 * Therefore, the status may be ignored in some subclasses.
415 *
416 * @param number The value to be formatted.
417 * @param appendTo Output parameter to receive result.
418 * Result is appended to existing contents.
419 * @param pos On input: an alignment field, if desired.
420 * On output: the offsets of the alignment field.
421 * @param status error status
422 * @return Reference to 'appendTo' parameter.
423 * @internal
424 */
425 virtual UnicodeString& format(double number,
426 UnicodeString& appendTo,
427 FieldPosition& pos,
428 UErrorCode &status) const;
429 /**
430 * Format a double number. Subclasses must implement
431 * this method.
432 *
433 * @param number The value to be formatted.
434 * @param appendTo Output parameter to receive result.
435 * Result is appended to existing contents.
436 * @param posIter On return, can be used to iterate over positions
437 * of fields generated by this format call.
438 * Can be NULL.
439 * @param status Output param filled with success/failure status.
440 * @return Reference to 'appendTo' parameter.
441 * @stable ICU 4.4
442 */
443 virtual UnicodeString& format(double number,
444 UnicodeString& appendTo,
445 FieldPositionIterator* posIter,
446 UErrorCode& status) const;
447 /**
448 * Format a long number. Concrete subclasses must implement
449 * these pure virtual methods.
450 *
451 * @param number The value to be formatted.
452 * @param appendTo Output parameter to receive result.
453 * Result is appended to existing contents.
454 * @param pos On input: an alignment field, if desired.
455 * On output: the offsets of the alignment field.
456 * @return Reference to 'appendTo' parameter.
457 * @stable ICU 2.0
458 */
459 virtual UnicodeString& format(int32_t number,
460 UnicodeString& appendTo,
461 FieldPosition& pos) const = 0;
462
463 /**
464 * Format a long number. Concrete subclasses may override
465 * this function to provide status return.
466 *
467 * @param number The value to be formatted.
468 * @param appendTo Output parameter to receive result.
469 * Result is appended to existing contents.
470 * @param pos On input: an alignment field, if desired.
471 * On output: the offsets of the alignment field.
472 * @param status the output status.
473 * @return Reference to 'appendTo' parameter.
474 * @internal
475 */
476 virtual UnicodeString& format(int32_t number,
477 UnicodeString& appendTo,
478 FieldPosition& pos,
479 UErrorCode &status) const;
480
481 /**
482 * Format an int32 number. Subclasses must implement
483 * this method.
484 *
485 * @param number The value to be formatted.
486 * @param appendTo Output parameter to receive result.
487 * Result is appended to existing contents.
488 * @param posIter On return, can be used to iterate over positions
489 * of fields generated by this format call.
490 * Can be NULL.
491 * @param status Output param filled with success/failure status.
492 * @return Reference to 'appendTo' parameter.
493 * @stable ICU 4.4
494 */
495 virtual UnicodeString& format(int32_t number,
496 UnicodeString& appendTo,
497 FieldPositionIterator* posIter,
498 UErrorCode& status) const;
499 /**
500 * Format an int64 number. (Not abstract to retain compatibility
501 * with earlier releases, however subclasses should override this
502 * method as it just delegates to format(int32_t number...);
503 *
504 * @param number The value to be formatted.
505 * @param appendTo Output parameter to receive result.
506 * Result is appended to existing contents.
507 * @param pos On input: an alignment field, if desired.
508 * On output: the offsets of the alignment field.
509 * @return Reference to 'appendTo' parameter.
510 * @stable ICU 2.8
511 */
512 virtual UnicodeString& format(int64_t number,
513 UnicodeString& appendTo,
514 FieldPosition& pos) const;
515
516 /**
517 * Format an int64 number. (Not abstract to retain compatibility
518 * with earlier releases, however subclasses should override this
519 * method as it just delegates to format(int32_t number...);
520 *
521 * @param number The value to be formatted.
522 * @param appendTo Output parameter to receive result.
523 * Result is appended to existing contents.
524 * @param pos On input: an alignment field, if desired.
525 * On output: the offsets of the alignment field.
526 * @param status Output param filled with success/failure status.
527 * @return Reference to 'appendTo' parameter.
528 * @internal
529 */
530 virtual UnicodeString& format(int64_t number,
531 UnicodeString& appendTo,
532 FieldPosition& pos,
533 UErrorCode& status) const;
534 /**
535 * Format an int64 number. Subclasses must implement
536 * this method.
537 *
538 * @param number The value to be formatted.
539 * @param appendTo Output parameter to receive result.
540 * Result is appended to existing contents.
541 * @param posIter On return, can be used to iterate over positions
542 * of fields generated by this format call.
543 * Can be NULL.
544 * @param status Output param filled with success/failure status.
545 * @return Reference to 'appendTo' parameter.
546 * @stable ICU 4.4
547 */
548 virtual UnicodeString& format(int64_t number,
549 UnicodeString& appendTo,
550 FieldPositionIterator* posIter,
551 UErrorCode& status) const;
552
553 /**
554 * Format a decimal number. Subclasses must implement
555 * this method. The syntax of the unformatted number is a "numeric string"
556 * as defined in the Decimal Arithmetic Specification, available at
557 * http://speleotrove.com/decimal
558 *
559 * @param number The unformatted number, as a string, to be formatted.
560 * @param appendTo Output parameter to receive result.
561 * Result is appended to existing contents.
562 * @param posIter On return, can be used to iterate over positions
563 * of fields generated by this format call.
564 * Can be NULL.
565 * @param status Output param filled with success/failure status.
566 * @return Reference to 'appendTo' parameter.
567 * @stable ICU 4.4
568 */
569 virtual UnicodeString& format(StringPiece number,
570 UnicodeString& appendTo,
571 FieldPositionIterator* posIter,
572 UErrorCode& status) const;
573
574// Can't use #ifndef U_HIDE_INTERNAL_API because these are virtual methods
575
576 /**
577 * Format a decimal number.
578 * The number is a DecimalQuantity wrapper onto a floating point decimal number.
579 * The default implementation in NumberFormat converts the decimal number
580 * to a double and formats that. Subclasses of NumberFormat that want
581 * to specifically handle big decimal numbers must override this method.
582 * class DecimalFormat does so.
583 *
584 * @param number The number, a DecimalQuantity format Decimal Floating Point.
585 * @param appendTo Output parameter to receive result.
586 * Result is appended to existing contents.
587 * @param posIter On return, can be used to iterate over positions
588 * of fields generated by this format call.
589 * @param status Output param filled with success/failure status.
590 * @return Reference to 'appendTo' parameter.
591 * @internal
592 */
593 virtual UnicodeString& format(const number::impl::DecimalQuantity &number,
594 UnicodeString& appendTo,
595 FieldPositionIterator* posIter,
596 UErrorCode& status) const;
597
598 /**
599 * Format a decimal number.
600 * The number is a DecimalQuantity wrapper onto a floating point decimal number.
601 * The default implementation in NumberFormat converts the decimal number
602 * to a double and formats that. Subclasses of NumberFormat that want
603 * to specifically handle big decimal numbers must override this method.
604 * class DecimalFormat does so.
605 *
606 * @param number The number, a DecimalQuantity format Decimal Floating Point.
607 * @param appendTo Output parameter to receive result.
608 * Result is appended to existing contents.
609 * @param pos On input: an alignment field, if desired.
610 * On output: the offsets of the alignment field.
611 * @param status Output param filled with success/failure status.
612 * @return Reference to 'appendTo' parameter.
613 * @internal
614 */
615 virtual UnicodeString& format(const number::impl::DecimalQuantity &number,
616 UnicodeString& appendTo,
617 FieldPosition& pos,
618 UErrorCode& status) const;
619
620 /**
621 * Return a long if possible (e.g. within range LONG_MAX,
622 * LONG_MAX], and with no decimals), otherwise a double. If
623 * IntegerOnly is set, will stop at a decimal point (or equivalent;
624 * e.g. for rational numbers "1 2/3", will stop after the 1).
625 * <P>
626 * If no object can be parsed, index is unchanged, and NULL is
627 * returned.
628 * <P>
629 * This is a pure virtual which concrete subclasses must implement.
630 *
631 * @param text The text to be parsed.
632 * @param result Formattable to be set to the parse result.
633 * If parse fails, return contents are undefined.
634 * @param parsePosition The position to start parsing at on input.
635 * On output, moved to after the last successfully
636 * parse character. On parse failure, does not change.
637 * @stable ICU 2.0
638 */
639 virtual void parse(const UnicodeString& text,
640 Formattable& result,
641 ParsePosition& parsePosition) const = 0;
642
643 /**
644 * Parse a string as a numeric value, and return a Formattable
645 * numeric object. This method parses integers only if IntegerOnly
646 * is set.
647 *
648 * @param text The text to be parsed.
649 * @param result Formattable to be set to the parse result.
650 * If parse fails, return contents are undefined.
651 * @param status Output parameter set to a failure error code
652 * when a failure occurs. The error code when the
653 * string fails to parse is U_INVALID_FORMAT_ERROR,
654 * unless overridden by a subclass.
655 * @see NumberFormat::isParseIntegerOnly
656 * @stable ICU 2.0
657 */
658 virtual void parse(const UnicodeString& text,
659 Formattable& result,
660 UErrorCode& status) const;
661
662 /**
663 * Parses text from the given string as a currency amount. Unlike
664 * the parse() method, this method will attempt to parse a generic
665 * currency name, searching for a match of this object's locale's
666 * currency display names, or for a 3-letter ISO currency code.
667 * This method will fail if this format is not a currency format,
668 * that is, if it does not contain the currency pattern symbol
669 * (U+00A4) in its prefix or suffix.
670 *
671 * @param text the string to parse
672 * @param pos input-output position; on input, the position within text
673 * to match; must have 0 <= pos.getIndex() < text.length();
674 * on output, the position after the last matched character.
675 * If the parse fails, the position in unchanged upon output.
676 * @return if parse succeeds, a pointer to a newly-created CurrencyAmount
677 * object (owned by the caller) containing information about
678 * the parsed currency; if parse fails, this is NULL.
679 * @stable ICU 49
680 */
681 virtual CurrencyAmount* parseCurrency(const UnicodeString& text,
682 ParsePosition& pos) const;
683
684 /**
685 * Return true if this format will parse numbers as integers
686 * only. For example in the English locale, with ParseIntegerOnly
687 * true, the string "1234." would be parsed as the integer value
688 * 1234 and parsing would stop at the "." character. Of course,
689 * the exact format accepted by the parse operation is locale
690 * dependant and determined by sub-classes of NumberFormat.
691 * @return true if this format will parse numbers as integers
692 * only.
693 * @stable ICU 2.0
694 */
695 UBool isParseIntegerOnly(void) const;
696
697 /**
698 * Sets whether or not numbers should be parsed as integers only.
699 * @param value set True, this format will parse numbers as integers
700 * only.
701 * @see isParseIntegerOnly
702 * @stable ICU 2.0
703 */
704 virtual void setParseIntegerOnly(UBool value);
705
706 /**
707 * Sets whether lenient parsing should be enabled (it is off by default).
708 *
709 * @param enable \c TRUE if lenient parsing should be used,
710 * \c FALSE otherwise.
711 * @stable ICU 4.8
712 */
713 virtual void setLenient(UBool enable);
714
715 /**
716 * Returns whether lenient parsing is enabled (it is off by default).
717 *
718 * @return \c TRUE if lenient parsing is enabled,
719 * \c FALSE otherwise.
720 * @see #setLenient
721 * @stable ICU 4.8
722 */
723 virtual UBool isLenient(void) const;
724
725 /**
726 * Create a default style NumberFormat for the current default locale.
727 * The default formatting style is locale dependent.
728 * <p>
729 * <strong>NOTE:</strong> New users are strongly encouraged to use
730 * {@link icu::number::NumberFormatter} instead of NumberFormat.
731 * @stable ICU 2.0
732 */
733 static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
734
735 /**
736 * Create a default style NumberFormat for the specified locale.
737 * The default formatting style is locale dependent.
738 * @param inLocale the given locale.
739 * <p>
740 * <strong>NOTE:</strong> New users are strongly encouraged to use
741 * {@link icu::number::NumberFormatter} instead of NumberFormat.
742 * @stable ICU 2.0
743 */
744 static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale,
745 UErrorCode&);
746
747 /**
748 * Create a specific style NumberFormat for the specified locale.
749 * <p>
750 * <strong>NOTE:</strong> New users are strongly encouraged to use
751 * {@link icu::number::NumberFormatter} instead of NumberFormat.
752 * @param desiredLocale the given locale.
753 * @param style the given style.
754 * @param errorCode Output param filled with success/failure status.
755 * @return A new NumberFormat instance.
756 * @stable ICU 4.8
757 */
758 static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale,
759 UNumberFormatStyle style,
760 UErrorCode& errorCode);
761
762#ifndef U_HIDE_INTERNAL_API
763
764 /**
765 * ICU use only.
766 * Creates NumberFormat instance without using the cache.
767 * @internal
768 */
769 static NumberFormat* internalCreateInstance(
770 const Locale& desiredLocale,
771 UNumberFormatStyle style,
772 UErrorCode& errorCode);
773
774 /**
775 * ICU use only.
776 * Returns handle to the shared, cached NumberFormat instance for given
777 * locale. On success, caller must call removeRef() on returned value
778 * once it is done with the shared instance.
779 * @internal
780 */
781 static const SharedNumberFormat* U_EXPORT2 createSharedInstance(
782 const Locale& inLocale, UNumberFormatStyle style, UErrorCode& status);
783
784#endif /* U_HIDE_INTERNAL_API */
785
786 /**
787 * Returns a currency format for the current default locale.
788 * <p>
789 * <strong>NOTE:</strong> New users are strongly encouraged to use
790 * {@link icu::number::NumberFormatter} instead of NumberFormat.
791 * @stable ICU 2.0
792 */
793 static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&);
794
795 /**
796 * Returns a currency format for the specified locale.
797 * <p>
798 * <strong>NOTE:</strong> New users are strongly encouraged to use
799 * {@link icu::number::NumberFormatter} instead of NumberFormat.
800 * @param inLocale the given locale.
801 * @stable ICU 2.0
802 */
803 static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale,
804 UErrorCode&);
805
806 /**
807 * Returns a percentage format for the current default locale.
808 * <p>
809 * <strong>NOTE:</strong> New users are strongly encouraged to use
810 * {@link icu::number::NumberFormatter} instead of NumberFormat.
811 * @stable ICU 2.0
812 */
813 static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&);
814
815 /**
816 * Returns a percentage format for the specified locale.
817 * <p>
818 * <strong>NOTE:</strong> New users are strongly encouraged to use
819 * {@link icu::number::NumberFormatter} instead of NumberFormat.
820 * @param inLocale the given locale.
821 * @stable ICU 2.0
822 */
823 static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale,
824 UErrorCode&);
825
826 /**
827 * Returns a scientific format for the current default locale.
828 * <p>
829 * <strong>NOTE:</strong> New users are strongly encouraged to use
830 * {@link icu::number::NumberFormatter} instead of NumberFormat.
831 * @stable ICU 2.0
832 */
833 static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&);
834
835 /**
836 * Returns a scientific format for the specified locale.
837 * <p>
838 * <strong>NOTE:</strong> New users are strongly encouraged to use
839 * {@link icu::number::NumberFormatter} instead of NumberFormat.
840 * @param inLocale the given locale.
841 * @stable ICU 2.0
842 */
843 static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale,
844 UErrorCode&);
845
846 /**
847 * Get the set of Locales for which NumberFormats are installed.
848 * @param count Output param to receive the size of the locales
849 * @stable ICU 2.0
850 */
851 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
852
853#if !UCONFIG_NO_SERVICE
854 /**
855 * Register a new NumberFormatFactory. The factory will be adopted.
856 * Because ICU may choose to cache NumberFormat objects internally,
857 * this must be called at application startup, prior to any calls to
858 * NumberFormat::createInstance to avoid undefined behavior.
859 * @param toAdopt the NumberFormatFactory instance to be adopted
860 * @param status the in/out status code, no special meanings are assigned
861 * @return a registry key that can be used to unregister this factory
862 * @stable ICU 2.6
863 */
864 static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status);
865
866 /**
867 * Unregister a previously-registered NumberFormatFactory using the key returned from the
868 * register call. Key becomes invalid after a successful call and should not be used again.
869 * The NumberFormatFactory corresponding to the key will be deleted.
870 * Because ICU may choose to cache NumberFormat objects internally,
871 * this should be called during application shutdown, after all calls to
872 * NumberFormat::createInstance to avoid undefined behavior.
873 * @param key the registry key returned by a previous call to registerFactory
874 * @param status the in/out status code, no special meanings are assigned
875 * @return TRUE if the factory for the key was successfully unregistered
876 * @stable ICU 2.6
877 */
878 static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
879
880 /**
881 * Return a StringEnumeration over the locales available at the time of the call,
882 * including registered locales.
883 * @return a StringEnumeration over the locales available at the time of the call
884 * @stable ICU 2.6
885 */
886 static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
887#endif /* UCONFIG_NO_SERVICE */
888
889 /**
890 * Returns true if grouping is used in this format. For example,
891 * in the English locale, with grouping on, the number 1234567
892 * might be formatted as "1,234,567". The grouping separator as
893 * well as the size of each group is locale dependent and is
894 * determined by sub-classes of NumberFormat.
895 * @see setGroupingUsed
896 * @stable ICU 2.0
897 */
898 UBool isGroupingUsed(void) const;
899
900 /**
901 * Set whether or not grouping will be used in this format.
902 * @param newValue True, grouping will be used in this format.
903 * @see getGroupingUsed
904 * @stable ICU 2.0
905 */
906 virtual void setGroupingUsed(UBool newValue);
907
908 /**
909 * Returns the maximum number of digits allowed in the integer portion of a
910 * number.
911 * @return the maximum number of digits allowed in the integer portion of a
912 * number.
913 * @see setMaximumIntegerDigits
914 * @stable ICU 2.0
915 */
916 int32_t getMaximumIntegerDigits(void) const;
917
918 /**
919 * Sets the maximum number of digits allowed in the integer portion of a
920 * number. maximumIntegerDigits must be >= minimumIntegerDigits. If the
921 * new value for maximumIntegerDigits is less than the current value
922 * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
923 * the new value.
924 *
925 * @param newValue the new value for the maximum number of digits
926 * allowed in the integer portion of a number.
927 * @see getMaximumIntegerDigits
928 * @stable ICU 2.0
929 */
930 virtual void setMaximumIntegerDigits(int32_t newValue);
931
932 /**
933 * Returns the minimum number of digits allowed in the integer portion of a
934 * number.
935 * @return the minimum number of digits allowed in the integer portion of a
936 * number.
937 * @see setMinimumIntegerDigits
938 * @stable ICU 2.0
939 */
940 int32_t getMinimumIntegerDigits(void) const;
941
942 /**
943 * Sets the minimum number of digits allowed in the integer portion of a
944 * number. minimumIntegerDigits must be &lt;= maximumIntegerDigits. If the
945 * new value for minimumIntegerDigits exceeds the current value
946 * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
947 * the new value.
948 * @param newValue the new value to be set.
949 * @see getMinimumIntegerDigits
950 * @stable ICU 2.0
951 */
952 virtual void setMinimumIntegerDigits(int32_t newValue);
953
954 /**
955 * Returns the maximum number of digits allowed in the fraction portion of a
956 * number.
957 * @return the maximum number of digits allowed in the fraction portion of a
958 * number.
959 * @see setMaximumFractionDigits
960 * @stable ICU 2.0
961 */
962 int32_t getMaximumFractionDigits(void) const;
963
964 /**
965 * Sets the maximum number of digits allowed in the fraction portion of a
966 * number. maximumFractionDigits must be >= minimumFractionDigits. If the
967 * new value for maximumFractionDigits is less than the current value
968 * of minimumFractionDigits, then minimumFractionDigits will also be set to
969 * the new value.
970 * @param newValue the new value to be set.
971 * @see getMaximumFractionDigits
972 * @stable ICU 2.0
973 */
974 virtual void setMaximumFractionDigits(int32_t newValue);
975
976 /**
977 * Returns the minimum number of digits allowed in the fraction portion of a
978 * number.
979 * @return the minimum number of digits allowed in the fraction portion of a
980 * number.
981 * @see setMinimumFractionDigits
982 * @stable ICU 2.0
983 */
984 int32_t getMinimumFractionDigits(void) const;
985
986 /**
987 * Sets the minimum number of digits allowed in the fraction portion of a
988 * number. minimumFractionDigits must be &lt;= maximumFractionDigits. If the
989 * new value for minimumFractionDigits exceeds the current value
990 * of maximumFractionDigits, then maximumIntegerDigits will also be set to
991 * the new value
992 * @param newValue the new value to be set.
993 * @see getMinimumFractionDigits
994 * @stable ICU 2.0
995 */
996 virtual void setMinimumFractionDigits(int32_t newValue);
997
998 /**
999 * Sets the currency used to display currency
1000 * amounts. This takes effect immediately, if this format is a
1001 * currency format. If this format is not a currency format, then
1002 * the currency is used if and when this object becomes a
1003 * currency format.
1004 * @param theCurrency a 3-letter ISO code indicating new currency
1005 * to use. It need not be null-terminated. May be the empty
1006 * string or NULL to indicate no currency.
1007 * @param ec input-output error code
1008 * @stable ICU 3.0
1009 */
1010 virtual void setCurrency(const char16_t* theCurrency, UErrorCode& ec);
1011
1012 /**
1013 * Gets the currency used to display currency
1014 * amounts. This may be an empty string for some subclasses.
1015 * @return a 3-letter null-terminated ISO code indicating
1016 * the currency in use, or a pointer to the empty string.
1017 * @stable ICU 2.6
1018 */
1019 const char16_t* getCurrency() const;
1020
1021 /**
1022 * Set a particular UDisplayContext value in the formatter, such as
1023 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE.
1024 * @param value The UDisplayContext value to set.
1025 * @param status Input/output status. If at entry this indicates a failure
1026 * status, the function will do nothing; otherwise this will be
1027 * updated with any new status from the function.
1028 * @stable ICU 53
1029 */
1030 virtual void setContext(UDisplayContext value, UErrorCode& status);
1031
1032 /**
1033 * Get the formatter's UDisplayContext value for the specified UDisplayContextType,
1034 * such as UDISPCTX_TYPE_CAPITALIZATION.
1035 * @param type The UDisplayContextType whose value to return
1036 * @param status Input/output status. If at entry this indicates a failure
1037 * status, the function will do nothing; otherwise this will be
1038 * updated with any new status from the function.
1039 * @return The UDisplayContextValue for the specified type.
1040 * @stable ICU 53
1041 */
1042 virtual UDisplayContext getContext(UDisplayContextType type, UErrorCode& status) const;
1043
1044 /**
1045 * Get the rounding mode. This will always return NumberFormat::ERoundingMode::kRoundUnnecessary
1046 * if the subclass does not support rounding.
1047 * @return A rounding mode
1048 * @stable ICU 60
1049 */
1050 virtual ERoundingMode getRoundingMode(void) const;
1051
1052 /**
1053 * Set the rounding mode. If a subclass does not support rounding, this will do nothing.
1054 * @param roundingMode A rounding mode
1055 * @stable ICU 60
1056 */
1057 virtual void setRoundingMode(ERoundingMode roundingMode);
1058
1059public:
1060
1061 /**
1062 * Return the class ID for this class. This is useful for
1063 * comparing to a return value from getDynamicClassID(). Note that,
1064 * because NumberFormat is an abstract base class, no fully constructed object
1065 * will have the class ID returned by NumberFormat::getStaticClassID().
1066 * @return The class ID for all objects of this class.
1067 * @stable ICU 2.0
1068 */
1069 static UClassID U_EXPORT2 getStaticClassID(void);
1070
1071 /**
1072 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override.
1073 * This method is to implement a simple version of RTTI, since not all
1074 * C++ compilers support genuine RTTI. Polymorphic operator==() and
1075 * clone() methods call this method.
1076 * <P>
1077 * @return The class ID for this object. All objects of a
1078 * given class have the same class ID. Objects of
1079 * other classes have different class IDs.
1080 * @stable ICU 2.0
1081 */
1082 virtual UClassID getDynamicClassID(void) const = 0;
1083
1084protected:
1085
1086 /**
1087 * Default constructor for subclass use only.
1088 * @stable ICU 2.0
1089 */
1090 NumberFormat();
1091
1092 /**
1093 * Copy constructor.
1094 * @stable ICU 2.0
1095 */
1096 NumberFormat(const NumberFormat&);
1097
1098 /**
1099 * Assignment operator.
1100 * @stable ICU 2.0
1101 */
1102 NumberFormat& operator=(const NumberFormat&);
1103
1104 /**
1105 * Returns the currency in effect for this formatter. Subclasses
1106 * should override this method as needed. Unlike getCurrency(),
1107 * this method should never return "".
1108 * @result output parameter for null-terminated result, which must
1109 * have a capacity of at least 4
1110 * @internal
1111 */
1112 virtual void getEffectiveCurrency(char16_t* result, UErrorCode& ec) const;
1113
1114#ifndef U_HIDE_INTERNAL_API
1115 /**
1116 * Creates the specified number format style of the desired locale.
1117 * If mustBeDecimalFormat is TRUE, then the returned pointer is
1118 * either a DecimalFormat or it is NULL.
1119 * @internal
1120 */
1121 static NumberFormat* makeInstance(const Locale& desiredLocale,
1122 UNumberFormatStyle style,
1123 UBool mustBeDecimalFormat,
1124 UErrorCode& errorCode);
1125#endif /* U_HIDE_INTERNAL_API */
1126
1127private:
1128
1129 static UBool isStyleSupported(UNumberFormatStyle style);
1130
1131 /**
1132 * Creates the specified decimal format style of the desired locale.
1133 * @param desiredLocale the given locale.
1134 * @param style the given style.
1135 * @param errorCode Output param filled with success/failure status.
1136 * @return A new NumberFormat instance.
1137 */
1138 static NumberFormat* makeInstance(const Locale& desiredLocale,
1139 UNumberFormatStyle style,
1140 UErrorCode& errorCode);
1141
1142 UBool fGroupingUsed;
1143 int32_t fMaxIntegerDigits;
1144 int32_t fMinIntegerDigits;
1145 int32_t fMaxFractionDigits;
1146 int32_t fMinFractionDigits;
1147
1148 protected:
1149 /** \internal */
1150 static const int32_t gDefaultMaxIntegerDigits;
1151 /** \internal */
1152 static const int32_t gDefaultMinIntegerDigits;
1153
1154 private:
1155 UBool fParseIntegerOnly;
1156 UBool fLenient; // TRUE => lenient parse is enabled
1157
1158 // ISO currency code
1159 char16_t fCurrency[4];
1160
1161 UDisplayContext fCapitalizationContext;
1162
1163 friend class ICUNumberFormatFactory; // access to makeInstance
1164 friend class ICUNumberFormatService;
1165 friend class ::NumberFormatTest; // access to isStyleSupported()
1166};
1167
1168#if !UCONFIG_NO_SERVICE
1169/**
1170 * A NumberFormatFactory is used to register new number formats. The factory
1171 * should be able to create any of the predefined formats for each locale it
1172 * supports. When registered, the locales it supports extend or override the
1173 * locale already supported by ICU.
1174 *
1175 * @stable ICU 2.6
1176 */
1177class U_I18N_API NumberFormatFactory : public UObject {
1178public:
1179
1180 /**
1181 * Destructor
1182 * @stable ICU 3.0
1183 */
1184 virtual ~NumberFormatFactory();
1185
1186 /**
1187 * Return true if this factory will be visible. Default is true.
1188 * If not visible, the locales supported by this factory will not
1189 * be listed by getAvailableLocales.
1190 * @stable ICU 2.6
1191 */
1192 virtual UBool visible(void) const = 0;
1193
1194 /**
1195 * Return the locale names directly supported by this factory. The number of names
1196 * is returned in count;
1197 * @stable ICU 2.6
1198 */
1199 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0;
1200
1201 /**
1202 * Return a number format of the appropriate type. If the locale
1203 * is not supported, return null. If the locale is supported, but
1204 * the type is not provided by this service, return null. Otherwise
1205 * return an appropriate instance of NumberFormat.
1206 * @stable ICU 2.6
1207 */
1208 virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0;
1209};
1210
1211/**
1212 * A NumberFormatFactory that supports a single locale. It can be visible or invisible.
1213 * @stable ICU 2.6
1214 */
1215class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory {
1216protected:
1217 /**
1218 * True if the locale supported by this factory is visible.
1219 * @stable ICU 2.6
1220 */
1221 const UBool _visible;
1222
1223 /**
1224 * The locale supported by this factory, as a UnicodeString.
1225 * @stable ICU 2.6
1226 */
1227 UnicodeString _id;
1228
1229public:
1230 /**
1231 * @stable ICU 2.6
1232 */
1233 SimpleNumberFormatFactory(const Locale& locale, UBool visible = TRUE);
1234
1235 /**
1236 * @stable ICU 3.0
1237 */
1238 virtual ~SimpleNumberFormatFactory();
1239
1240 /**
1241 * @stable ICU 2.6
1242 */
1243 virtual UBool visible(void) const;
1244
1245 /**
1246 * @stable ICU 2.6
1247 */
1248 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const;
1249};
1250#endif /* #if !UCONFIG_NO_SERVICE */
1251
1252// -------------------------------------
1253
1254inline UBool
1255NumberFormat::isParseIntegerOnly() const
1256{
1257 return fParseIntegerOnly;
1258}
1259
1260inline UBool
1261NumberFormat::isLenient() const
1262{
1263 return fLenient;
1264}
1265
1266U_NAMESPACE_END
1267
1268#endif /* #if !UCONFIG_NO_FORMATTING */
1269
1270#endif /* U_SHOW_CPLUSPLUS_API */
1271
1272#endif // _NUMFMT
1273//eof
1274