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