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