All-in-one formatter for localized numbers, currencies, and units. For a full list of options, see NumberFormatterSettings.

// Most basic usage:
NumberFormatter.withLocale(...).format(123).toString();  // 1,234 in en-US

// Custom notation, unit, and rounding strategy:
NumberFormatter.with()
    .notation(Notation.compactShort())
    .unit(Currency.getInstance("EUR"))
    .precision(Precision.maxDigits(2))
    .locale(...)
    .format(1234)
    .toString();  // €1.2K in en-US

// Create a formatter in a private static final field:
private static final LocalizedNumberFormatter formatter = NumberFormatter.withLocale(...)
    .unit(NoUnit.PERCENT)
    .precision(Precision.fixedFraction(3));
formatter.format(5.9831).toString();  // 5.983% in en-US

// Create a "template" in a private static final field but without setting a locale until the call site:
private static final UnlocalizedNumberFormatter template = NumberFormatter.with()
    .sign(SignDisplay.ALWAYS)
    .unitWidth(UnitWidth.FULL_NAME);
template.locale(...).format(new Measure(1234, MeasureUnit.METER)).toString();  // +1,234 meters in en-US

This API offers more features than com.ibm.icu.text.DecimalFormat and is geared toward new users of ICU.

NumberFormatter instances (i.e., LocalizedNumberFormatter and UnlocalizedNumberFormatter) are immutable and thread safe. This means that invoking a configuration method has no effect on the receiving instance; you must store and use the new number formatter instance it returns instead.

UnlocalizedNumberFormatter formatter = UnlocalizedNumberFormatter.with()
        .notation(Notation.scientific());
formatter.precision(Precision.maxFraction(2)); // does nothing!
formatter.locale(ULocale.ENGLISH).format(9.8765).toString(); // prints "9.8765E0", not "9.88E0"

This API is based on the fluent design pattern popularized by libraries such as Google's Guava. For extensive details on the design of this API, read the design doc.

Note

To format monetary/currency values, specify the currency in the `.unit()` function.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	NumberFormatter.DecimalSeparatorDisplay An enum declaring how to render the decimal separator.
public static enum	NumberFormatter.GroupingStrategy An enum declaring the strategy for when and how to display grouping separators (i.e., the separator, often a comma or period, after every 2-3 powers of ten).
public static enum	NumberFormatter.RoundingPriority An enum declaring how to resolve conflicts between maximum fraction digits and maximum significant digits.
public static enum	NumberFormatter.SignDisplay An enum declaring how to denote positive and negative numbers.
public static enum	NumberFormatter.TrailingZeroDisplay An enum declaring how to render trailing zeros.
public static enum	NumberFormatter.UnitWidth An enum declaring how to render units, including currencies.

Modifier and Type	Field and Description
private static final UnlocalizedNumberFormatter	BASE
pack-priv static final long	DEFAULT_THRESHOLD Use a default threshold of 3.

Access	Constructor and Description
private	NumberFormatter() Private constructor, not designed for instantiation.

Method Summary

Modifier and Type	Method and Description
public static UnlocalizedNumberFormatter	Returns: An `UnlocalizedNumberFormatter`, to be used for chaining. forSkeleton(String The skeleton string off of which to base this NumberFormatter. skeleton) Call this method at the beginning of a NumberFormatter fluent chain to create an instance based on a given number skeleton string.
public static UnlocalizedNumberFormatter	fromDecimalFormat(DecimalFormatProperties properties, DecimalFormatSymbols symbols, DecimalFormatProperties exportedProperties) Deprecated ICU 60 This API is ICU internal only. Note In Java, since NumberPropertyMapper is package-private, this method is here so that it is accessible to tests.
public static UnlocalizedNumberFormatter	Returns: An `UnlocalizedNumberFormatter`, to be used for chaining. with() Call this method at the beginning of a NumberFormatter fluent chain in which the locale is not currently known at the call site.
public static LocalizedNumberFormatter	Returns: A `LocalizedNumberFormatter`, to be used for chaining. withLocale(Locale The locale from which to load formats and symbols for number formatting. locale) Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known at the call site.
public static LocalizedNumberFormatter	Returns: A `LocalizedNumberFormatter`, to be used for chaining. withLocale(ULocale The locale from which to load formats and symbols for number formatting. locale) Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known at the call site.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

BASE	back to summary
private static final UnlocalizedNumberFormatter BASE

