<packageset dir="${icu4j.core.dir}/src">
<include name="com/ibm/icu/lang/**"/>
<include name="com/ibm/icu/math/**"/>
+ <include name="com/ibm/icu/number/**"/>
<include name="com/ibm/icu/text/**"/>
<include name="com/ibm/icu/util/**"/>
</packageset>
<packageset dir="${icu4j.core.dir}/src">
<include name="com/ibm/icu/lang/**"/>
<include name="com/ibm/icu/math/**"/>
+ <include name="com/ibm/icu/number/**"/>
<include name="com/ibm/icu/text/**"/>
<include name="com/ibm/icu/util/**"/>
</packageset>
<packageset dir="${icu4j.core.dir}/src">
<include name="com/ibm/icu/lang/**"/>
<include name="com/ibm/icu/math/**"/>
+ <include name="com/ibm/icu/number/**"/>
<include name="com/ibm/icu/text/**"/>
<include name="com/ibm/icu/util/**"/>
</packageset>
<packageset dir="${icu4j.core.dir}/src">
<include name="com/ibm/icu/lang/**"/>
<include name="com/ibm/icu/math/**"/>
+ <include name="com/ibm/icu/number/**"/>
<include name="com/ibm/icu/text/**"/>
<include name="com/ibm/icu/util/**"/>
</packageset>
<packageset dir="${icu4j.core.dir}/src">
<include name="com/ibm/icu/lang/**"/>
<include name="com/ibm/icu/math/**"/>
+ <include name="com/ibm/icu/number/**"/>
<include name="com/ibm/icu/text/**"/>
<include name="com/ibm/icu/util/**"/>
</packageset>
<packageset dir="${icu4j.core.dir}/src">
<include name="com/ibm/icu/lang/**"/>
<include name="com/ibm/icu/math/**"/>
+ <include name="com/ibm/icu/number/**"/>
<include name="com/ibm/icu/text/**"/>
<include name="com/ibm/icu/util/**"/>
</packageset>
// License & terms of use: http://www.unicode.org/copyright.html#License
package com.ibm.icu.impl.number;
+/**
+ * An interface used by compact notation and scientific notation to choose a multiplier while rounding.
+ */
public interface MultiplierProducer {
int getMultiplier(int magnitude);
-}
\ No newline at end of file
+}
* {@link Notation}.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public class CompactNotation extends Notation {
* To create a CurrencyRounder, use one of the factory methods on Rounder.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public abstract class CurrencyRounder extends Rounder {
* The currency to associate with this rounding strategy.
* @return A Rounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public Rounder withCurrency(Currency currency) {
import com.ibm.icu.text.PluralRules.IFixedDecimal;
import com.ibm.icu.util.ICUUncheckedIOException;
+/**
+ * The result of a number formatting operation. This class allows the result to be exported in several data types,
+ * including a String, an AttributedCharacterIterator, and a BigDecimal.
+ *
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public class FormattedNumber {
NumberStringBuilder nsb;
DecimalQuantity fq;
this.micros = micros;
}
+ /**
+ * Creates a String representation of the the formatted number.
+ *
+ * @return a String containing the localized number.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
@Override
public String toString() {
return nsb.toString();
}
+ /**
+ * Append the formatted number to an Appendable, such as a StringBuilder. This may be slightly more efficient than
+ * creating a String.
+ *
+ * <p>
+ * If an IOException occurs when appending to the Appendable, an unchecked {@link ICUUncheckedIOException} is thrown
+ * instead.
+ *
+ * @param appendable
+ * The Appendable to which to append the formatted number string.
+ * @return The same Appendable, for chaining.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see Appendable
+ * @see NumberFormatter
+ */
public <A extends Appendable> A appendTo(A appendable) {
try {
appendable.append(nsb);
return appendable;
}
+ /**
+ * Determine the start and end indices of the first occurrence of the given <em>field</em> in the output string.
+ * This allows you to determine the locations of the integer part, fraction part, and sign.
+ *
+ * <p>
+ * If multiple different field attributes are needed, this method can be called repeatedly, or if <em>all</em> field
+ * attributes are needed, consider using getFieldIterator().
+ *
+ * <p>
+ * If a field occurs multiple times in an output string, such as a grouping separator, this method will only ever
+ * return the first occurrence. Use getFieldIterator() to access all occurrences of an attribute.
+ *
+ * @param fieldPosition
+ * The FieldPosition to populate with the start and end indices of the desired field.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see com.ibm.icu.text.NumberFormat.Field
+ * @see NumberFormatter
+ */
public void populateFieldPosition(FieldPosition fieldPosition) {
populateFieldPosition(fieldPosition, 0);
}
fq.populateUFieldPosition(fieldPosition);
}
- public AttributedCharacterIterator getAttributes() {
+ /**
+ * Export the formatted number as an AttributedCharacterIterator. This allows you to determine which characters in
+ * the output string correspond to which <em>fields</em>, such as the integer part, fraction part, and sign.
+ *
+ * <p>
+ * If information on only one field is needed, consider using populateFieldPosition() instead.
+ *
+ * @return An AttributedCharacterIterator, containing information on the field attributes of the number string.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see com.ibm.icu.text.NumberFormat.Field
+ * @see AttributedCharacterIterator
+ * @see NumberFormatter
+ */
+ public AttributedCharacterIterator getFieldIterator() {
return nsb.getIterator();
}
+ /**
+ * Export the formatted number as a BigDecimal. This endpoint is useful for obtaining the exact number being printed
+ * after scaling and rounding have been applied by the number formatting pipeline.
+ *
+ * @return A BigDecimal representation of the formatted number.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public BigDecimal toBigDecimal() {
return fq.toBigDecimal();
}
/**
* @internal
- * @deprecated This API a technology preview. It is not stable and may change or go away in an upcoming release.
+ * @deprecated This API is ICU internal only.
*/
@Deprecated
public String getPrefix() {
/**
* @internal
- * @deprecated This API a technology preview. It is not stable and may change or go away in an upcoming release.
+ * @deprecated This API is ICU internal only.
*/
@Deprecated
public String getSuffix() {
/**
* @internal
- * @deprecated This API a technology preview. It is not stable and may change or go away in an upcoming release.
+ * @deprecated This API is ICU internal only.
*/
@Deprecated
public IFixedDecimal getFixedDecimal() {
* To create a FractionRounder, use one of the factory methods on Rounder.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public abstract class FractionRounder extends Rounder {
* The number of significant figures to guarantee.
* @return A Rounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public Rounder withMinDigits(int minSignificantDigits) {
* Round the number to no more than this number of significant figures.
* @return A Rounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public Rounder withMaxDigits(int maxSignificantDigits) {
import com.ibm.icu.impl.number.DecimalQuantity;
import com.ibm.icu.impl.number.PatternStringParser.ParsedPatternInfo;
+/**
+ * @internal
+ * @deprecated This API is a technical preview. It is likely to change in an upcoming release.
+ */
+@Deprecated
public class Grouper {
// Conveniences for Java handling of bytes
this.min2 = min2;
}
+ /**
+ * @internal
+ * @deprecated This API is a technical preview. It is likely to change in an upcoming release.
+ */
+ @Deprecated
public static Grouper defaults() {
return DEFAULTS;
}
+ /**
+ * @internal
+ * @deprecated This API is a technical preview. It is likely to change in an upcoming release.
+ */
+ @Deprecated
public static Grouper minTwoDigits() {
return MIN2;
}
+ /**
+ * @internal
+ * @deprecated This API is a technical preview. It is likely to change in an upcoming release.
+ */
+ @Deprecated
public static Grouper none() {
return NONE;
}
return position >= 0 && (position % grouping2) == 0
&& value.getUpperDisplayMagnitude() - grouping1 + 1 >= (min2 ? 2 : 1);
}
- }
\ No newline at end of file
+}
\ No newline at end of file
import com.ibm.icu.impl.number.RoundingUtils;
-@SuppressWarnings("unused")
+/**
+ * A class that defines the strategy for padding and truncating integers before the decimal separator.
+ *
+ * <p>
+ * To create an IntegerWidth, use one of the factory methods.
+ *
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public class IntegerWidth {
/* package-private */ static final IntegerWidth DEFAULT = new IntegerWidth(1, -1);
this.maxInt = maxInt;
}
+ /**
+ * Pad numbers at the beginning with zeros to guarantee a certain number of numerals before the decimal separator.
+ *
+ * <p>
+ * For example, with minInt=3, the number 55 will get printed as "055".
+ *
+ * @param minInt
+ * The minimum number of places before the decimal separator.
+ * @return An IntegerWidth for chaining or passing to the NumberFormatter integerWidth() setter.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public static IntegerWidth zeroFillTo(int minInt) {
if (minInt == 1) {
return DEFAULT;
}
}
+ /**
+ * Truncate numbers exceeding a certain number of numerals before the decimal separator.
+ *
+ * For example, with maxInt=3, the number 1234 will get printed as "234".
+ *
+ * @param maxInt
+ * The maximum number of places before the decimal separator.
+ * @return An IntegerWidth for passing to the NumberFormatter integerWidth() setter.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public IntegerWidth truncateAt(int maxInt) {
if (maxInt == this.maxInt) {
return this;
// License & terms of use: http://www.unicode.org/copyright.html#License
package com.ibm.icu.number;
+import java.math.BigInteger;
import java.util.Objects;
import java.util.concurrent.atomic.AtomicLongFieldUpdater;
import com.ibm.icu.impl.number.MacroProps;
import com.ibm.icu.impl.number.MicroProps;
import com.ibm.icu.impl.number.NumberStringBuilder;
+import com.ibm.icu.math.BigDecimal;
+import com.ibm.icu.util.CurrencyAmount;
import com.ibm.icu.util.Measure;
import com.ibm.icu.util.MeasureUnit;
+/**
+ * A NumberFormatter that has a locale associated with it; this means .format() methods are available.
+ *
+ * @see NumberFormatter
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public class LocalizedNumberFormatter extends NumberFormatterSettings<LocalizedNumberFormatter> {
static final AtomicLongFieldUpdater<LocalizedNumberFormatter> callCount = AtomicLongFieldUpdater
super(parent, key, value);
}
+ /**
+ * Format the given byte, short, int, or long to a string using the settings specified in the NumberFormatter fluent
+ * setting chain.
+ *
+ * @param input
+ * The number to format.
+ * @return A FormattedNumber object; call .toString() to get the string.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public FormattedNumber format(long input) {
return format(new DecimalQuantity_DualStorageBCD(input));
}
+ /**
+ * Format the given float or double to a string using the settings specified in the NumberFormatter fluent setting
+ * chain.
+ *
+ * @param input
+ * The number to format.
+ * @return A FormattedNumber object; call .toString() to get the string.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public FormattedNumber format(double input) {
return format(new DecimalQuantity_DualStorageBCD(input));
}
+ /**
+ * Format the given {@link BigInteger}, {@link BigDecimal}, or other {@link Number} to a string using the settings
+ * specified in the NumberFormatter fluent setting chain.
+ *
+ * @param input
+ * The number to format.
+ * @return A FormattedNumber object; call .toString() to get the string.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public FormattedNumber format(Number input) {
return format(new DecimalQuantity_DualStorageBCD(input));
}
+ /**
+ * Format the given {@link Measure} or {@link CurrencyAmount} to a string using the settings specified in the
+ * NumberFormatter fluent setting chain.
+ *
+ * <p>
+ * The unit specified here overrides any unit that may have been specified in the setter chain. This method is
+ * intended for cases when each input to the number formatter has a different unit.
+ *
+ * @param input
+ * The number to format.
+ * @return A FormattedNumber object; call .toString() to get the string.
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public FormattedNumber format(Measure input) {
MeasureUnit unit = input.getUnit();
Number number = input.getNumber();
}
@Override
- protected LocalizedNumberFormatter create(int key, Object value) {
+ LocalizedNumberFormatter create(int key, Object value) {
return new LocalizedNumberFormatter(this, key, value);
}
-
- /**
- * @internal
- * @deprecated ICU 60 This API is ICU internal only.
- */
- @Deprecated
- public static class Internal extends LocalizedNumberFormatter {
-
- /**
- * @internal
- * @deprecated ICU 60 This API is ICU internal only.
- */
- @Deprecated
- public Internal(NumberFormatterSettings<?> parent, int key, Object value) {
- super(parent, key, value);
- }
- }
}
\ No newline at end of file
* 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 {
*
* @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 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 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 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 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() {
import com.ibm.icu.text.DecimalFormatSymbols;
import com.ibm.icu.util.ULocale;
+/**
+ * The main entrypoint to the localized number formatting library introduced in ICU 60. Basic usage examples:
+ *
+ * <pre>
+ * // 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"))
+ * .rounding(Rounder.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)
+ * .rounding(Rounder.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
+ * </pre>
+ *
+ * <p>
+ * This API offers more features than {@link com.ibm.icu.text.DecimalFormat} and is geared toward new users of ICU.
+ *
+ * <p>
+ * NumberFormatter instances 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.
+ *
+ * <pre>
+ * UnlocalizedNumberFormatter formatter = UnlocalizedNumberFormatter.with().notation(Notation.scientific());
+ * formatter.rounding(Rounder.maxFraction(2)); // does nothing!
+ * formatter.locale(ULocale.ENGLISH).format(9.8765).toString(); // prints "9.8765E0", not "9.88E0"
+ * </pre>
+ *
+ * <p>
+ * This API is based on the <em>fluent</em> design pattern popularized by libraries such as Google's Guava. For
+ * extensive details on the design of this API, read <a href="https://goo.gl/szi5VB">the design doc</a>.
+ *
+ * @author Shane Carr
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ */
public final class NumberFormatter {
private static final UnlocalizedNumberFormatter BASE = new UnlocalizedNumberFormatter();
* An enum declaring how to render units, including currencies. Example outputs when formatting 123 USD and 123
* meters in <em>en-CA</em>:
*
- * <p>
* <ul>
* <li>NARROW*: "$123.00" and "123 m"
* <li>SHORT: "US$ 123.00" and "123 m"
* This enum is similar to {@link com.ibm.icu.text.MeasureFormat.FormatWidth}.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static enum UnitWidth {
* currencies.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
NARROW,
* currencies.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
SHORT,
* currencies.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
FULL_NAME,
* In CLDR, this option corresponds to the "¤¤" placeholder for currencies.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
ISO_CODE,
* equivalent to not specifying the unit at all.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
HIDDEN,
* An enum declaring how to denote positive and negative numbers. Example outputs when formatting 123 and -123 in
* <em>en-US</em>:
*
- * <p>
* <ul>
* <li>AUTO: "123" and "-123"
* <li>ALWAYS: "+123" and "-123"
* The exact format, including the position and the code point of the sign, differ by locale.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static enum SignDisplay {
* behavior.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
AUTO,
* Show the minus sign on negative numbers and the plus sign on positive numbers.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
ALWAYS,
* Do not show the sign on positive or negative numbers.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
NEVER,
* future.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
ACCOUNTING,
* For more information on the accounting format, see the ACCOUNTING sign display strategy.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
ACCOUNTING_ALWAYS,
* An enum declaring how to render the decimal separator. Example outputs when formatting 1 and 1.1 in
* <em>en-US</em>:
*
- * <p>
* <ul>
* <li>AUTO: "1" and "1.1"
* <li>ALWAYS: "1." and "1.1"
* </ul>
+ *
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
*/
public static enum DecimalSeparatorDisplay {
/**
* it otherwise. This is the default behavior.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
AUTO,
* Always show the decimal separator, even if there are no digits to display after the separator.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
ALWAYS,
*
* @return An {@link UnlocalizedNumberFormatter}, to be used for chaining.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
*/
public static UnlocalizedNumberFormatter with() {
return BASE;
* The locale from which to load formats and symbols for number formatting.
* @return A {@link LocalizedNumberFormatter}, to be used for chaining.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
*/
public static LocalizedNumberFormatter withLocale(Locale locale) {
return BASE.locale(locale);
* The locale from which to load formats and symbols for number formatting.
* @return A {@link LocalizedNumberFormatter}, to be used for chaining.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
*/
public static LocalizedNumberFormatter withLocale(ULocale locale) {
return BASE.locale(locale);
import com.ibm.icu.number.NumberFormatter.SignDisplay;
import com.ibm.icu.number.NumberFormatter.UnitWidth;
import com.ibm.icu.text.DecimalFormatSymbols;
-import com.ibm.icu.text.MeasureFormat.FormatWidth;
import com.ibm.icu.text.NumberingSystem;
import com.ibm.icu.util.Currency;
import com.ibm.icu.util.Measure;
/**
* An abstract base class for specifying settings related to number formatting. This class is implemented by
- * {@link UnlocalizedNumberFormatter} and {@link LocalizedNumberFormatter}.
+ * {@link UnlocalizedNumberFormatter} and {@link LocalizedNumberFormatter}. This class is not intended for public
+ * subclassing.
+ *
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
*/
public abstract class NumberFormatterSettings<T extends NumberFormatterSettings<?>> {
* The notation strategy to use.
* @return The fluent chain.
* @see Notation
- * @provisional This API might change or be removed in a future release.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
*/
public T notation(Notation notation) {
return create(KEY_NOTATION, notation);
* <p>
* <strong>Note:</strong> The unit can also be specified by passing a {@link Measure} to
* {@link LocalizedNumberFormatter#format(Measure)}. Units specified via the format method take precedence over
- * units specified here.
+ * units specified here. This setter is designed for situations when the unit is constant for the duration of the
+ * number formatting process.
*
* <p>
* All units will be properly localized with locale data, and all units are compatible with notation styles,
* @see MeasureUnit
* @see Currency
* @see NoUnit
- * @provisional This API might change or be removed in a future release.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
*/
public T unit(MeasureUnit unit) {
return create(KEY_UNIT, unit);
* NumberFormatter.with().rounding(Rounder.fixedFraction(2))
* </pre>
*
- * The default is to not perform rounding.
+ * <p>
+ * In most cases, the default rounding strategy is to round to 6 fraction places; i.e.,
+ * <code>Rounder.maxFraction(6)</code>. The exceptions are if compact notation is being used, then the compact
+ * notation rounding strategy is used (see {@link Notation#compactShort} for details), or if the unit is a currency,
+ * then standard currency rounding is used, which varies from currency to currency (see {@link Rounder#currency} for
+ * details).
*
* @param rounder
* The rounding strategy to use.
* @return The fluent chain.
* @see Rounder
- * @provisional This API might change or be removed in a future release.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
*/
public T rounding(Rounder rounder) {
return create(KEY_ROUNDER, rounder);
* @return The fluent chain.
* @see Grouper
* @see Notation
- * @provisional This API might change or be removed in a future release.
- * @draft ICU 60
+ * @internal
+ * @deprecated ICU 60 This API is technical preview; see #7861.
*/
+ @Deprecated
public T grouping(Grouper grouper) {
return create(KEY_GROUPER, grouper);
}
* The integer width to use.
* @return The fluent chain.
* @see IntegerWidth
- * @provisional This API might change or be removed in a future release.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
*/
public T integerWidth(IntegerWidth style) {
return create(KEY_INTEGER, style);
* The DecimalFormatSymbols to use.
* @return The fluent chain.
* @see DecimalFormatSymbols
- * @provisional This API might change or be removed in a future release.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
*/
public T symbols(DecimalFormatSymbols symbols) {
symbols = (DecimalFormatSymbols) symbols.clone();
* The NumberingSystem to use.
* @return The fluent chain.
* @see NumberingSystem
- * @provisional This API might change or be removed in a future release.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
*/
public T symbols(NumberingSystem ns) {
return create(KEY_SYMBOLS, ns);
}
/**
- * Sets the width of the unit (measure unit or currency).
+ * Sets the width of the unit (measure unit or currency). Most common values:
*
* <ul>
- * <li>Narrow: "$12.00", "12 m"
- * <li>Short: "12.00 USD", "12 m"
- * <li>Wide: "12.00 US dollars", "12 meters"
- * <li>Hidden: "12.00", "12"
+ * <li>Short: "$12.00", "12 m"
+ * <li>ISO Code: "USD 12.00"
+ * <li>Full name: "12.00 US dollars", "12 meters"
* </ul>
*
* <p>
- * Pass an element from the {@link FormatWidth} enum to this setter. For example:
+ * Pass an element from the {@link UnitWidth} enum to this setter. For example:
*
* <pre>
- * NumberFormatter.with().unitWidth(FormatWidth.SHORT)
+ * NumberFormatter.with().unitWidth(UnitWidth.FULL_NAME)
* </pre>
*
* <p>
- * The default is the narrow width.
+ * The default is the SHORT width.
*
* @param style
- * The with to use when rendering numbers.
+ * The width to use when rendering numbers.
* @return The fluent chain
- * @see FormatWidth
- * @provisional This API might change or be removed in a future release.
+ * @see UnitWidth
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
*/
public T unitWidth(UnitWidth style) {
return create(KEY_UNIT_WIDTH, style);
}
+ /**
+ * Sets the plus/minus sign display strategy. Most common values:
+ *
+ * <ul>
+ * <li>Auto: "123", "-123"
+ * <li>Always: "+123", "-123"
+ * <li>Accounting: "$123", "($123)"
+ * </ul>
+ *
+ * <p>
+ * Pass an element from the {@link SignDisplay} enum to this setter. For example:
+ *
+ * <pre>
+ * NumberFormatter.with().sign(SignDisplay.ALWAYS)
+ * </pre>
+ *
+ * <p>
+ * The default is AUTO sign display.
+ *
+ * @param style
+ * The sign display strategy to use when rendering numbers.
+ * @return The fluent chain
+ * @see SignDisplay
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ */
public T sign(SignDisplay style) {
return create(KEY_SIGN, style);
}
+ /**
+ * Sets the decimal separator display strategy. This affects integer numbers with no fraction part. Most common
+ * values:
+ *
+ * <ul>
+ * <li>Auto: "1"
+ * <li>Always: "1."
+ * </ul>
+ *
+ * <p>
+ * Pass an element from the {@link DecimalSeparatorDisplay} enum to this setter. For example:
+ *
+ * <pre>
+ * NumberFormatter.with().decimal(DecimalSeparatorDisplay.ALWAYS)
+ * </pre>
+ *
+ * <p>
+ * The default is AUTO decimal separator display.
+ *
+ * @param style
+ * The decimal separator display strategy to use when rendering numbers.
+ * @return The fluent chain
+ * @see DecimalSeparatorDisplay
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ */
public T decimal(DecimalSeparatorDisplay style) {
return create(KEY_DECIMAL, style);
}
- /** Internal method to set a starting macros. */
+ /**
+ * Internal method to set a starting macros.
+ *
+ * @internal
+ * @deprecated ICU 60 This API is ICU internal only.
+ */
+ @Deprecated
public T macros(MacroProps macros) {
return create(KEY_MACROS, macros);
}
- /** Non-public method */
+ /**
+ * Set the padding strategy. May be added to ICU 61; see #13338.
+ *
+ * @internal
+ * @deprecated ICU 60 This API is ICU internal only.
+ */
+ @Deprecated
public T padding(Padder padder) {
return create(KEY_PADDER, padder);
}
/**
* Internal fluent setter to support a custom regulation threshold. A threshold of 1 causes the data structures to
* be built right away. A threshold of 0 prevents the data structures from being built.
+ *
+ * @internal
+ * @deprecated ICU 60 This API is ICU internal only.
*/
+ @Deprecated
public T threshold(Long threshold) {
return create(KEY_THRESHOLD, threshold);
}
- abstract T create(int key, Object value);
+ /* package-protected */ abstract T create(int key, Object value);
MacroProps resolve() {
if (resolvedMacros != null) {
import com.ibm.icu.impl.number.Padder;
import com.ibm.icu.impl.number.PatternStringParser;
import com.ibm.icu.impl.number.PatternStringParser.ParsedPatternInfo;
+import com.ibm.icu.impl.number.RoundingUtils;
import com.ibm.icu.number.NumberFormatter.DecimalSeparatorDisplay;
import com.ibm.icu.number.NumberFormatter.SignDisplay;
import com.ibm.icu.number.Rounder.FractionRounderImpl;
import com.ibm.icu.number.Rounder.IncrementRounderImpl;
import com.ibm.icu.number.Rounder.SignificantRounderImpl;
-import com.ibm.icu.impl.number.RoundingUtils;
import com.ibm.icu.text.CompactDecimalFormat.CompactStyle;
import com.ibm.icu.text.CurrencyPluralInfo;
import com.ibm.icu.text.DecimalFormatSymbols;
minFrac = minFrac <= 0 ? 1 : minFrac;
maxFrac = maxFrac < 0 ? Integer.MAX_VALUE : maxFrac < minFrac ? minFrac : maxFrac;
minInt = 0;
- maxInt = maxInt < 0 ? -1 : maxInt;
+ maxInt = maxInt < 0 ? -1 : maxInt > RoundingUtils.MAX_INT_FRAC_SIG ? -1 : maxInt;
} else {
// Force a digit before the decimal point.
minFrac = minFrac < 0 ? 0 : minFrac;
maxFrac = maxFrac < 0 ? Integer.MAX_VALUE : maxFrac < minFrac ? minFrac : maxFrac;
- minInt = minInt <= 0 ? 1 : minInt;
- maxInt = maxInt < 0 ? -1 : maxInt < minInt ? minInt : maxInt;
+ minInt = minInt <= 0 ? 1 : minInt > RoundingUtils.MAX_INT_FRAC_SIG ? 1 : minInt;
+ maxInt = maxInt < 0 ? -1 : maxInt < minInt ? minInt : maxInt > RoundingUtils.MAX_INT_FRAC_SIG ? -1 : maxInt;
}
Rounder rounding = null;
if (explicitCurrencyUsage) {
} else if (roundingIncrement != null) {
rounding = Rounder.constructIncrement(roundingIncrement);
} else if (explicitMinMaxSig) {
- minSig = minSig < 1 ? 1 : minSig > 1000 ? 1000 : minSig;
- maxSig = maxSig < 0 ? 1000 : maxSig < minSig ? minSig : maxSig > 1000 ? 1000 : maxSig;
+ minSig = minSig < 1 ? 1 : minSig > RoundingUtils.MAX_INT_FRAC_SIG ? RoundingUtils.MAX_INT_FRAC_SIG : minSig;
+ maxSig = maxSig < 0 ? RoundingUtils.MAX_INT_FRAC_SIG
+ : maxSig < minSig ? minSig
+ : maxSig > RoundingUtils.MAX_INT_FRAC_SIG ? RoundingUtils.MAX_INT_FRAC_SIG : maxSig;
rounding = Rounder.constructSignificant(minSig, maxSig);
} else if (explicitMinMaxFrac) {
rounding = Rounder.constructFraction(minFrac, maxFrac);
if (properties.getMinimumExponentDigits() != -1) {
// Scientific notation is required.
+ // This whole section feels like a hack, but it is needed for regression tests.
// The mapping from property bag to scientific notation is nontrivial due to LDML rules.
- // The maximum of 8 engineering digits has unknown origins and is not in the spec.
+ // The maximum of 8 digits has unknown origins and is not in the spec.
+ if (maxInt > 8) {
+ maxInt = 8;
+ if (minInt > maxInt) {
+ minInt = maxInt;
+ }
+ macros.integerWidth = IntegerWidth.zeroFillTo(minInt).truncateAt(maxInt);
+ }
int engineering = (maxInt != -1) ? maxInt : properties.getMaximumIntegerDigits();
engineering = (engineering < 0) ? 0 : (engineering > 8) ? minInt : engineering;
// Bug #13289: if maxInt > minInt > 1, then minInt should be 1.
* To create a Rounder, use one of the factory methods.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public abstract class Rounder implements Cloneable {
*
* @return A Rounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static Rounder unlimited() {
*
* @return A FractionRounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static FractionRounder integer() {
* long or padding with zeros if too short).
* @return A FractionRounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static FractionRounder fixedFraction(int minMaxFractionPlaces) {
* necessary).
* @return A FractionRounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static FractionRounder minFraction(int minFractionPlaces) {
* The maximum number of numerals to display after the decimal mark (rounding if necessary).
* @return A FractionRounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static FractionRounder maxFraction(int maxFractionPlaces) {
* The maximum number of numerals to display after the decimal separator (rounding if necessary).
* @return A FractionRounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static FractionRounder minMaxFraction(int minFractionPlaces, int maxFractionPlaces) {
* zeros if too short).
* @return A Rounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static Rounder fixedDigits(int minMaxSignificantDigits) {
* The minimum number of significant digits to display (padding with zeros if too short).
* @return A Rounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static Rounder minDigits(int minSignificantDigits) {
* The maximum number of significant digits to display (rounding if too long).
* @return A Rounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static Rounder maxDigits(int maxSignificantDigits) {
* The maximum number of significant digits to display (rounding if necessary).
* @return A Rounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static Rounder minMaxDigits(int minSignificantDigits, int maxSignificantDigits) {
* The increment to which to round numbers.
* @return A Rounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static Rounder increment(BigDecimal roundingIncrement) {
* be limited by the available denominations of cash or coins).
* @return A CurrencyRounder for chaining or passing to the NumberFormatter rounding() setter.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public static CurrencyRounder currency(CurrencyUsage currencyUsage) {
* The RoundingMode to use.
* @return A Rounder for chaining.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public Rounder withMode(RoundingMode roundingMode) {
* To create a ScientificNotation, use one of the factory methods in {@link Notation}.
*
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public class ScientificNotation extends Notation implements Cloneable {
* The minimum number of digits to show in the exponent.
* @return A ScientificNotation, for chaining.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public ScientificNotation withMinExponentDigits(int minExponentDigits) {
* The strategy for displaying the sign in the exponent.
* @return A ScientificNotation, for chaining.
* @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
* @see NumberFormatter
*/
public ScientificNotation withExponentSignDisplay(SignDisplay exponentSignDisplay) {
// License & terms of use: http://www.unicode.org/copyright.html#License
package com.ibm.icu.number;
+/**
+ * A class that defines the simple notation style to be used when formatting numbers in NumberFormatter.
+ *
+ * <p>
+ * This class exposes no public functionality. To create a SimpleNotation, use one of the factory methods in
+ * {@link Notation}.
+ *
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ * @see NumberFormatter
+ */
public class SimpleNotation extends Notation {
/* package-private */ SimpleNotation() {
}
import com.ibm.icu.util.ULocale;
+/**
+ * A NumberFormatter that does not yet have a locale. In order to format numbers, a locale must be specified.
+ *
+ * @see NumberFormatter
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ */
public class UnlocalizedNumberFormatter extends NumberFormatterSettings<UnlocalizedNumberFormatter> {
/** Base constructor; called during startup only. Sets the threshold to the default value of 3. */
super(parent, key, value);
}
+ /**
+ * Associate the given locale with the number formatter. The locale is used for picking the appropriate symbols,
+ * formats, and other data for number display.
+ *
+ * <p>
+ * To use the Java default locale, call Locale.getDefault():
+ *
+ * <pre>
+ * NumberFormatter.with(). ... .locale(Locale.getDefault())
+ * </pre>
+ *
+ * @param locale
+ * The locale to use when loading data for number formatting.
+ * @return The fluent chain
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ */
public LocalizedNumberFormatter locale(Locale locale) {
return new LocalizedNumberFormatter(this, KEY_LOCALE, ULocale.forLocale(locale));
}
+ /**
+ * ULocale version of the {@link #locale(Locale)} setter above.
+ *
+ * @param locale
+ * The locale to use when loading data for number formatting.
+ * @return The fluent chain
+ * @see #locale(Locale)
+ * @draft ICU 60
+ * @provisional This API might change or be removed in a future release.
+ */
public LocalizedNumberFormatter locale(ULocale locale) {
return new LocalizedNumberFormatter(this, KEY_LOCALE, locale);
}
@Override
- protected UnlocalizedNumberFormatter create(int key, Object value) {
+ UnlocalizedNumberFormatter create(int key, Object value) {
return new UnlocalizedNumberFormatter(this, key, value);
}
}
\ No newline at end of file
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+
+<head>
+<!-- Copyright (C) 2017 and later: Unicode, Inc. and others.
+ License & terms of use: http://www.unicode.org/copyright.html#License
+-->
+<!-- Copyright (C) 2000-2004, International Business Machines Corporation and
+ others. All Rights Reserved.
+
+-->
+
+<title>ICU4J com.ibm.icu.number Package Overview</title>
+</head>
+
+<body bgcolor="white">
+
+<p>
+Library for localized number formatting introduced in ICU 60; for usage, see com.ibm.icu.number.NumberFormatter.
+</p>
+
+</body>
+</html>
* href="http://unicode.org/reports/tr35/tr35-numbers.html#Number_Format_Patterns">UTS #35</a>. Read
* the specification for more information on how all the properties in DecimalFormat fit together.
*
+ * <p><strong>NOTE:</strong> Starting in ICU 60, there is a new set of APIs for localized number
+ * formatting that are designed to be an improvement over DecimalFormat. New users are discouraged
+ * from using DecimalFormat. For more information, see the package com.ibm.icu.number.
+ *
* <h3>Example Usage</h3>
*
* <p>Customize settings on a DecimalFormat instance from the NumberFormat factory:
if (!(obj instanceof Number)) throw new IllegalArgumentException();
Number number = (Number) obj;
FormattedNumber output = formatter.format(number);
- return output.getAttributes();
+ return output.getFieldIterator();
}
/**
public class NumberingSystem {
private static final String[] OTHER_NS_KEYWORDS = { "native", "traditional", "finance" };
+ /**
+ * For convenience, an instance representing the <em>latn</em> numbering system, which
+ * corresponds to digits in the ASCII range '0' through '9'.
+ *
+ * @draft ICU 60
+ */
public static final NumberingSystem LATIN = lookupInstanceByName("latn");
/**
@Test
public void Test4110936()
{
+ // NOTE: Starting in ICU 60, the maximum integer digits is fixed at 100
NumberFormat nf = NumberFormat.getInstance();
- nf.setMaximumIntegerDigits(128);
- logln("setMaximumIntegerDigits(128)");
- if (nf.getMaximumIntegerDigits() != 128)
+ nf.setMaximumIntegerDigits(99);
+ logln("setMaximumIntegerDigits(99)");
+ if (nf.getMaximumIntegerDigits() != 99)
errln("getMaximumIntegerDigits() returns " +
nf.getMaximumIntegerDigits());
}
// Generate random doubles
String alert = "UNEXPECTED FAILURE: PLEASE REPORT THIS MESSAGE TO THE ICU TEAM: ";
Random rnd = new Random();
- for (int i = 0; i < 1000000; i++) {
+ for (int i = 0; i < 10000; i++) {
double d = Double.longBitsToDouble(rnd.nextLong());
if (Double.isNaN(d) || Double.isInfinite(d)) continue;
checkDoubleBehavior(d, false, alert);
import com.ibm.icu.util.NoUnit;
import com.ibm.icu.util.ULocale;
-public class NumberFormatterTest {
+public class NumberFormatterApiTest {
private static final Currency USD = Currency.getInstance("USD");
private static final Currency GBP = Currency.getInstance("GBP");
projects / icu / commitdiff