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 a DecimalFormatSymbols instance to the formatSymbols method or by directly calling the various other builder configuration methods, such as digits.

Comparison with DecimalFormat

This type provides some of the same functionality as Java's own java.text.DecimalFormat. However, unlike DecimalFormat, 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.

It should be noted that the output String is created by formatting the output of Double#toString(). This limits the output precision to the precision required to exactly represent the input double and is dependent on the JDK implementation of Double#toString(). A number formatted with the maximum precision should be parsed to the same input double. This implementation cannot extend the String to the required length to represent the exact decimal value of the double as per BigDecimal#toString().

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.