com.ibm.icu.number.Notation Maven / Gradle / Ivy
Show all versions of icu4j Show documentation
// © 2017 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html#License
package com.ibm.icu.number;
import com.ibm.icu.number.NumberFormatter.SignDisplay;
import com.ibm.icu.text.CompactDecimalFormat.CompactStyle;
/**
* A class that defines the notation style to be used when formatting numbers in NumberFormatter.
*
* @draft ICU 60
* @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public class Notation {
// TODO: Support engineering intervals other than 3?
private static final ScientificNotation SCIENTIFIC = new ScientificNotation(1,
false,
1,
SignDisplay.AUTO);
private static final ScientificNotation ENGINEERING = new ScientificNotation(3,
false,
1,
SignDisplay.AUTO);
private static final CompactNotation COMPACT_SHORT = new CompactNotation(CompactStyle.SHORT);
private static final CompactNotation COMPACT_LONG = new CompactNotation(CompactStyle.LONG);
private static final SimpleNotation SIMPLE = new SimpleNotation();
/* package-private */ Notation() {
}
/**
* Print the number using scientific notation (also known as scientific form, standard index form, or
* standard form in the UK). The format for scientific notation varies by locale; for example, many
* Western locales display the number in the form "#E0", where the number is displayed with one digit
* before the decimal separator, zero or more digits after the decimal separator, and the
* corresponding power of 10 displayed after the "E".
*
*
* Example outputs in en-US when printing 8.765E4 through 8.765E-3:
*
*
* 8.765E4
* 8.765E3
* 8.765E2
* 8.765E1
* 8.765E0
* 8.765E-1
* 8.765E-2
* 8.765E-3
* 0E0
*
*
* @return A ScientificNotation for chaining or passing to the NumberFormatter notation() setter.
* @draft ICU 60
* @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static ScientificNotation scientific() {
return SCIENTIFIC;
}
/**
* Print the number using engineering notation, a variant of scientific notation in which the
* exponent must be divisible by 3.
*
*
* Example outputs in en-US when printing 8.765E4 through 8.765E-3:
*
*
* 87.65E3
* 8.765E3
* 876.5E0
* 87.65E0
* 8.765E0
* 876.5E-3
* 87.65E-3
* 8.765E-3
* 0E0
*
*
* @return A ScientificNotation for chaining or passing to the NumberFormatter notation() setter.
* @draft ICU 60
* @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static ScientificNotation engineering() {
return ENGINEERING;
}
/**
* Print the number using short-form compact notation.
*
*
* Compact notation, defined in Unicode Technical Standard #35 Part 3 Section 2.4.1, prints
* numbers with localized prefixes or suffixes corresponding to different powers of ten. Compact
* notation is similar to engineering notation in how it scales numbers.
*
*
* Compact notation is ideal for displaying large numbers (over ~1000) to humans while at the same
* time minimizing screen real estate.
*
*
* In short form, the powers of ten are abbreviated. In en-US, the abbreviations are "K" for
* thousands, "M" for millions, "B" for billions, and "T" for trillions. Example outputs in
* en-US when printing 8.765E7 through 8.765E0:
*
*
* 88M
* 8.8M
* 876K
* 88K
* 8.8K
* 876
* 88
* 8.8
*
*
*
* When compact notation is specified without an explicit rounding strategy, numbers are rounded off
* to the closest integer after scaling the number by the corresponding power of 10, but with a digit
* shown after the decimal separator if there is only one digit before the decimal separator. The
* default compact notation rounding strategy is equivalent to:
*
*
* Rounder.integer().withMinDigits(2)
*
*
* @return A CompactNotation for passing to the NumberFormatter notation() setter.
* @draft ICU 60
* @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static CompactNotation compactShort() {
return COMPACT_SHORT;
}
/**
* Print the number using long-form compact notation. For more information on compact notation, see
* {@link #compactShort}.
*
*
* In long form, the powers of ten are spelled out fully. Example outputs in en-US when
* printing 8.765E7 through 8.765E0:
*
*
* 88 million
* 8.8 million
* 876 thousand
* 88 thousand
* 8.8 thousand
* 876
* 88
* 8.8
*
*
* @return A CompactNotation for passing to the NumberFormatter notation() setter.
* @draft ICU 60
* @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static CompactNotation compactLong() {
return COMPACT_LONG;
}
/**
* Print the number using simple notation without any scaling by powers of ten. This is the default
* behavior.
*
*
* Since this is the default behavior, this method needs to be called only when it is necessary to
* override a previous setting.
*
*
* Example outputs in en-US when printing 8.765E7 through 8.765E0:
*
*
* 87,650,000
* 8,765,000
* 876,500
* 87,650
* 8,765
* 876.5
* 87.65
* 8.765
*
*
* @return A SimpleNotation for passing to the NumberFormatter notation() setter.
* @draft ICU 60
* @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static SimpleNotation simple() {
return SIMPLE;
}
}