DEFAULT_THRESHOLD	back to summary
pack-priv static final long DEFAULT_THRESHOLD Use a default threshold of 3. This means that the third time .format() is called, the data structures get built using the "safe" code path. The first two calls to .format() will trigger the unsafe code path.

NumberFormatter	back to summary
private NumberFormatter() Private constructor, not designed for instantiation.

Method Detail

forSkeleton back to summary

forSkeleton	back to summary
public static UnlocalizedNumberFormatter forSkeleton(String skeleton) Call this method at the beginning of a NumberFormatter fluent chain to create an instance based on a given number skeleton string. For more information on number skeleton strings, see: https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html Parameters skeleton:String The skeleton string off of which to base this NumberFormatter. Returns:UnlocalizedNumberFormatter An `UnlocalizedNumberFormatter`, to be used for chaining. Exceptions SkeletonSyntaxException: If the given string is not a valid number formatting skeleton. ICU Status Stable since ICU 62.

public static UnlocalizedNumberFormatter forSkeleton(String skeleton)

Call this method at the beginning of a NumberFormatter fluent chain to create an instance based on a given number skeleton string. For more information on number skeleton strings, see: https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html

Parameters

skeleton:String: The skeleton string off of which to base this NumberFormatter.

Returns:UnlocalizedNumberFormatter

An UnlocalizedNumberFormatter, to be used for chaining.

Exceptions

SkeletonSyntaxException:: If the given string is not a valid number formatting skeleton.

ICU Status

Stable since ICU 62.

fromDecimalFormat	back to summary
public static UnlocalizedNumberFormatter fromDecimalFormat(DecimalFormatProperties properties, DecimalFormatSymbols symbols, DecimalFormatProperties exportedProperties) Deprecated ICU 60 This API is ICU internal only. Note In Java, since NumberPropertyMapper is package-private, this method is here so that it is accessible to tests. Annotations @Deprecated ICU Status Internal ICU component.

fromDecimalFormat

back to summary

public static UnlocalizedNumberFormatter fromDecimalFormat(DecimalFormatProperties properties, DecimalFormatSymbols symbols, DecimalFormatProperties exportedProperties)

Deprecated

ICU 60 This API is ICU internal only.

Note

In Java, since NumberPropertyMapper is package-private, this method is here so that it is accessible to tests.

Annotations

@Deprecated

ICU Status

Internal ICU component.

with back to summary

with	back to summary
public static UnlocalizedNumberFormatter with() Call this method at the beginning of a NumberFormatter fluent chain in which the locale is not currently known at the call site. Returns:UnlocalizedNumberFormatter An `UnlocalizedNumberFormatter`, to be used for chaining. ICU Status Stable since ICU 60.

public static UnlocalizedNumberFormatter with()

Call this method at the beginning of a NumberFormatter fluent chain in which the locale is not currently known at the call site.

Returns:UnlocalizedNumberFormatter: An UnlocalizedNumberFormatter, to be used for chaining.
ICU Status: Stable since ICU 60.

withLocale back to summary

withLocale	back to summary
public static LocalizedNumberFormatter withLocale(Locale locale) Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known at the call site. Parameters locale:Locale The locale from which to load formats and symbols for number formatting. Returns:LocalizedNumberFormatter A `LocalizedNumberFormatter`, to be used for chaining. ICU Status Stable since ICU 60.

public static LocalizedNumberFormatter withLocale(Locale locale)

Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known at the call site.

Parameters

locale:Locale: The locale from which to load formats and symbols for number formatting.

Returns:LocalizedNumberFormatter

A LocalizedNumberFormatter, to be used for chaining.

ICU Status

Stable since ICU 60.

withLocale back to summary

withLocale	back to summary
public static LocalizedNumberFormatter withLocale(ULocale locale) Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known at the call site. Parameters locale:ULocale The locale from which to load formats and symbols for number formatting. Returns:LocalizedNumberFormatter A `LocalizedNumberFormatter`, to be used for chaining. ICU Status Stable since ICU 60.

public static LocalizedNumberFormatter withLocale(ULocale locale)

Call this method at the beginning of a NumberFormatter fluent chain in which the locale is known at the call site.

Parameters

locale:ULocale: The locale from which to load formats and symbols for number formatting.

Returns:LocalizedNumberFormatter

A LocalizedNumberFormatter, to be used for chaining.

ICU Status

Stable since ICU 60.

com.ibm.icu.number back to summary

public final Enum NumberFormatter.DecimalSeparatorDisplay

Class Inheritance

extends Enum<NumberFormatter.DecimalSeparatorDisplay>

