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