1--- 2layout: default 3title: Legacy NumberFormat 4nav_order: 1 5grand_parent: Formatting 6parent: Formatting Numbers 7--- 8<!-- 9© 2020 and later: Unicode, Inc. and others. 10License & terms of use: http://www.unicode.org/copyright.html 11--> 12 13# Legacy `NumberFormat` 14{: .no_toc } 15 16## Contents 17{: .no_toc .text-delta } 18 191. TOC 20{:toc} 21 22--- 23 24## Note 25 26> :warning: Since ICU 60, the recommended way to format numbers is NumberFormatter; see [index.md](index.md). 27> 28> This page is here for reference for the older NumberFormat hierarchy in ICU4C and ICU4J. 29 30## `NumberFormat` 31 32[`NumberFormat`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classNumberFormat.html) is 33the abstract base class for all number formats. It provides an interface for 34formatting and parsing numbers. It also provides methods to determine which 35locales have number formats, and what their names are. `NumberFormat` helps format 36and parse numbers for any locale. Your program can be written to be completely 37independent of the locale conventions for decimal points or 38thousands-separators. It can also be written to be independent of the particular 39decimal digits used or whether the number format is a decimal. A normal decimal 40number can also be displayed as a currency or as a percentage. 41 42``` 431234.5 //Decimal number 44$1234.50 //U.S. currency 451.234,57€ //German currency 46123457% //Percent 47``` 48 49### Usage 50 51#### Formatting for a `Locale` 52 53To format a number for the current `Locale`, use one of the static factory methods 54to create a format, then call a format method to format it. To format a number 55for a different `Locale`, specify the `Locale` in the call to `createInstance()`. You 56can control the numbering system to be used for number formatting by creating a 57`Locale` that uses the `@numbers` keyword defined. For example, by default, the Thai 58locale "th" uses the western digits 0-9. To create a number format that uses the 59native Thai digits instead, first create a locale with `"@numbers=thai"` defined. 60See [the description on Locales](../../locale/index.md) for details. 61 62> :point_right: **Note**: If you are formatting multiple numbers, save processing time 63> by constructing the formatter once and then using it several times. 64 65#### Instantiating a `NumberFormat` 66 67The following methods are used for instantiating `NumberFormat` objects: 68 691. **`createInstance()`** 70 Returns the normal number format for the current locale or for a specified 71 locale. 72 732. **`createCurrencyInstance()`** 74 Returns the currency format for the current locale or for a specified 75 locale. 76 773. **`createPercentInstance()`** 78 Returns the percentage format for the current locale or for a specified 79 locale. 80 814. **`createScientificInstance()`** 82 Returns the scientific number format for the current locale or for a 83 specified locale. 84 85To create a format for spelled-out numbers, use a constructor on `RuleBasedNumberFormat`. 86 87#### Currency Formatting 88 89Currency formatting, i.e., the formatting of monetary values, combines a number 90with a suitable display symbol or name for a currency. By default, the currency 91is set from the locale data from when the currency format instance is created, 92based on the country code in the locale ID. However, for all but trivial uses, 93this is fragile because countries change currencies over time, and the locale 94data for a particular country may not be available. 95 96For proper currency formatting, both number and currency must be 97specified. Aside from achieving reliably correct results, this also allows to 98format monetary values in any currency with the format of any locale, like in 99exchange rate lists. If the locale data does not contain display symbols or 100names for a currency, then the 3-letter ISO code itself is displayed. 101 102The locale ID and the currency code are effectively independent: The locale ID 103defines the general format for the numbers, and whether the currency symbol or 104name is displayed before or after the number, while the currency code selects 105the actual currency with its symbol, name, number of digits, and [rounding 106mode](rounding-modes.md). 107 108In ICU and Java, the currency is specified in the form of a 3-letter ISO 4217 109code. For example, the code "USD" represents the US Dollar and "EUR" represents 110the Euro currency. 111 112In terms of APIs, the currency code is set as an attribute on a number format 113object (on a currency instance), while the number value is passed into each 114`format()` call or returned from `parse()` as usual. 115 1161. ICU4C (C++) `NumberFormat.setCurrency()` takes a Unicode string (`const UChar*`) with the 3-letter code. 117 1182. ICU4C (C API) allows to set the currency code via `unum_setTextAttribute()` 119 using the `UNUM_CURRENCY_CODE` selector. 120 1213. ICU4J `NumberFormat.setCurrency()` takes an ICU Currency object which 122 encapsulates the 3-letter code. 123 1244. The base JDK's `NumberFormat.setCurrency()` takes a JDK Currency object which 125 encapsulates the 3-letter code. 126 127The functionality of `Currency` and `setCurrency()` is more advanced in ICU than in 128the base JDK. When using ICU, setting the currency automatically adjusts the 129number format object appropriately, i.e., it sets not only the currency symbol 130and display name, but also the correct number of fraction digits and the correct 131[rounding mode](rounding-modes.md). This is not the case with the base JDK. See 132the API references for more details. 133 134There is ICU4C sample code at 135[icu4c/source/samples/numfmt/main.cpp](https://github.com/unicode-org/icu/blob/master/icu4c/source/samples/numfmt/main.cpp) 136which illustrates the use of `NumberFormat.setCurrency()`. 137 138#### Displaying Numbers 139 140You can also control the display of numbers with methods such as 141`getMinimumFractionDigits()`. If you want even more control over the format or 142parsing, or want to give your users more control, cast the `NumberFormat` returned 143from the factory methods to a `DecimalNumberFormat`. This works for the vast 144majority of countries. 145 146#### Working with Positions 147 148You can also use forms of the parse and format methods with `ParsePosition` and 149`UFieldPosition` to enable you to: 150 1511. progressively parse through pieces of a string. 152 1532. align the decimal point and other areas. 154 155For example, you can align numbers in two ways: 156 1571. If you are using a mono-spaced font with spacing for alignment, pass the 158 `FieldPosition` in your format call with `field = INTEGER_FIELD`. On output, 159 `getEndIndex` is set to the offset between the last character of the integer 160 and the decimal. Add `(desiredSpaceCount - getEndIndex)` spaces at the front 161 of the string. You can also use the space padding feature available in 162 `DecimalFormat`. 163 1642. If you are using proportional fonts, instead of padding with spaces, measure 165 the width of the string in pixels from the start to `getEndIndex`. Then move 166 the pen by `(desiredPixelWidth - widthToAlignmentPoint)` before drawing the 167 text. It also works where there is no decimal, but additional characters at 168 the end (that is, with parentheses in negative numbers: "(12)" for -12). 169 170#### Emulating `printf` 171 172`NumberFormat` can produce many of the same formats as printf. 173 174| printf | ICU | 175|--------|-----| 176| Width specifier, e.g., `"%5d"` has a width of 5. | Use `DecimalFormat`. Either specify the padding, with can pad with any character, or specify a minimum integer count and a minimum fraction count, which will emit a specific number of digits, with zero padded to the left and right. | 177| Precision specifier for `%f` and `%e`, e.g. `"%.6f"` or `"%.6e"`. This defines the number of digits to the right of the decimal point. | Use `DecimalFormat`. Specify the maximum fraction digits. | 178| General scientific notation, `%g`. This format uses either `%f` or `%e`, depending on the magnitude of the number being displayed. | Use `ChoiceFormat` with `DecimalFormat`. For example, for a typical `%g`, which has 6 significant digits, use a `ChoiceFormat` with thresholds of 1e-4 and 1e6. For values between the two thresholds, use a fixed `DecimalFormat` with the pattern `"@#####"`. For values outside the thresholds, use a `DecimalFormat` with the pattern `"@#####E0"`. | 179 180## `DecimalFormat` 181 182`DecimalFormat` is a `NumberFormat` that converts numbers into strings using the 183decimal numbering system. This is the formatter that provides standard number 184formatting and parsing services for most usage scenarios in most locales. In 185order to access features of `DecimalFormat` not exposed in the `NumberFormat` API, 186you may need to cast your `NumberFormat` object to a `DecimalFormat`. You may also 187construct a `DecimalFormat` directly, but this is not recommended because it can 188hinder proper localization. 189 190For a complete description of `DecimalFormat`, including the pattern syntax, 191formatting and parsing behavior, and available API, see the [ICU4J `DecimalFormat` 192API](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/text/DecimalFormat.html) or 193[ICU4C `DecimalFormat` 194API](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classDecimalFormat.html) documentation. 195 196## `DecimalFormatSymbols` 197 198[`DecimalFormatSymbols`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classDecimalFormatSymbols.html) 199specifies the exact characters a `DecimalFormat` uses for various parts of a 200number (such as the characters to use for the digits, the character to use as 201the decimal point, or the character to use as the minus sign). 202 203This class represents the set of symbols needed by `DecimalFormat` to format 204numbers. `DecimalFormat` creates its own instance of `DecimalFormatSymbols` from its 205locale data. The `DecimalFormatSymbols` can be adopted by a `DecimalFormat` 206instance, or it can be specified when a `DecimalFormat` is created. If you need to 207change any of these symbols, can get the `DecimalFormatSymbols` object from your 208`DecimalFormat` and then modify it. 209 210## Additional Sample Code 211 212C/C++: See 213[icu4c/source/samples/numfmt/](https://github.com/unicode-org/icu/blob/master/icu4c/source/samples/numfmt/) 214in the ICU source distribution for code samples showing the use of ICU number 215formatting. 216