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