Package org.apache.commons.text.numbers
Enum DoubleFormat
- java.lang.Object
-
- java.lang.Enum<DoubleFormat>
-
- org.apache.commons.text.numbers.DoubleFormat
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Comparable<DoubleFormat>
public enum DoubleFormat extends java.lang.Enum<DoubleFormat>
Enum containing standard double format types with methods to produce configured formatter instances. This type is intended to provide a quick and convenient way to create lightweight, thread-safe double format functions for common format types using a builder pattern. Output can be localized by passing aDecimalFormatSymbols
instance to theformatSymbols
method or by directly calling the various other builder configuration methods, such asdigits
.Comparison with DecimalFormat
This type provides some of the same functionality as Java's own
DecimalFormat
. However, unlikeDecimalFormat
, the format functions produced by this type are lightweight and thread-safe, making them much easier to work with in multi-threaded environments. They also provide performance comparable to, and in many cases faster than,DecimalFormat
.Examples
// construct a formatter equivalent to Double.toString() DoubleFunction<String> fmt = DoubleFormat.MIXED.builder().build(); // construct a formatter equivalent to Double.toString() but using // format symbols for a specific locale DoubleFunction<String> fmt = DoubleFormat.MIXED.builder() .formatSymbols(DecimalFormatSymbols.getInstance(locale)) .build(); // construct a formatter equivalent to the DecimalFormat pattern "0.0##" DoubleFunction<String> fmt = DoubleFormat.PLAIN.builder() .minDecimalExponent(-3) .build(); // construct a formatter equivalent to the DecimalFormat pattern "#,##0.0##", // where whole number groups of thousands are separated DoubleFunction<String> fmt = DoubleFormat.PLAIN.builder() .minDecimalExponent(-3) .groupThousands(true) .build(); // construct a formatter equivalent to the DecimalFormat pattern "0.0##E0" DoubleFunction<String> fmt = DoubleFormat.SCIENTIFIC.builder() .maxPrecision(4) .alwaysIncludeExponent(true) .build() // construct a formatter equivalent to the DecimalFormat pattern "##0.0##E0", // i.e. "engineering format" DoubleFunction<String> fmt = DoubleFormat.ENGINEERING.builder() .maxPrecision(6) .alwaysIncludeExponent(true) .build()
Implementation Notes
Half-even
rounding is used in cases where the decimal value must be rounded in order to meet the configuration requirements of the formatter instance.- Since:
- 1.10.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
DoubleFormat.AbstractDoubleFormat
Base class for standard double formatting classes.static class
DoubleFormat.Builder
Builds configured format functions for standard double format types.private static class
DoubleFormat.EngineeringDoubleFormat
Format class that uses engineering notation for all values.private static class
DoubleFormat.MixedDoubleFormat
Format class producing results similar toDouble.toString()
, with plain decimal notation for small numbers relatively close to zero and scientific notation otherwise.private static class
DoubleFormat.PlainDoubleFormat
Format class that produces plain decimal strings that do not use scientific notation.private static class
DoubleFormat.ScientificDoubleFormat
Format class that uses scientific notation for all values.
-
Enum Constant Summary
Enum Constants Enum Constant Description ENGINEERING
Number format similar toscientific format
but adjusted so that the exponent value is always a multiple of 3, allowing easier alignment with SI prefixes.MIXED
Number format that usesplain format
for small numbers andscientific format
for large numbers.PLAIN
Number format without exponents.SCIENTIFIC
Number format that uses exponents and contains a single digit to the left of the decimal point.
-
Field Summary
Fields Modifier and Type Field Description private java.util.function.Function<DoubleFormat.Builder,java.util.function.DoubleFunction<java.lang.String>>
factory
Function used to construct instances for this format type.
-
Constructor Summary
Constructors Modifier Constructor Description private
DoubleFormat(java.util.function.Function<DoubleFormat.Builder,java.util.function.DoubleFunction<java.lang.String>> factory)
Constructs a new instance.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description DoubleFormat.Builder
builder()
Creates aDoubleFormat.Builder
for building formatter functions for this format type.static DoubleFormat
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.static DoubleFormat[]
values()
Returns an array containing the constants of this enum type, in the order they are declared.
-
-
-
Enum Constant Detail
-
PLAIN
public static final DoubleFormat PLAIN
Number format without exponents. Ex:0.0 12.401 100000.0 1450000000.0 0.0000000000123
-
SCIENTIFIC
public static final DoubleFormat SCIENTIFIC
Number format that uses exponents and contains a single digit to the left of the decimal point. Ex:0.0 1.2401E1 1.0E5 1.45E9 1.23E-11
-
ENGINEERING
public static final DoubleFormat ENGINEERING
Number format similar toscientific format
but adjusted so that the exponent value is always a multiple of 3, allowing easier alignment with SI prefixes. Ex:0.0 12.401 100.0E3 1.45E9 12.3E-12
-
MIXED
public static final DoubleFormat MIXED
Number format that usesplain format
for small numbers andscientific format
for large numbers. The number thresholds can be configured through theplainFormatMinDecimalExponent
andplainFormatMaxDecimalExponent
properties. Ex:0.0 12.401 100000.0 1.45E9 1.23E-11
-
-
Field Detail
-
factory
private final java.util.function.Function<DoubleFormat.Builder,java.util.function.DoubleFunction<java.lang.String>> factory
Function used to construct instances for this format type.
-
-
Constructor Detail
-
DoubleFormat
private DoubleFormat(java.util.function.Function<DoubleFormat.Builder,java.util.function.DoubleFunction<java.lang.String>> factory)
Constructs a new instance.- Parameters:
factory
- function used to construct format instances
-
-
Method Detail
-
values
public static DoubleFormat[] values()
Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:for (DoubleFormat c : DoubleFormat.values()) System.out.println(c);
- Returns:
- an array containing the constants of this enum type, in the order they are declared
-
valueOf
public static DoubleFormat valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)- Parameters:
name
- the name of the enum constant to be returned.- Returns:
- the enum constant with the specified name
- Throws:
java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is null
-
builder
public DoubleFormat.Builder builder()
Creates aDoubleFormat.Builder
for building formatter functions for this format type.- Returns:
- builder instance
-
-