intl/icu/source/i18n/unicode/numfmt.h@fc2d59ddac77
intl/icu/source/i18n/unicode/numfmt.h
Wed, 31 Dec 2014 07:22:50 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 07:22:50 +0100
- branch
- TOR_BUG_3246
- changeset 4
- fc2d59ddac77
- permissions
- -rw-r--r--
Correct previous dual key logic pending first delivery installment.
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 */
21 #ifndef NUMFMT_H
22 #define NUMFMT_H
25 #include "unicode/utypes.h"
27 /**
28 * \file
29 * \brief C++ API: Abstract base class for all number formats.
30 */
32 #if !UCONFIG_NO_FORMATTING
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"
41 class NumberFormatTest;
43 U_NAMESPACE_BEGIN
45 #if !UCONFIG_NO_SERVICE
46 class NumberFormatFactory;
47 class StringEnumeration;
48 #endif
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,
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 };
220 /**
221 * Destructor.
222 * @stable ICU 2.0
223 */
224 virtual ~NumberFormat();
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;
235 using Format::format;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
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;
570 public:
572 /**
573 * Return a long if possible (e.g. within range LONG_MAX,
574 * LONG_MAX], and with no decimals), otherwise a double. If
575 * IntegerOnly is set, will stop at a decimal point (or equivalent;
576 * e.g. for rational numbers "1 2/3", will stop after the 1).
577 * <P>
578 * If no object can be parsed, index is unchanged, and NULL is
579 * returned.
580 * <P>
581 * This is a pure virtual which concrete subclasses must implement.
582 *
583 * @param text The text to be parsed.
584 * @param result Formattable to be set to the parse result.
585 * If parse fails, return contents are undefined.
586 * @param parsePosition The position to start parsing at on input.
587 * On output, moved to after the last successfully
588 * parse character. On parse failure, does not change.
589 * @stable ICU 2.0
590 */
591 virtual void parse(const UnicodeString& text,
592 Formattable& result,
593 ParsePosition& parsePosition) const = 0;
595 /**
596 * Parse a string as a numeric value, and return a Formattable
597 * numeric object. This method parses integers only if IntegerOnly
598 * is set.
599 *
600 * @param text The text to be parsed.
601 * @param result Formattable to be set to the parse result.
602 * If parse fails, return contents are undefined.
603 * @param status Output parameter set to a failure error code
604 * when a failure occurs.
605 * @see NumberFormat::isParseIntegerOnly
606 * @stable ICU 2.0
607 */
608 virtual void parse(const UnicodeString& text,
609 Formattable& result,
610 UErrorCode& status) const;
612 /**
613 * Parses text from the given string as a currency amount. Unlike
614 * the parse() method, this method will attempt to parse a generic
615 * currency name, searching for a match of this object's locale's
616 * currency display names, or for a 3-letter ISO currency code.
617 * This method will fail if this format is not a currency format,
618 * that is, if it does not contain the currency pattern symbol
619 * (U+00A4) in its prefix or suffix.
620 *
621 * @param text the string to parse
622 * @param pos input-output position; on input, the position within text
623 * to match; must have 0 <= pos.getIndex() < text.length();
624 * on output, the position after the last matched character.
625 * If the parse fails, the position in unchanged upon output.
626 * @return if parse succeeds, a pointer to a newly-created CurrencyAmount
627 * object (owned by the caller) containing information about
628 * the parsed currency; if parse fails, this is NULL.
629 * @stable ICU 49
630 */
631 virtual CurrencyAmount* parseCurrency(const UnicodeString& text,
632 ParsePosition& pos) const;
634 /**
635 * Return true if this format will parse numbers as integers
636 * only. For example in the English locale, with ParseIntegerOnly
637 * true, the string "1234." would be parsed as the integer value
638 * 1234 and parsing would stop at the "." character. Of course,
639 * the exact format accepted by the parse operation is locale
640 * dependant and determined by sub-classes of NumberFormat.
641 * @return true if this format will parse numbers as integers
642 * only.
643 * @stable ICU 2.0
644 */
645 UBool isParseIntegerOnly(void) const;
647 /**
648 * Sets whether or not numbers should be parsed as integers only.
649 * @param value set True, this format will parse numbers as integers
650 * only.
651 * @see isParseIntegerOnly
652 * @stable ICU 2.0
653 */
654 virtual void setParseIntegerOnly(UBool value);
656 /**
657 * Sets whether lenient parsing should be enabled (it is off by default).
658 *
659 * @param enable <code>TRUE</code> if lenient parsing should be used,
660 * <code>FALSE</code> otherwise.
661 * @stable ICU 4.8
662 */
663 virtual void setLenient(UBool enable);
665 /**
666 * Returns whether lenient parsing is enabled (it is off by default).
667 *
668 * @return <code>TRUE</code> if lenient parsing is enabled,
669 * <code>FALSE</code> otherwise.
670 * @see #setLenient
671 * @stable ICU 4.8
672 */
673 virtual UBool isLenient(void) const;
675 /**
676 * Returns the default number format for the current default
677 * locale. The default format is one of the styles provided by
678 * the other factory methods: getNumberInstance,
679 * getCurrencyInstance or getPercentInstance. Exactly which one
680 * is locale dependant.
681 * @stable ICU 2.0
682 */
683 static NumberFormat* U_EXPORT2 createInstance(UErrorCode&);
685 /**
686 * Returns the default number format for the specified locale.
687 * The default format is one of the styles provided by the other
688 * factory methods: getNumberInstance, getCurrencyInstance or
689 * getPercentInstance. Exactly which one is locale dependant.
690 * @param inLocale the given locale.
691 * @stable ICU 2.0
692 */
693 static NumberFormat* U_EXPORT2 createInstance(const Locale& inLocale,
694 UErrorCode&);
696 /**
697 * Creates the specified decimal format style of the desired locale.
698 * @param desiredLocale the given locale.
699 * @param style the given style.
700 * @param errorCode Output param filled with success/failure status.
701 * @return A new NumberFormat instance.
702 * @stable ICU 4.8
703 */
704 static NumberFormat* U_EXPORT2 createInstance(const Locale& desiredLocale,
705 UNumberFormatStyle style,
706 UErrorCode& errorCode);
708 /**
709 * Returns a currency format for the current default locale.
710 * @stable ICU 2.0
711 */
712 static NumberFormat* U_EXPORT2 createCurrencyInstance(UErrorCode&);
714 /**
715 * Returns a currency format for the specified locale.
716 * @param inLocale the given locale.
717 * @stable ICU 2.0
718 */
719 static NumberFormat* U_EXPORT2 createCurrencyInstance(const Locale& inLocale,
720 UErrorCode&);
722 /**
723 * Returns a percentage format for the current default locale.
724 * @stable ICU 2.0
725 */
726 static NumberFormat* U_EXPORT2 createPercentInstance(UErrorCode&);
728 /**
729 * Returns a percentage format for the specified locale.
730 * @param inLocale the given locale.
731 * @stable ICU 2.0
732 */
733 static NumberFormat* U_EXPORT2 createPercentInstance(const Locale& inLocale,
734 UErrorCode&);
736 /**
737 * Returns a scientific format for the current default locale.
738 * @stable ICU 2.0
739 */
740 static NumberFormat* U_EXPORT2 createScientificInstance(UErrorCode&);
742 /**
743 * Returns a scientific format for the specified locale.
744 * @param inLocale the given locale.
745 * @stable ICU 2.0
746 */
747 static NumberFormat* U_EXPORT2 createScientificInstance(const Locale& inLocale,
748 UErrorCode&);
750 /**
751 * Get the set of Locales for which NumberFormats are installed.
752 * @param count Output param to receive the size of the locales
753 * @stable ICU 2.0
754 */
755 static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
757 #if !UCONFIG_NO_SERVICE
758 /**
759 * Register a new NumberFormatFactory. The factory will be adopted.
760 * @param toAdopt the NumberFormatFactory instance to be adopted
761 * @param status the in/out status code, no special meanings are assigned
762 * @return a registry key that can be used to unregister this factory
763 * @stable ICU 2.6
764 */
765 static URegistryKey U_EXPORT2 registerFactory(NumberFormatFactory* toAdopt, UErrorCode& status);
767 /**
768 * Unregister a previously-registered NumberFormatFactory using the key returned from the
769 * register call. Key becomes invalid after a successful call and should not be used again.
770 * The NumberFormatFactory corresponding to the key will be deleted.
771 * @param key the registry key returned by a previous call to registerFactory
772 * @param status the in/out status code, no special meanings are assigned
773 * @return TRUE if the factory for the key was successfully unregistered
774 * @stable ICU 2.6
775 */
776 static UBool U_EXPORT2 unregister(URegistryKey key, UErrorCode& status);
778 /**
779 * Return a StringEnumeration over the locales available at the time of the call,
780 * including registered locales.
781 * @return a StringEnumeration over the locales available at the time of the call
782 * @stable ICU 2.6
783 */
784 static StringEnumeration* U_EXPORT2 getAvailableLocales(void);
785 #endif /* UCONFIG_NO_SERVICE */
787 /**
788 * Returns true if grouping is used in this format. For example,
789 * in the English locale, with grouping on, the number 1234567
790 * might be formatted as "1,234,567". The grouping separator as
791 * well as the size of each group is locale dependant and is
792 * determined by sub-classes of NumberFormat.
793 * @see setGroupingUsed
794 * @stable ICU 2.0
795 */
796 UBool isGroupingUsed(void) const;
798 /**
799 * Set whether or not grouping will be used in this format.
800 * @param newValue True, grouping will be used in this format.
801 * @see getGroupingUsed
802 * @stable ICU 2.0
803 */
804 virtual void setGroupingUsed(UBool newValue);
806 /**
807 * Returns the maximum number of digits allowed in the integer portion of a
808 * number.
809 * @return the maximum number of digits allowed in the integer portion of a
810 * number.
811 * @see setMaximumIntegerDigits
812 * @stable ICU 2.0
813 */
814 int32_t getMaximumIntegerDigits(void) const;
816 /**
817 * Sets the maximum number of digits allowed in the integer portion of a
818 * number. maximumIntegerDigits must be >= minimumIntegerDigits. If the
819 * new value for maximumIntegerDigits is less than the current value
820 * of minimumIntegerDigits, then minimumIntegerDigits will also be set to
821 * the new value.
822 *
823 * @param newValue the new value for the maximum number of digits
824 * allowed in the integer portion of a number.
825 * @see getMaximumIntegerDigits
826 * @stable ICU 2.0
827 */
828 virtual void setMaximumIntegerDigits(int32_t newValue);
830 /**
831 * Returns the minimum number of digits allowed in the integer portion of a
832 * number.
833 * @return the minimum number of digits allowed in the integer portion of a
834 * number.
835 * @see setMinimumIntegerDigits
836 * @stable ICU 2.0
837 */
838 int32_t getMinimumIntegerDigits(void) const;
840 /**
841 * Sets the minimum number of digits allowed in the integer portion of a
842 * number. minimumIntegerDigits must be <= maximumIntegerDigits. If the
843 * new value for minimumIntegerDigits exceeds the current value
844 * of maximumIntegerDigits, then maximumIntegerDigits will also be set to
845 * the new value.
846 * @param newValue the new value to be set.
847 * @see getMinimumIntegerDigits
848 * @stable ICU 2.0
849 */
850 virtual void setMinimumIntegerDigits(int32_t newValue);
852 /**
853 * Returns the maximum number of digits allowed in the fraction portion of a
854 * number.
855 * @return the maximum number of digits allowed in the fraction portion of a
856 * number.
857 * @see setMaximumFractionDigits
858 * @stable ICU 2.0
859 */
860 int32_t getMaximumFractionDigits(void) const;
862 /**
863 * Sets the maximum number of digits allowed in the fraction portion of a
864 * number. maximumFractionDigits must be >= minimumFractionDigits. If the
865 * new value for maximumFractionDigits is less than the current value
866 * of minimumFractionDigits, then minimumFractionDigits will also be set to
867 * the new value.
868 * @param newValue the new value to be set.
869 * @see getMaximumFractionDigits
870 * @stable ICU 2.0
871 */
872 virtual void setMaximumFractionDigits(int32_t newValue);
874 /**
875 * Returns the minimum number of digits allowed in the fraction portion of a
876 * number.
877 * @return the minimum number of digits allowed in the fraction portion of a
878 * number.
879 * @see setMinimumFractionDigits
880 * @stable ICU 2.0
881 */
882 int32_t getMinimumFractionDigits(void) const;
884 /**
885 * Sets the minimum number of digits allowed in the fraction portion of a
886 * number. minimumFractionDigits must be <= maximumFractionDigits. If the
887 * new value for minimumFractionDigits exceeds the current value
888 * of maximumFractionDigits, then maximumIntegerDigits will also be set to
889 * the new value
890 * @param newValue the new value to be set.
891 * @see getMinimumFractionDigits
892 * @stable ICU 2.0
893 */
894 virtual void setMinimumFractionDigits(int32_t newValue);
896 /**
897 * Sets the currency used to display currency
898 * amounts. This takes effect immediately, if this format is a
899 * currency format. If this format is not a currency format, then
900 * the currency is used if and when this object becomes a
901 * currency format.
902 * @param theCurrency a 3-letter ISO code indicating new currency
903 * to use. It need not be null-terminated. May be the empty
904 * string or NULL to indicate no currency.
905 * @param ec input-output error code
906 * @stable ICU 3.0
907 */
908 virtual void setCurrency(const UChar* theCurrency, UErrorCode& ec);
910 /**
911 * Gets the currency used to display currency
912 * amounts. This may be an empty string for some subclasses.
913 * @return a 3-letter null-terminated ISO code indicating
914 * the currency in use, or a pointer to the empty string.
915 * @stable ICU 2.6
916 */
917 const UChar* getCurrency() const;
919 public:
921 /**
922 * Return the class ID for this class. This is useful for
923 * comparing to a return value from getDynamicClassID(). Note that,
924 * because NumberFormat is an abstract base class, no fully constructed object
925 * will have the class ID returned by NumberFormat::getStaticClassID().
926 * @return The class ID for all objects of this class.
927 * @stable ICU 2.0
928 */
929 static UClassID U_EXPORT2 getStaticClassID(void);
931 /**
932 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override.
933 * This method is to implement a simple version of RTTI, since not all
934 * C++ compilers support genuine RTTI. Polymorphic operator==() and
935 * clone() methods call this method.
936 * <P>
937 * @return The class ID for this object. All objects of a
938 * given class have the same class ID. Objects of
939 * other classes have different class IDs.
940 * @stable ICU 2.0
941 */
942 virtual UClassID getDynamicClassID(void) const = 0;
944 protected:
946 /**
947 * Default constructor for subclass use only.
948 * @stable ICU 2.0
949 */
950 NumberFormat();
952 /**
953 * Copy constructor.
954 * @stable ICU 2.0
955 */
956 NumberFormat(const NumberFormat&);
958 /**
959 * Assignment operator.
960 * @stable ICU 2.0
961 */
962 NumberFormat& operator=(const NumberFormat&);
964 /**
965 * Returns the currency in effect for this formatter. Subclasses
966 * should override this method as needed. Unlike getCurrency(),
967 * this method should never return "".
968 * @result output parameter for null-terminated result, which must
969 * have a capacity of at least 4
970 * @internal
971 */
972 virtual void getEffectiveCurrency(UChar* result, UErrorCode& ec) const;
974 #ifndef U_HIDE_INTERNAL_API
975 /**
976 * Creates the specified number format style of the desired locale.
977 * If mustBeDecimalFormat is TRUE, then the returned pointer is
978 * either a DecimalFormat or it is NULL.
979 * @internal
980 */
981 static NumberFormat* makeInstance(const Locale& desiredLocale,
982 UNumberFormatStyle style,
983 UBool mustBeDecimalFormat,
984 UErrorCode& errorCode);
985 #endif /* U_HIDE_INTERNAL_API */
987 private:
989 static UBool isStyleSupported(UNumberFormatStyle style);
991 /**
992 * Creates the specified decimal format style of the desired locale.
993 * @param desiredLocale the given locale.
994 * @param style the given style.
995 * @param errorCode Output param filled with success/failure status.
996 * @return A new NumberFormat instance.
997 */
998 static NumberFormat* makeInstance(const Locale& desiredLocale,
999 UNumberFormatStyle style,
1000 UErrorCode& errorCode);
1002 UBool fGroupingUsed;
1003 int32_t fMaxIntegerDigits;
1004 int32_t fMinIntegerDigits;
1005 int32_t fMaxFractionDigits;
1006 int32_t fMinFractionDigits;
1008 protected:
1009 static const int32_t gDefaultMaxIntegerDigits;
1010 static const int32_t gDefaultMinIntegerDigits;
1012 private:
1013 UBool fParseIntegerOnly;
1014 UBool fLenient; // TRUE => lenient parse is enabled
1016 // ISO currency code
1017 UChar fCurrency[4];
1019 friend class ICUNumberFormatFactory; // access to makeInstance
1020 friend class ICUNumberFormatService;
1021 friend class ::NumberFormatTest; // access to isStyleSupported()
1022 };
1024 #if !UCONFIG_NO_SERVICE
1025 /**
1026 * A NumberFormatFactory is used to register new number formats. The factory
1027 * should be able to create any of the predefined formats for each locale it
1028 * supports. When registered, the locales it supports extend or override the
1029 * locale already supported by ICU.
1030 *
1031 * @stable ICU 2.6
1032 */
1033 class U_I18N_API NumberFormatFactory : public UObject {
1034 public:
1036 /**
1037 * Destructor
1038 * @stable ICU 3.0
1039 */
1040 virtual ~NumberFormatFactory();
1042 /**
1043 * Return true if this factory will be visible. Default is true.
1044 * If not visible, the locales supported by this factory will not
1045 * be listed by getAvailableLocales.
1046 * @stable ICU 2.6
1047 */
1048 virtual UBool visible(void) const = 0;
1050 /**
1051 * Return the locale names directly supported by this factory. The number of names
1052 * is returned in count;
1053 * @stable ICU 2.6
1054 */
1055 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const = 0;
1057 /**
1058 * Return a number format of the appropriate type. If the locale
1059 * is not supported, return null. If the locale is supported, but
1060 * the type is not provided by this service, return null. Otherwise
1061 * return an appropriate instance of NumberFormat.
1062 * @stable ICU 2.6
1063 */
1064 virtual NumberFormat* createFormat(const Locale& loc, UNumberFormatStyle formatType) = 0;
1065 };
1067 /**
1068 * A NumberFormatFactory that supports a single locale. It can be visible or invisible.
1069 * @stable ICU 2.6
1070 */
1071 class U_I18N_API SimpleNumberFormatFactory : public NumberFormatFactory {
1072 protected:
1073 /**
1074 * True if the locale supported by this factory is visible.
1075 * @stable ICU 2.6
1076 */
1077 const UBool _visible;
1079 /**
1080 * The locale supported by this factory, as a UnicodeString.
1081 * @stable ICU 2.6
1082 */
1083 UnicodeString _id;
1085 public:
1086 /**
1087 * @stable ICU 2.6
1088 */
1089 SimpleNumberFormatFactory(const Locale& locale, UBool visible = TRUE);
1091 /**
1092 * @stable ICU 3.0
1093 */
1094 virtual ~SimpleNumberFormatFactory();
1096 /**
1097 * @stable ICU 2.6
1098 */
1099 virtual UBool visible(void) const;
1101 /**
1102 * @stable ICU 2.6
1103 */
1104 virtual const UnicodeString * getSupportedIDs(int32_t &count, UErrorCode& status) const;
1105 };
1106 #endif /* #if !UCONFIG_NO_SERVICE */
1108 // -------------------------------------
1110 inline UBool
1111 NumberFormat::isParseIntegerOnly() const
1112 {
1113 return fParseIntegerOnly;
1114 }
1116 inline UBool
1117 NumberFormat::isLenient() const
1118 {
1119 return fLenient;
1120 }
1122 U_NAMESPACE_END
1124 #endif /* #if !UCONFIG_NO_FORMATTING */
1126 #endif // _NUMFMT
1127 //eof
