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