X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/374ca955a76ecab1204ca8bfa63ff9238d998416..c5116b9f5a666b9d59f443b3770acd6ef64dc6c3:/icuSources/i18n/unicode/decimfmt.h diff --git a/icuSources/i18n/unicode/decimfmt.h b/icuSources/i18n/unicode/decimfmt.h index 4fe6d32c..6e6a7ff0 100644 --- a/icuSources/i18n/unicode/decimfmt.h +++ b/icuSources/i18n/unicode/decimfmt.h @@ -1,6 +1,8 @@ +// © 2016 and later: Unicode, Inc. and others. +// License & terms of use: http://www.unicode.org/copyright.html /* ******************************************************************************** -* Copyright (C) 1997-2004, International Business Machines +* Copyright (C) 1997-2016, International Business Machines * Corporation and others. All Rights Reserved. ******************************************************************************** * @@ -17,52 +19,81 @@ * 07/10/97 helena Made ParsePosition a class and get rid of the function * hiding problems. * 09/09/97 aliu Ported over support for exponential formats. -* 07/20/98 stephen Changed documentation +* 07/20/98 stephen Changed documentation +* 01/30/13 emmons Added Scaling methods ******************************************************************************** */ - + #ifndef DECIMFMT_H #define DECIMFMT_H - + #include "unicode/utypes.h" +/** + * \file + * \brief C++ API: Compatibility APIs for decimal formatting. + */ #if !UCONFIG_NO_FORMATTING #include "unicode/dcfmtsym.h" #include "unicode/numfmt.h" #include "unicode/locid.h" +#include "unicode/fpositer.h" +#include "unicode/stringpiece.h" +#include "unicode/curramt.h" +#include "unicode/enumset.h" +#if U_SHOW_CPLUSPLUS_API U_NAMESPACE_BEGIN -class DigitList; -class ChoiceFormat; +class CurrencyPluralInfo; +class CompactDecimalFormat; + +namespace number { +class LocalizedNumberFormatter; +class FormattedNumber; +namespace impl { +class DecimalQuantity; +struct DecimalFormatFields; +} +} + +namespace numparse { +namespace impl { +class NumberParserImpl; +} +} /** + * **IMPORTANT:** New users are strongly encouraged to see if + * numberformatter.h fits their use case. Although not deprecated, this header + * is provided for backwards compatibility only. + * * DecimalFormat is a concrete subclass of NumberFormat that formats decimal * numbers. It has a variety of features designed to make it possible to parse * and format numbers in any locale, including support for Western, Arabic, or * Indic digits. It also supports different flavors of numbers, including * integers ("123"), fixed-point numbers ("123.4"), scientific notation - * ("1.23E4"), percentages ("12%"), and currency amounts ("$123"). All of these - * flavors can be easily localized. + * ("1.23E4"), percentages ("12%"), and currency amounts ("$123", "USD123", + * "123 US dollars"). All of these flavors can be easily localized. * - *

To obtain a NumberFormat for a specific locale (including the default + * To obtain a NumberFormat for a specific locale (including the default * locale) call one of NumberFormat's factory methods such as * createInstance(). Do not call the DecimalFormat constructors directly, unless * you know what you are doing, since the NumberFormat factory methods may * return subclasses other than DecimalFormat. * - *

Example Usage + * **Example Usage** * * \code * // Normally we would have a GUI with a menu for this * int32_t locCount; * const Locale* locales = NumberFormat::getAvailableLocales(locCount); - * + * * double myNumber = -1234.56; * UErrorCode success = U_ZERO_ERROR; * NumberFormat* form; - * + * * // Print out a number with the localized number, currency and percent * // format for each locale. * UnicodeString countryName; @@ -91,12 +122,35 @@ class ChoiceFormat; * cout << locales[i].getDisplayName(displayName) << ": " << pattern; * cout << " -> " << form->format(myNumber,str) << endl; * form->parse(form->format(myNumber,str), fmtable, success); - * delete form; + * delete form; * } * } * } * \endcode * + * **Another example use createInstance(style)** + * + * \code + * // Print out a number using the localized number, currency, + * // percent, scientific, integer, iso currency, and plural currency + * // format for each locale + * Locale* locale = new Locale("en", "US"); + * double myNumber = 1234.56; + * UErrorCode success = U_ZERO_ERROR; + * UnicodeString str; + * Formattable fmtable; + * for (int j=NumberFormat::kNumberStyle; + * j<=NumberFormat::kPluralCurrencyStyle; + * ++j) { + * NumberFormat* form = NumberFormat::createInstance(locale, j, success); + * str.remove(); + * cout << "format result " << form->format(myNumber, str) << endl; + * format->parse(form->format(myNumber, str), fmtable, success); + * delete form; + * } + * \endcode + * + * *

Patterns * *

A DecimalFormat consists of a pattern and a set of @@ -106,7 +160,7 @@ class ChoiceFormat; * digits. The symbols are stored in a DecimalFormatSymbols * object. When using the NumberFormat factory methods, the * pattern and symbols are read from ICU's locale data. - * + * *

Special Pattern Characters * *

Many characters in a pattern are taken literally; they are matched during @@ -204,6 +258,8 @@ class ChoiceFormat; * No * Currency sign, replaced by currency symbol. If * doubled, replaced by international currency symbol. + * If tripled, replaced by currency plural names, for example, + * "US dollar" or "US dollars" for America. * If present in a pattern, the monetary decimal separator * is used instead of the decimal separator. * @@ -221,7 +277,7 @@ class ChoiceFormat; * Pad escape, precedes pad character * * - *

A DecimalFormat pattern contains a postive and negative + *

A DecimalFormat pattern contains a positive and negative * subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a * prefix, a numeric part, and a suffix. If there is no explicit negative * subpattern, the negative subpattern is the localized minus sign prefixed to the @@ -284,7 +340,7 @@ class ChoiceFormat; * * The first subpattern is for positive numbers. The second (optional) * subpattern is for negative numbers. - * + * *

Not indicated in the BNF syntax above: * *

@@ -538,7 +600,7 @@ class ChoiceFormat; * including prefix and suffix, determines the format width. For example, in * the pattern "* #0 o''clock", the format width is 10. * - *
  • The width is counted in 16-bit code units (UChars). + *
  • The width is counted in 16-bit code units (char16_ts). * *
  • Some parameters which usually do not matter have meaning when padding is * used, because the pattern width is significant with padding. In the pattern @@ -570,13 +632,17 @@ class ChoiceFormat; * increment in the pattern itself. "#,#50" specifies a rounding increment of * 50. "#,##0.05" specifies a rounding increment of 0.05. * + *

    In the absence of an explicit rounding increment numbers are + * rounded to their formatted width. + * *