1 /*
2 ********************************************************************************
3 * Copyright (C) 1997-2013, 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
41 class NumberFormatTest;
42
43 U_NAMESPACE_BEGIN
44
45 #if !UCONFIG_NO_SERVICE
46 class NumberFormatFactory;
47 class StringEnumeration;
48 #endif
49
50 /**
51 *
52 * Abstract base class for all number formats. Provides interface for
53 * formatting and parsing a number. Also provides methods for
54 * determining which locales have number formats, and what their names
55 * are.
56 * <P>
57 * NumberFormat helps you to format and parse numbers for any locale.
58 * Your code can be completely independent of the locale conventions
59 * for decimal points, thousands-separators, or even the particular
60 * decimal digits used, or whether the number format is even decimal.
61 * <P>
62 * To format a number for the current Locale, use one of the static
63 * factory methods:
64 * <pre>
65 * \code
66 * double myNumber = 7.0;
67 * UnicodeString myString;
68 * UErrorCode success = U_ZERO_ERROR;
69 * NumberFormat* nf = NumberFormat::createInstance(success)
70 * nf->format(myNumber, myString);
71 * cout << " Example 1: " << myString << endl;
72 * \endcode
73 * </pre>
74 * Note that there are additional factory methods within subclasses of
75 * NumberFormat.
76 * <P>
77 * If you are formatting multiple numbers, it is more efficient to get
78 * the format and use it multiple times so that the system doesn't
79 * have to fetch the information about the local language and country
80 * conventions multiple times.
81 * <pre>
82 * \code
83 * UnicodeString myString;
84 * UErrorCode success = U_ZERO_ERROR;
85 * nf = NumberFormat::createInstance( success );
86 * int32_t a[] = { 123, 3333, -1234567 };
87 * const int32_t a_len = sizeof(a) / sizeof(a[0]);
88 * myString.remove();
89 * for (int32_t i = 0; i < a_len; i++) {
90 * nf->format(a[i], myString);
91 * myString += " ; ";
92 * }
93 * cout << " Example 2: " << myString << endl;
94 * \endcode
95 * </pre>
96 * To format a number for a different Locale, specify it in the
97 * call to createInstance().
98 * <pre>
99 * \code
100 * nf = NumberFormat::createInstance( Locale::FRENCH, success );
101 * \endcode
102 * </pre>
103 * You can use a NumberFormat to parse also.
104 * <pre>
105 * \code
106 * UErrorCode success;
107 * Formattable result(-999); // initialized with error code
108 * nf->parse(myString, result, success);
109 * \endcode
110 * </pre>
111 * Use createInstance to get the normal number format for that country.
112 * There are other static factory methods available. Use getCurrency
113 * to get the currency number format for that country. Use getPercent
114 * to get a format for displaying percentages. With this format, a
115 * fraction from 0.53 is displayed as 53%.
116 * <P>
117 * Starting from ICU 4.2, you can use createInstance() by passing in a 'style'
118 * as parameter to get the correct instance.
119 * For example,
120 * use createInstance(...kNumberStyle...) to get the normal number format,
121 * createInstance(...kPercentStyle...) to get a format for displaying
122 * percentage,
123 * createInstance(...kScientificStyle...) to get a format for displaying
124 * scientific number,
125 * createInstance(...kCurrencyStyle...) to get the currency number format,
126 * in which the currency is represented by its symbol, for example, "$3.00".
127 * createInstance(...kIsoCurrencyStyle...) to get the currency number format,
128 * in which the currency is represented by its ISO code, for example "USD3.00".
129 * createInstance(...kPluralCurrencyStyle...) 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 * 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 casting the NumberFormat you get from the factory methods to a
137 * DecimalNumberFormat. This will work for the vast majority of
138 * countries; just remember to put it in a try block in case you
139 * encounter an unusual one.
140 * <P>
141 * You can also use forms of the parse and format methods with
142 * ParsePosition and 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 FieldPosition in your format call, with field =
151 * INTEGER_FIELD. On output, 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 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 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 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 * @return Reference to 'appendTo' parameter.
480 * @internal
481 */
482 virtual UnicodeString& format(int64_t number,
483 UnicodeString& appendTo,
484 FieldPosition& pos,
485 UErrorCode& status) const;
486 /**
487 * Format an int64 number. Subclasses must implement
488 * this method.
489 *
490 * @param number The value to be formatted.
491 * @param appendTo Output parameter to receive result.
492 * Result is appended to existing contents.
493 * @param posIter On return, can be used to iterate over positions
494 * of fields generated by this format call.
495 * Can be NULL.
496 * @param status Output param filled with success/failure status.
497 * @return Reference to 'appendTo' parameter.
498 * @stable 4.4
499 */
500 virtual UnicodeString& format(int64_t number,
501 UnicodeString& appendTo,
502 FieldPositionIterator* posIter,
503 UErrorCode& status) const;
504
505 /**
506 * Format a decimal number. Subclasses must implement
507 * this method. The syntax of the unformatted number is a "numeric string"
508 * as defined in the Decimal Arithmetic Specification, available at
509 * http://speleotrove.com/decimal
510 *
511 * @param number The unformatted number, as a string, to be formatted.
512 * @param appendTo Output parameter to receive result.
513 * Result is appended to existing contents.
514 * @param posIter On return, can be used to iterate over positions
515 * of fields generated by this format call.
516 * Can be NULL.
517 * @param status Output param filled with success/failure status.
518 * @return Reference to 'appendTo' parameter.
519 * @stable 4.4
520 */
521 virtual UnicodeString& format(const StringPiece &number,
522 UnicodeString& appendTo,
523 FieldPositionIterator* posIter,
524 UErrorCode& status) const;
525 public:
526 /**
527 * Format a decimal number.
528 * The number is a DigitList wrapper onto a floating point decimal number.
529 * The default implementation in NumberFormat converts the decimal number
530 * to a double and formats that. Subclasses of NumberFormat that want
531 * to specifically handle big decimal numbers must override this method.
532 * class DecimalFormat does so.
533 *
534 * @param number The number, a DigitList format Decimal Floating Point.
535 * @param appendTo Output parameter to receive result.
536 * Result is appended to existing contents.
537 * @param posIter On return, can be used to iterate over positions
538 * of fields generated by this format call.
539 * @param status Output param filled with success/failure status.
540 * @return Reference to 'appendTo' parameter.
541 * @internal
542 */
543 virtual UnicodeString& format(const DigitList &number,
544 UnicodeString& appendTo,
545 FieldPositionIterator* posIter,
546 UErrorCode& status) const;
547
548 /**
549 * Format a decimal number.
550 * The number is a DigitList wrapper onto a floating point decimal number.
551 * The default implementation in NumberFormat converts the decimal number
552 * to a double and formats that. Subclasses of NumberFormat that want
553 * to specifically handle big decimal numbers must override this method.
554 * class DecimalFormat does so.
555 *
556 * @param number The number, a DigitList format Decimal Floating Point.
557 * @param appendTo Output parameter to receive result.
558 * Result is appended to existing contents.
559 * @param pos On input: an alignment field, if desired.
560 * On output: the offsets of the alignment field.
561 * @param status Output param filled with success/failure status.
562 * @return Reference to 'appendTo' parameter.
563 * @internal
564 */
565 virtual UnicodeString& format(const DigitList &number,
566 UnicodeString& appendTo,
567 FieldPosition& pos,
568 UErrorCode& status) const;
569
570 public:
571
572 /**
573 * Redeclared Format method.
574 * @param obj The object to be formatted.
575 * @param appendTo Output parameter to receive result.
576 * Result is appended to existing contents.
577 * @param status Output parameter set to a failure error code
578 * when a failure occurs.
579 * @return Reference to 'appendTo' parameter.
580 * @stable ICU 2.0
581 */
582 UnicodeString& format(const Formattable& obj,
583 UnicodeString& appendTo,
584 UErrorCode& status) const;
585
586 /**
587 * Return a long if possible (e.g. within range LONG_MAX,
588 * LONG_MAX], and with no decimals), otherwise a double. If
589 * IntegerOnly is set, will stop at a decimal point (or equivalent;
590 * e.g. for rational numbers "1 2/3", will stop after the 1).
591 * <P>
592 * If no object can be parsed, index is unchanged, and NULL is
593 * returned.
594 * <P>
595 * This is a pure virtual which concrete subclasses must implement.
596 *
597 * @param text The text to be parsed.
598 * @param result Formattable to be set to the parse result.
599 * If parse fails, return contents are undefined.
600 * @param parsePosition The position to start parsing at on input.
601 * On output, moved to after the last successfully
602 * parse character. On parse failure, does not change.
603 * @stable ICU 2.0
604 */
605 virtual void parse(const UnicodeString& text,
606 Formattable& result,
607 ParsePosition& parsePosition) const = 0;
608
609 /**
610 * Parse a string as a numeric value, and return a Formattable
611 * numeric object. This method parses integers only if IntegerOnly
612 * is set.
613 *
614 * @param text The text to be parsed.
615 * @param result Formattable to be set to the parse result.
616 * If parse fails, return contents are undefined.
617 * @param status Output parameter set to a failure error code
618 * when a failure occurs.
619 * @see NumberFormat::isParseIntegerOnly
620 * @stable ICU 2.0
621 */
622 virtual void parse(const UnicodeString& text,
623 Formattable& result,
624 UErrorCode& status) const;
625
626 /**
627 * Parses text from the given string as a currency amount. Unlike
628 * the parse() method, this method will attempt to parse a generic
629 * currency name, searching for a match of this object's locale's
630 * currency display names, or for a 3-letter ISO currency code.
631 * This method will fail if this format is not a currency format,
632 * that is, if it does not contain the currency pattern symbol
633 * (U+00A4) in its prefix or suffix.
634 *
635 * @param text the string to parse
636 * @param pos input-output position; on input, the position within text
637 * to match; must have 0 <= pos.getIndex() < text.length();
638 * on output, the position after the last matched character.
639 * If the parse fails, the position in unchanged upon output.
640 * @return if parse succeeds, a pointer to a newly-created CurrencyAmount
641 * object (owned by the caller) containing information about
642 * the parsed currency; if parse fails, this is NULL.
643 * @stable ICU 49
644 */
645 virtual CurrencyAmount* parseCurrency(const UnicodeString& text,
646 ParsePosition& pos) const;
647
648 /**
649 * Return true if this format will parse numbers as integers
650 * only. For example in the English locale, with ParseIntegerOnly
651 * true, the string "1234." would be parsed as the integer value
652 * 1234 and parsing would stop at the "." character. Of course,
653 * the exact format accepted by the parse operation is locale
654 * dependant and determined by sub-classes of NumberFormat.
655 * @return true if this format will parse numbers as integers
656 * only.
657 * @stable ICU 2.0
658 */
659 UBool isParseIntegerOnly(void) const;
660
661 /**
662 * Sets whether or not numbers should be parsed as integers only.
663 * @param value set True, this format will parse numbers as integers
664 * only.
665 * @see isParseIntegerOnly
666 * @stable ICU 2.0
667 */
668 virtual void setParseIntegerOnly(UBool value);
669
670 /**
671 * Sets whether lenient parsing should be enabled (it is off by default).
672 *
673 * @param enable <code>TRUE</code> if lenient parsing should be used,
674 * <code>FALSE</code> otherwise.
675 * @stable ICU 4.8
676 */
677 virtual void setLenient(UBool enable);
678
679 /**
680 * Returns whether lenient parsing is enabled (it is off by default).
681 *
682 * @return <code>TRUE</code> if lenient parsing is enabled,
683 * <code>FALSE</code> otherwise.
684 * @see #setLenient
685 * @stable ICU 4.8
686 */
687 virtual UBool isLenient(void) const;
688
689 /**
690 * Returns the default number format for the current default
691 * locale. The default format is one of the styles provided by
692 * the other factory methods: getNumberInstance,
693 * getCurrencyInstance or getPercentInstance. Exactly which one
694 * is locale dependant.
695 * @stable ICU 2.0
696 */
697 static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
698
699 /**
700 * Returns the default number format for the specified locale.
701 * The default format is one of the styles provided by the other
702 * factory methods: getNumberInstance, getCurrencyInstance or
703 * getPercentInstance. Exactly which one is locale dependant.
704 * @param inLocale the given locale.
705 * @stable ICU 2.0
706 */
707 static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale,
708 UErrorCode&);
709
710 /**
711 * Creates the specified decimal format style of the desired locale.
712 * @param desiredLocale the given locale.
713 * @param style the given style.
714 * @param errorCode Output param filled with success/failure status.
715 * @return A new NumberFormat instance.
716 * @stable ICU 4.8
717 */
718 static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale,
719 UNumberFormatStyle style,
720 UErrorCode& errorCode);
721
722 /**
723 * Returns a currency format for the current default locale.
724 * @stable ICU 2.0
725 */
726 static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&);
727
728 /**
729 * Returns a currency format for the specified locale.
730 * @param inLocale the given locale.
731 * @stable ICU 2.0
732 */
733 static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale,
734 UErrorCode&);
735
736 /**
737 * Returns a percentage format for the current default locale.
738 * @stable ICU 2.0
739 */
740 static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&);
741
742 /**
743 * Returns a percentage format for the specified locale.
744 * @param inLocale the given locale.
745 * @stable ICU 2.0
746 */
747 static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale,
748 UErrorCode&);
749
750 /**
751 * Returns a scientific format for the current default locale.
752 * @stable ICU 2.0
753 */
754 static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&);
755
756 /**
757 * Returns a scientific format for the specified locale.
758 * @param inLocale the given locale.
759 * @stable ICU 2.0
760 */
761 static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale,
762 UErrorCode&);
763
764 /**
765 * Get the set of Locales for which NumberFormats are installed.
766 * @param count Output param to receive the size of the locales
767 * @stable ICU 2.0
768 */
769 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
770
771 #if !UCONFIG_NO_SERVICE
772 /**
773 * Register a new NumberFormatFactory. The factory will be adopted.
774 * @param toAdopt the NumberFormatFactory instance to be adopted
775 * @param status the in/out status code, no special meanings are assigned
776 * @return a registry key that can be used to unregister this factory
777 * @stable ICU 2.6
778 */
779 static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status);
780
781 /**
782 * Unregister a previously-registered NumberFormatFactory using the key returned from the
783 * register call. Key becomes invalid after a successful call and should not be used again.
784 * The NumberFormatFactory corresponding to the key will be deleted.
785 * @param key the registry key returned by a previous call to registerFactory
786 * @param status the in/out status code, no special meanings are assigned
787 * @return TRUE if the factory for the key was successfully unregistered
788 * @stable ICU 2.6
789 */
790 static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
791
792 /**
793 * Return a StringEnumeration over the locales available at the time of the call,
794 * including registered locales.
795 * @return a StringEnumeration over the locales available at the time of the call
796 * @stable ICU 2.6
797 */
798 static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
799 #endif /* UCONFIG_NO_SERVICE */
800
801 /**
802 * Returns true if grouping is used in this format. For example,
803 * in the English locale, with grouping on, the number 1234567
804 * might be formatted as "1,234,567". The grouping separator as
805 * well as the size of each group is locale dependant and is
806 * determined by sub-classes of NumberFormat.
807 * @see setGroupingUsed
808 * @stable ICU 2.0
809 */
810 UBool isGroupingUsed(void) const;
811
812 /**
813 * Set whether or not grouping will be used in this format.
814 * @param newValue True, grouping will be used in this format.
815 * @see getGroupingUsed
816 * @stable ICU 2.0
817 */
818 virtual void setGroupingUsed(UBool newValue);
819
820 /**
821 * Returns the maximum number of digits allowed in the integer portion of a
822 * number.
823 * @return the maximum number of digits allowed in the integer portion of a
824 * number.
825 * @see setMaximumIntegerDigits
826 * @stable ICU 2.0
827 */
828 int32_t getMaximumIntegerDigits(void) const;
829
830 /**
831 * Sets the maximum number of digits allowed in the integer portion of a
832 * number. maximumIntegerDigits must be >= minimumIntegerDigits. If the
833 * new value for maximumIntegerDigits is less than the current value
834 * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
835 * the new value.
836 *
837 * @param newValue the new value for the maximum number of digits
838 * allowed in the integer portion of a number.
839 * @see getMaximumIntegerDigits
840 * @stable ICU 2.0
841 */
842 virtual void setMaximumIntegerDigits(int32_t newValue);
843
844 /**
845 * Returns the minimum number of digits allowed in the integer portion of a
846 * number.
847 * @return the minimum number of digits allowed in the integer portion of a
848 * number.
849 * @see setMinimumIntegerDigits
850 * @stable ICU 2.0
851 */
852 int32_t getMinimumIntegerDigits(void) const;
853
854 /**
855 * Sets the minimum number of digits allowed in the integer portion of a
856 * number. minimumIntegerDigits must be <= maximumIntegerDigits. If the
857 * new value for minimumIntegerDigits exceeds the current value
858 * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
859 * the new value.
860 * @param newValue the new value to be set.
861 * @see getMinimumIntegerDigits
862 * @stable ICU 2.0
863 */
864 virtual void setMinimumIntegerDigits(int32_t newValue);
865
866 /**
867 * Returns the maximum number of digits allowed in the fraction portion of a
868 * number.
869 * @return the maximum number of digits allowed in the fraction portion of a
870 * number.
871 * @see setMaximumFractionDigits
872 * @stable ICU 2.0
873 */
874 int32_t getMaximumFractionDigits(void) const;
875
876 /**
877 * Sets the maximum number of digits allowed in the fraction portion of a
878 * number. maximumFractionDigits must be >= minimumFractionDigits. If the
879 * new value for maximumFractionDigits is less than the current value
880 * of minimumFractionDigits, then minimumFractionDigits will also be set to
881 * the new value.
882 * @param newValue the new value to be set.
883 * @see getMaximumFractionDigits
884 * @stable ICU 2.0
885 */
886 virtual void setMaximumFractionDigits(int32_t newValue);
887
888 /**
889 * Returns the minimum number of digits allowed in the fraction portion of a
890 * number.
891 * @return the minimum number of digits allowed in the fraction portion of a
892 * number.
893 * @see setMinimumFractionDigits
894 * @stable ICU 2.0
895 */
896 int32_t getMinimumFractionDigits(void) const;
897
898 /**
899 * Sets the minimum number of digits allowed in the fraction portion of a
900 * number. minimumFractionDigits must be <= maximumFractionDigits. If the
901 * new value for minimumFractionDigits exceeds the current value
902 * of maximumFractionDigits, then maximumIntegerDigits will also be set to
903 * the new value
904 * @param newValue the new value to be set.
905 * @see getMinimumFractionDigits
906 * @stable ICU 2.0
907 */
908 virtual void setMinimumFractionDigits(int32_t newValue);
909
910 /**
911 * Sets the currency used to display currency
912 * amounts. This takes effect immediately, if this format is a
913 * currency format. If this format is not a currency format, then
914 * the currency is used if and when this object becomes a
915 * currency format.
916 * @param theCurrency a 3-letter ISO code indicating new currency
917 * to use. It need not be null-terminated. May be the empty
918 * string or NULL to indicate no currency.
919 * @param ec input-output error code
920 * @stable ICU 3.0
921 */
922 virtual void setCurrency(const UChar* theCurrency, UErrorCode& ec);
923
924 /**
925 * Gets the currency used to display currency
926 * amounts. This may be an empty string for some subclasses.
927 * @return a 3-letter null-terminated ISO code indicating
928 * the currency in use, or a pointer to the empty string.
929 * @stable ICU 2.6
930 */
931 const UChar* getCurrency() const;
932
933 public:
934
935 /**
936 * Return the class ID for this class. This is useful for
937 * comparing to a return value from getDynamicClassID(). Note that,
938 * because NumberFormat is an abstract base class, no fully constructed object
939 * will have the class ID returned by NumberFormat::getStaticClassID().
940 * @return The class ID for all objects of this class.
941 * @stable ICU 2.0
942 */
943 static UClassID U_EXPORT2 getStaticClassID(void);
944
945 /**
946 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override.
947 * This method is to implement a simple version of RTTI, since not all
948 * C++ compilers support genuine RTTI. Polymorphic operator==() and
949 * clone() methods call this method.
950 * <P>
951 * @return The class ID for this object. All objects of a
952 * given class have the same class ID. Objects of
953 * other classes have different class IDs.
954 * @stable ICU 2.0
955 */
956 virtual UClassID getDynamicClassID(void) const = 0;
957
958 protected:
959
960 /**
961 * Default constructor for subclass use only.
962 * @stable ICU 2.0
963 */
964 NumberFormat();
965
966 /**
967 * Copy constructor.
968 * @stable ICU 2.0
969 */
970 NumberFormat(const NumberFormat&);
971
972 /**
973 * Assignment operator.
974 * @stable ICU 2.0
975 */
976 NumberFormat& operator=(const NumberFormat&);
977
978 /**
979 * Returns the currency in effect for this formatter. Subclasses
980 * should override this method as needed. Unlike getCurrency(),
981 * this method should never return "".
982 * @result output parameter for null-terminated result, which must
983 * have a capacity of at least 4
984 * @internal
985 */
986 virtual void getEffectiveCurrency(UChar* result, UErrorCode& ec) const;
987
988 #ifndef U_HIDE_INTERNAL_API
989 /**
990 * Creates the specified number format style of the desired locale.
991 * If mustBeDecimalFormat is TRUE, then the returned pointer is
992 * either a DecimalFormat or it is NULL.
993 * @internal
994 */
995 static NumberFormat* makeInstance(const Locale& desiredLocale,
996 UNumberFormatStyle style,
997 UBool mustBeDecimalFormat,
998 UErrorCode& errorCode);
999 #endif /* U_HIDE_INTERNAL_API */
1000
1001 private:
1002
1003 static UBool isStyleSupported(UNumberFormatStyle style);
1004
1005 /**
1006 * Creates the specified decimal format style of the desired locale.
1007 * @param desiredLocale the given locale.
1008 * @param style the given style.
1009 * @param errorCode Output param filled with success/failure status.
1010 * @return A new NumberFormat instance.
1011 */
1012 static NumberFormat* makeInstance(const Locale& desiredLocale,
1013 UNumberFormatStyle style,
1014 UErrorCode& errorCode);
1015
1016 UBool fGroupingUsed;
1017 int32_t fMaxIntegerDigits;
1018 int32_t fMinIntegerDigits;
1019 int32_t fMaxFractionDigits;
1020 int32_t fMinFractionDigits;
1021 UBool fParseIntegerOnly;
1022 UBool fLenient; // TRUE => lenient parse is enabled
1023
1024 // ISO currency code
1025 UChar fCurrency[4];
1026
1027 friend class ICUNumberFormatFactory; // access to makeInstance
1028 friend class ICUNumberFormatService;
1029 friend class ::NumberFormatTest; // access to isStyleSupported()
1030 };
1031
1032 #if !UCONFIG_NO_SERVICE
1033 /**
1034 * A NumberFormatFactory is used to register new number formats. The factory
1035 * should be able to create any of the predefined formats for each locale it
1036 * supports. When registered, the locales it supports extend or override the
1037 * locale already supported by ICU.
1038 *
1039 * @stable ICU 2.6
1040 */
1041 class U_I18N_API NumberFormatFactory : public UObject {
1042 public:
1043
1044 /**
1045 * Destructor
1046 * @stable ICU 3.0
1047 */
1048 virtual ~NumberFormatFactory();
1049
1050 /**
1051 * Return true if this factory will be visible. Default is true.
1052 * If not visible, the locales supported by this factory will not
1053 * be listed by getAvailableLocales.
1054 * @stable ICU 2.6
1055 */
1056 virtual UBool visible(void) const = 0;
1057
1058 /**
1059 * Return the locale names directly supported by this factory. The number of names
1060 * is returned in count;
1061 * @stable ICU 2.6
1062 */
1063 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0;
1064
1065 /**
1066 * Return a number format of the appropriate type. If the locale
1067 * is not supported, return null. If the locale is supported, but
1068 * the type is not provided by this service, return null. Otherwise
1069 * return an appropriate instance of NumberFormat.
1070 * @stable ICU 2.6
1071 */
1072 virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0;
1073 };
1074
1075 /**
1076 * A NumberFormatFactory that supports a single locale. It can be visible or invisible.
1077 * @stable ICU 2.6
1078 */
1079 class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory {
1080 protected:
1081 /**
1082 * True if the locale supported by this factory is visible.
1083 * @stable ICU 2.6
1084 */
1085 const UBool _visible;
1086
1087 /**
1088 * The locale supported by this factory, as a UnicodeString.
1089 * @stable ICU 2.6
1090 */
1091 UnicodeString _id;
1092
1093 public:
1094 /**
1095 * @stable ICU 2.6
1096 */
1097 SimpleNumberFormatFactory(const Locale& locale, UBool visible = TRUE);
1098
1099 /**
1100 * @stable ICU 3.0
1101 */
1102 virtual ~SimpleNumberFormatFactory();
1103
1104 /**
1105 * @stable ICU 2.6
1106 */
1107 virtual UBool visible(void) const;
1108
1109 /**
1110 * @stable ICU 2.6
1111 */
1112 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const;
1113 };
1114 #endif /* #if !UCONFIG_NO_SERVICE */
1115
1116 // -------------------------------------
1117
1118 inline UBool
isParseIntegerOnly()1119 NumberFormat::isParseIntegerOnly() const
1120 {
1121 return fParseIntegerOnly;
1122 }
1123
1124 inline UBool
isLenient()1125 NumberFormat::isLenient() const
1126 {
1127 return fLenient;
1128 }
1129
1130 inline UnicodeString&
format(const Formattable & obj,UnicodeString & appendTo,UErrorCode & status)1131 NumberFormat::format(const Formattable& obj,
1132 UnicodeString& appendTo,
1133 UErrorCode& status) const {
1134 return Format::format(obj, appendTo, status);
1135 }
1136
1137 U_NAMESPACE_END
1138
1139 #endif /* #if !UCONFIG_NO_FORMATTING */
1140
1141 #endif // _NUMFMT
1142 //eof
1143