java.lang.Object
java.lang.Enum
com.ibm.icu.number.NumberFormatter.DecimalSeparatorDisplay

An enum declaring how to render the decimal separator. Example outputs when formatting 1 and 1.1 in en-US:

AUTO: "1" and "1.1"
ALWAYS: "1." and "1.1"

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

Field Summary

Modifier and Type	Field and Description
public static final NumberFormatter.DecimalSeparatorDisplay	ALWAYS Always show the decimal separator, even if there are no digits to display after the separator.
public static final NumberFormatter.DecimalSeparatorDisplay	AUTO Show the decimal separator when there are one or more digits to display after the separator, and do not show it otherwise.

Constructor Summary

Access	Constructor and Description
private	DecimalSeparatorDisplay()

Method Summary

Modifier and Type	Method and Description
public static NumberFormatter.DecimalSeparatorDisplay	valueOf(String name)
public static NumberFormatter.DecimalSeparatorDisplay[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

ALWAYS back to summary

ALWAYS	back to summary
public static final NumberFormatter.DecimalSeparatorDisplay ALWAYS Always show the decimal separator, even if there are no digits to display after the separator. ICU Status Stable since ICU 60. See Also `NumberFormatter`

public static final NumberFormatter.DecimalSeparatorDisplay ALWAYS

Always show the decimal separator, even if there are no digits to display after the separator.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

AUTO back to summary

AUTO	back to summary
public static final NumberFormatter.DecimalSeparatorDisplay AUTO Show the decimal separator when there are one or more digits to display after the separator, and do not show it otherwise. This is the default behavior. ICU Status Stable since ICU 60. See Also `NumberFormatter`

public static final NumberFormatter.DecimalSeparatorDisplay AUTO

Show the decimal separator when there are one or more digits to display after the separator, and do not show it otherwise. This is the default behavior.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

Constructor Detail

DecimalSeparatorDisplay	back to summary
private DecimalSeparatorDisplay()

Method Detail

valueOf	back to summary
public static NumberFormatter.DecimalSeparatorDisplay valueOf(String name)

values	back to summary
public static NumberFormatter.DecimalSeparatorDisplay[] values()

com.ibm.icu.number back to summary

public final Enum NumberFormatter.GroupingStrategy

Class Inheritance

extends Enum<NumberFormatter.GroupingStrategy>

java.lang.Object
java.lang.Enum
com.ibm.icu.number.NumberFormatter.GroupingStrategy

An enum declaring the strategy for when and how to display grouping separators (i.e., the separator, often a comma or period, after every 2-3 powers of ten). The choices are several pre-built strategies for different use cases that employ locale data whenever possible. Example outputs for 1234 and 1234567 in en-IN:

OFF: 1234 and 12345
MIN2: 1234 and 12,34,567
AUTO: 1,234 and 12,34,567
ON_ALIGNED: 1,234 and 12,34,567
THOUSANDS: 1,234 and 1,234,567

The default is AUTO, which displays grouping separators unless the locale data says that grouping is not customary. To force grouping for all numbers greater than 1000 consistently across locales, use ON_ALIGNED. On the other hand, to display grouping less frequently than the default, use MIN2 or OFF. See the docs of each option for details.

Note

This enum specifies the strategy for grouping sizes. To set which character to use as the grouping separator, use the "symbols" setter.

ICU Status: Stable since ICU 61.
See Also: NumberFormatter

Field Summary

Modifier and Type	Field and Description
public static final NumberFormatter.GroupingStrategy	AUTO Display grouping using the default strategy for all locales.
public static final NumberFormatter.GroupingStrategy	MIN2 Display grouping using locale defaults, except do not show grouping on values smaller than 10000 (such that there is a minimum of two digits before the first separator).
public static final NumberFormatter.GroupingStrategy	OFF Do not display grouping separators in any locale.
public static final NumberFormatter.GroupingStrategy	ON_ALIGNED Always display the grouping separator on values of at least 1000.
public static final NumberFormatter.GroupingStrategy	THOUSANDS Use the Western defaults: groups of 3 and enabled for all numbers 1000 or greater.

Constructor Summary

Access	Constructor and Description
private	GroupingStrategy()

Method Summary

Modifier and Type	Method and Description
public static NumberFormatter.GroupingStrategy	valueOf(String name)
public static NumberFormatter.GroupingStrategy[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

AUTO back to summary

AUTO	back to summary
public static final NumberFormatter.GroupingStrategy AUTO Display grouping using the default strategy for all locales. This is the default behavior. Note that locales may restrict grouping separators to be displayed only on 1 million or greater (for example, ee and hu) or disable grouping altogether (for example, bg currency). Locale data is used to determine whether to separate larger numbers into groups of 2 (customary in South Asia) or groups of 3 (customary in Europe and the Americas). ICU Status Stable since ICU 61. See Also `NumberFormatter`

public static final NumberFormatter.GroupingStrategy AUTO

Display grouping using the default strategy for all locales. This is the default behavior.

Note that locales may restrict grouping separators to be displayed only on 1 million or greater (for example, ee and hu) or disable grouping altogether (for example, bg currency).

Locale data is used to determine whether to separate larger numbers into groups of 2 (customary in South Asia) or groups of 3 (customary in Europe and the Americas).

ICU Status: Stable since ICU 61.
See Also: NumberFormatter

MIN2 back to summary

MIN2	back to summary
public static final NumberFormatter.GroupingStrategy MIN2 Display grouping using locale defaults, except do not show grouping on values smaller than 10000 (such that there is a minimum of two digits before the first separator). Note that locales may restrict grouping separators to be displayed only on 1 million or greater (for example, ee and hu) or disable grouping altogether (for example, bg currency). Locale data is used to determine whether to separate larger numbers into groups of 2 (customary in South Asia) or groups of 3 (customary in Europe and the Americas). ICU Status Stable since ICU 61. See Also `NumberFormatter`

public static final NumberFormatter.GroupingStrategy MIN2

Display grouping using locale defaults, except do not show grouping on values smaller than 10000 (such that there is a minimum of two digits before the first separator).

Note that locales may restrict grouping separators to be displayed only on 1 million or greater (for example, ee and hu) or disable grouping altogether (for example, bg currency).

Locale data is used to determine whether to separate larger numbers into groups of 2 (customary in South Asia) or groups of 3 (customary in Europe and the Americas).

ICU Status: Stable since ICU 61.
See Also: NumberFormatter

OFF back to summary

OFF	back to summary
public static final NumberFormatter.GroupingStrategy OFF Do not display grouping separators in any locale. ICU Status Stable since ICU 61. See Also `NumberFormatter`

public static final NumberFormatter.GroupingStrategy OFF

Do not display grouping separators in any locale.

ICU Status: Stable since ICU 61.
See Also: NumberFormatter

ON_ALIGNED back to summary

ON_ALIGNED	back to summary
public static final NumberFormatter.GroupingStrategy ON_ALIGNED Always display the grouping separator on values of at least 1000. This option ignores the locale data that restricts or disables grouping, described in MIN2 and AUTO. This option may be useful to normalize the alignment of numbers, such as in a spreadsheet. Locale data is used to determine whether to separate larger numbers into groups of 2 (customary in South Asia) or groups of 3 (customary in Europe and the Americas). ICU Status Stable since ICU 61. See Also `NumberFormatter`

public static final NumberFormatter.GroupingStrategy ON_ALIGNED

Always display the grouping separator on values of at least 1000.

This option ignores the locale data that restricts or disables grouping, described in MIN2 and AUTO. This option may be useful to normalize the alignment of numbers, such as in a spreadsheet.

Locale data is used to determine whether to separate larger numbers into groups of 2 (customary in South Asia) or groups of 3 (customary in Europe and the Americas).

ICU Status: Stable since ICU 61.
See Also: NumberFormatter

THOUSANDS back to summary

THOUSANDS	back to summary
public static final NumberFormatter.GroupingStrategy THOUSANDS Use the Western defaults: groups of 3 and enabled for all numbers 1000 or greater. Do not use locale data for determining the grouping strategy. ICU Status Stable since ICU 61. See Also `NumberFormatter`

public static final NumberFormatter.GroupingStrategy THOUSANDS

Use the Western defaults: groups of 3 and enabled for all numbers 1000 or greater. Do not use locale data for determining the grouping strategy.

ICU Status: Stable since ICU 61.
See Also: NumberFormatter

Constructor Detail

GroupingStrategy	back to summary
private GroupingStrategy()

Method Detail

valueOf	back to summary
public static NumberFormatter.GroupingStrategy valueOf(String name)

values	back to summary
public static NumberFormatter.GroupingStrategy[] values()

com.ibm.icu.number back to summary

public final Enum NumberFormatter.RoundingPriority

Class Inheritance

extends Enum<NumberFormatter.RoundingPriority>

java.lang.Object
java.lang.Enum
com.ibm.icu.number.NumberFormatter.RoundingPriority

An enum declaring how to resolve conflicts between maximum fraction digits and maximum significant digits.

There are two modes, RELAXED and STRICT:

RELAXED: Relax one of the two constraints (fraction digits or significant digits) in order to round the number to a higher level of precision.
STRICT: Enforce both constraints, resulting in the number being rounded to a lower level of precision.

The default settings for compact notation rounding are Max-Fraction = 0 (round to the nearest integer), Max-Significant = 2 (round to 2 significant digits), and priority RELAXED (choose the constraint that results in more digits being displayed).

Conflicting minimum fraction and significant digits are always resolved in the direction that results in more trailing zeros.

Example 1: Consider the number 3.141, with various different settings:

Max-Fraction = 1: "3.1"
Max-Significant = 3: "3.14"

The rounding priority determines how to resolve the conflict when both Max-Fraction and Max-Significant are set. With RELAXED, the less-strict setting (the one that causes more digits to be displayed) will be used; Max-Significant wins. With STRICT, the more-strict setting (the one that causes fewer digits to be displayed) will be used; Max-Fraction wins.

Example 2: Consider the number 8317, with various different settings:

Max-Fraction = 1: "8317"
Max-Significant = 3: "8320"

Here, RELAXED favors Max-Fraction and STRICT favors Max-Significant. Note that this larger number caused the two modes to favor the opposite result.

ICU Status: Stable since ICU 69.

Field Summary

Modifier and Type	Field and Description
public static final NumberFormatter.RoundingPriority	RELAXED Favor greater precision by relaxing one of the rounding constraints.
public static final NumberFormatter.RoundingPriority	STRICT Favor adherence to all rounding constraints by producing lower precision.

Constructor Summary

Access	Constructor and Description
private	RoundingPriority()

Method Summary

Modifier and Type	Method and Description
public static NumberFormatter.RoundingPriority	valueOf(String name)
public static NumberFormatter.RoundingPriority[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

RELAXED	back to summary
public static final NumberFormatter.RoundingPriority RELAXED Favor greater precision by relaxing one of the rounding constraints. ICU Status Stable since ICU 69.

RELAXED

back to summary

public static final NumberFormatter.RoundingPriority RELAXED

Favor greater precision by relaxing one of the rounding constraints.

ICU Status: Stable since ICU 69.

STRICT	back to summary
public static final NumberFormatter.RoundingPriority STRICT Favor adherence to all rounding constraints by producing lower precision. ICU Status Stable since ICU 69.

STRICT

back to summary

public static final NumberFormatter.RoundingPriority STRICT

Favor adherence to all rounding constraints by producing lower precision.

ICU Status: Stable since ICU 69.

Constructor Detail

RoundingPriority	back to summary
private RoundingPriority()

Method Detail

valueOf	back to summary
public static NumberFormatter.RoundingPriority valueOf(String name)

values	back to summary
public static NumberFormatter.RoundingPriority[] values()

com.ibm.icu.number back to summary

public final Enum NumberFormatter.SignDisplay

Class Inheritance

extends Enum<NumberFormatter.SignDisplay>

java.lang.Object
java.lang.Enum
com.ibm.icu.number.NumberFormatter.SignDisplay

An enum declaring how to denote positive and negative numbers. Example outputs when formatting 123, 0, and -123 in en-US:

AUTO: "123", "0", and "-123"
ALWAYS: "+123", "+0", and "-123"
NEVER: "123", "0", and "123"
ACCOUNTING: "$123", "$0", and "($123)"
ACCOUNTING_ALWAYS: "+$123", "+$0", and "($123)"
EXCEPT_ZERO: "+123", "0", and "-123"
ACCOUNTING_EXCEPT_ZERO: "+$123", "$0", and "($123)"

The exact format, including the position and the code point of the sign, differ by locale.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

Field Summary

Modifier and Type	Field and Description
public static final NumberFormatter.SignDisplay	ACCOUNTING Use the locale-dependent accounting format on negative numbers, and do not show the sign on positive numbers.
public static final NumberFormatter.SignDisplay	ACCOUNTING_ALWAYS Use the locale-dependent accounting format on negative numbers, and show the plus sign on positive numbers, including zero.
public static final NumberFormatter.SignDisplay	ACCOUNTING_EXCEPT_ZERO Use the locale-dependent accounting format on negative numbers, and show the plus sign on positive numbers.
public static final NumberFormatter.SignDisplay	ACCOUNTING_NEGATIVE Same as ACCOUNTING, but do not show the sign on negative zero.
public static final NumberFormatter.SignDisplay	ALWAYS Show the minus sign on negative numbers and the plus sign on positive numbers, including zero.
public static final NumberFormatter.SignDisplay	AUTO Show the minus sign on negative numbers, and do not show the sign on positive numbers.
public static final NumberFormatter.SignDisplay	EXCEPT_ZERO Show the minus sign on negative numbers and the plus sign on positive numbers.
public static final NumberFormatter.SignDisplay	NEGATIVE Same as AUTO, but do not show the sign on negative zero.
public static final NumberFormatter.SignDisplay	NEVER Do not show the sign on positive or negative numbers.

Constructor Summary

Access	Constructor and Description
private	SignDisplay()

Method Summary

Modifier and Type	Method and Description
public static NumberFormatter.SignDisplay	valueOf(String name)
public static NumberFormatter.SignDisplay[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

ACCOUNTING back to summary

ACCOUNTING	back to summary
public static final NumberFormatter.SignDisplay ACCOUNTING Use the locale-dependent accounting format on negative numbers, and do not show the sign on positive numbers. The accounting format is defined in CLDR and varies by locale; in many Western locales, the format is a pair of parentheses around the number. Note Since CLDR defines the accounting format in the monetary context only, this option falls back to the AUTO sign display strategy when formatting without a currency unit. This limitation may be lifted in the future. ICU Status Stable since ICU 60. See Also `NumberFormatter`

public static final NumberFormatter.SignDisplay ACCOUNTING

Use the locale-dependent accounting format on negative numbers, and do not show the sign on positive numbers.

The accounting format is defined in CLDR and varies by locale; in many Western locales, the format is a pair of parentheses around the number.

Note

Since CLDR defines the accounting format in the monetary context only, this option falls back to the AUTO sign display strategy when formatting without a currency unit. This limitation may be lifted in the future.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

ACCOUNTING_ALWAYS back to summary

ACCOUNTING_ALWAYS	back to summary
public static final NumberFormatter.SignDisplay ACCOUNTING_ALWAYS Use the locale-dependent accounting format on negative numbers, and show the plus sign on positive numbers, including zero. For more information on the accounting format, see the ACCOUNTING sign display strategy. To hide the sign on zero, see `ACCOUNTING_EXCEPT_ZERO`. ICU Status Stable since ICU 60. See Also `NumberFormatter`

public static final NumberFormatter.SignDisplay ACCOUNTING_ALWAYS

Use the locale-dependent accounting format on negative numbers, and show the plus sign on positive numbers, including zero. For more information on the accounting format, see the ACCOUNTING sign display strategy. To hide the sign on zero, see ACCOUNTING_EXCEPT_ZERO.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

ACCOUNTING_EXCEPT_ZERO back to summary

ACCOUNTING_EXCEPT_ZERO	back to summary
public static final NumberFormatter.SignDisplay ACCOUNTING_EXCEPT_ZERO Use the locale-dependent accounting format on negative numbers, and show the plus sign on positive numbers. Do not show a sign on zero, numbers that round to zero, or NaN. For more information on the accounting format, see the ACCOUNTING sign display strategy. ICU Status Stable since ICU 61. See Also `NumberFormatter`

public static final NumberFormatter.SignDisplay ACCOUNTING_EXCEPT_ZERO

Use the locale-dependent accounting format on negative numbers, and show the plus sign on positive numbers. Do not show a sign on zero, numbers that round to zero, or NaN. For more information on the accounting format, see the ACCOUNTING sign display strategy.

ICU Status: Stable since ICU 61.
See Also: NumberFormatter

ACCOUNTING_NEGATIVE	back to summary
public static final NumberFormatter.SignDisplay ACCOUNTING_NEGATIVE Same as ACCOUNTING, but do not show the sign on negative zero. ICU Status Stable since ICU 69.

ACCOUNTING_NEGATIVE

back to summary

public static final NumberFormatter.SignDisplay ACCOUNTING_NEGATIVE

Same as ACCOUNTING, but do not show the sign on negative zero.

ICU Status: Stable since ICU 69.

ALWAYS back to summary

ALWAYS	back to summary
public static final NumberFormatter.SignDisplay ALWAYS Show the minus sign on negative numbers and the plus sign on positive numbers, including zero. To hide the sign on zero, see `EXCEPT_ZERO`. ICU Status Stable since ICU 60. See Also `NumberFormatter`

public static final NumberFormatter.SignDisplay ALWAYS

Show the minus sign on negative numbers and the plus sign on positive numbers, including zero. To hide the sign on zero, see EXCEPT_ZERO.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

AUTO back to summary

AUTO	back to summary
public static final NumberFormatter.SignDisplay AUTO Show the minus sign on negative numbers, and do not show the sign on positive numbers. This is the default behavior. If using this option, a sign will be displayed on negative zero, including negative numbers that round to zero. To hide the sign on negative zero, use the NEGATIVE option. ICU Status Stable since ICU 60. See Also `NumberFormatter`

public static final NumberFormatter.SignDisplay AUTO

Show the minus sign on negative numbers, and do not show the sign on positive numbers. This is the default behavior. If using this option, a sign will be displayed on negative zero, including negative numbers that round to zero. To hide the sign on negative zero, use the NEGATIVE option.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

EXCEPT_ZERO back to summary

EXCEPT_ZERO	back to summary
public static final NumberFormatter.SignDisplay EXCEPT_ZERO Show the minus sign on negative numbers and the plus sign on positive numbers. Do not show a sign on zero, numbers that round to zero, or NaN. ICU Status Stable since ICU 61. See Also `NumberFormatter`

public static final NumberFormatter.SignDisplay EXCEPT_ZERO

Show the minus sign on negative numbers and the plus sign on positive numbers. Do not show a sign on zero, numbers that round to zero, or NaN.

ICU Status: Stable since ICU 61.
See Also: NumberFormatter

NEGATIVE	back to summary
public static final NumberFormatter.SignDisplay NEGATIVE Same as AUTO, but do not show the sign on negative zero. ICU Status Stable since ICU 69.

NEGATIVE

back to summary

public static final NumberFormatter.SignDisplay NEGATIVE

Same as AUTO, but do not show the sign on negative zero.

ICU Status: Stable since ICU 69.

NEVER back to summary

public static final NumberFormatter.SignDisplay NEVER

Do not show the sign on positive or negative numbers.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

Constructor Detail

SignDisplay	back to summary
private SignDisplay()

Method Detail

valueOf	back to summary
public static NumberFormatter.SignDisplay valueOf(String name)

values	back to summary
public static NumberFormatter.SignDisplay[] values()

com.ibm.icu.number back to summary

public final Enum NumberFormatter.TrailingZeroDisplay

Class Inheritance

extends Enum<NumberFormatter.TrailingZeroDisplay>

java.lang.Object
java.lang.Enum
com.ibm.icu.number.NumberFormatter.TrailingZeroDisplay

An enum declaring how to render trailing zeros.

AUTO: 0.90, 1.00, 1.10
HIDE_IF_WHOLE: 0.90, 1, 1.10

ICU Status: Stable since ICU 69.

Field Summary

Modifier and Type	Field and Description
public static final NumberFormatter.TrailingZeroDisplay	AUTO Display trailing zeros according to the settings for minimum fraction and significant digits.
public static final NumberFormatter.TrailingZeroDisplay	HIDE_IF_WHOLE Same as AUTO, but hide trailing zeros after the decimal separator if they are all zero.

Constructor Summary

Access	Constructor and Description
private	TrailingZeroDisplay()

Method Summary

Modifier and Type	Method and Description
public static NumberFormatter.TrailingZeroDisplay	valueOf(String name)
public static NumberFormatter.TrailingZeroDisplay[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

AUTO

back to summary

public static final NumberFormatter.TrailingZeroDisplay AUTO

Display trailing zeros according to the settings for minimum fraction and significant digits.

ICU Status: Stable since ICU 69.

HIDE_IF_WHOLE

back to summary

public static final NumberFormatter.TrailingZeroDisplay HIDE_IF_WHOLE

Same as AUTO, but hide trailing zeros after the decimal separator if they are all zero.

ICU Status: Stable since ICU 69.

Constructor Detail

TrailingZeroDisplay	back to summary
private TrailingZeroDisplay()

Method Detail

valueOf	back to summary
public static NumberFormatter.TrailingZeroDisplay valueOf(String name)

values	back to summary
public static NumberFormatter.TrailingZeroDisplay[] values()

com.ibm.icu.number back to summary

public final Enum NumberFormatter.UnitWidth

Class Inheritance

extends Enum<NumberFormatter.UnitWidth>

java.lang.Object
java.lang.Enum
com.ibm.icu.number.NumberFormatter.UnitWidth

An enum declaring how to render units, including currencies. Example outputs when formatting 123 USD and 123 meters in en-CA:

NARROW: "$123.00" and "123 m"
SHORT: "US$ 123.00" and "123 m"
FULL_NAME: "123.00 US dollars" and "123 meters"
ISO_CODE: "USD 123.00" and undefined behavior
HIDDEN: "123.00" and "123"

This enum is similar to com.ibm.icu.text.MeasureFormat.FormatWidth.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

Field Summary

Modifier and Type	Field and Description
public static final NumberFormatter.UnitWidth	FORMAL Use the formal variant of the currency symbol; for example, "NT$" for the New Taiwan dollar in zh-TW.
public static final NumberFormatter.UnitWidth	FULL_NAME Print the full name of the unit, without any abbreviations.
public static final NumberFormatter.UnitWidth	HIDDEN Format the number according to the specified unit, but do not display the unit.
public static final NumberFormatter.UnitWidth	ISO_CODE Use the three-digit ISO XXX code in place of the symbol for displaying currencies.
public static final NumberFormatter.UnitWidth	NARROW Print an abbreviated version of the unit name.
public static final NumberFormatter.UnitWidth	SHORT Print an abbreviated version of the unit name.
public static final NumberFormatter.UnitWidth	VARIANT Use the alternate variant of the currency symbol; for example, "TL" for the Turkish lira (TRY).

Constructor Summary

Access	Constructor and Description
private	UnitWidth()

Method Summary

Modifier and Type	Method and Description
public static NumberFormatter.UnitWidth	valueOf(String name)
public static NumberFormatter.UnitWidth[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

FORMAL back to summary

public static final NumberFormatter.UnitWidth FORMAL

Use the formal variant of the currency symbol; for example, "NT$" for the New Taiwan dollar in zh-TW.

Behavior of this option with non-currency units is not defined at this time.

ICU Status: Stable since ICU 67.
See Also: NumberFormatter

FULL_NAME back to summary

public static final NumberFormatter.UnitWidth FULL_NAME

Print the full name of the unit, without any abbreviations.

In CLDR, this option corresponds to the default format for measure units and the "¤¤¤" placeholder for currencies.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

HIDDEN back to summary

public static final NumberFormatter.UnitWidth HIDDEN

Format the number according to the specified unit, but do not display the unit. For currencies, apply monetary symbols and formats as with SHORT, but omit the currency symbol. For measure units, the behavior is equivalent to not specifying the unit at all.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

ISO_CODE back to summary

public static final NumberFormatter.UnitWidth ISO_CODE

Use the three-digit ISO XXX code in place of the symbol for displaying currencies.

Behavior of this option with non-currency units is not defined at this time.

In CLDR, this option corresponds to the "¤¤" placeholder for currencies.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

NARROW back to summary

public static final NumberFormatter.UnitWidth NARROW

Print an abbreviated version of the unit name. Similar to SHORT, but always use the shortest available abbreviation or symbol. This option can be used when the context hints at the identity of the unit. For more information on the difference between NARROW and SHORT, see SHORT.

In CLDR, this option corresponds to the "Narrow" format for measure units and the "¤¤¤¤¤" placeholder for currencies.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

SHORT back to summary

public static final NumberFormatter.UnitWidth SHORT

Print an abbreviated version of the unit name. Similar to NARROW, but use a slightly wider abbreviation or symbol when there may be ambiguity. This is the default behavior.

For example, in es-US, the SHORT form for Fahrenheit is "{0} °F", but the NARROW form is "{0}°", since Fahrenheit is the customary unit for temperature in that locale.

In CLDR, this option corresponds to the "Short" format for measure units and the "¤" placeholder for currencies.

ICU Status: Stable since ICU 60.
See Also: NumberFormatter

VARIANT back to summary

public static final NumberFormatter.UnitWidth VARIANT

Use the alternate variant of the currency symbol; for example, "TL" for the Turkish lira (TRY).

Behavior of this option with non-currency units is not defined at this time.

ICU Status: Stable since ICU 67.
See Also: NumberFormatter

Constructor Detail

UnitWidth	back to summary
private UnitWidth()

Method Detail

valueOf	back to summary
public static NumberFormatter.UnitWidth valueOf(String name)

values	back to summary
public static NumberFormatter.UnitWidth[] values()

public final Class NumberFormatter

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Enum NumberFormatter.DecimalSeparatorDisplay

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Enum NumberFormatter.GroupingStrategy

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Enum NumberFormatter.RoundingPriority

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Enum NumberFormatter.SignDisplay

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Enum NumberFormatter.TrailingZeroDisplay

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Enum NumberFormatter.UnitWidth

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail