DoubleFormat (Apache Commons Text 1.13.0 API)
Description: declaration: package: org.apache.commons.text.numbers, enum: DoubleFormat

Package org.apache.commons.text.numbers

# Enum DoubleFormat

java.lang.Object
java.lang.Enum<DoubleFormat>
org.apache.commons.text.numbers.DoubleFormat

All Implemented Interfaces:
  `Serializable`, `Comparable<DoubleFormat>`

public enum DoubleFormat extends 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 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 `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.

Since:
  1.10.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `DoubleFormat.Builder`
  Builds configured format functions for standard double format types.

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `ENGINEERING`
  Number format similar to `scientific format` but adjusted so that the exponent value is always a multiple of 3, allowing easier alignment with SI prefixes.
  `MIXED`
  Number format that uses `plain format` for small numbers and `scientific 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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DoubleFormat.Builder`
  `builder()`
  Creates a `DoubleFormat.Builder` for building formatter functions for this format type.
  `static DoubleFormat`
  `valueOf(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.

  ### Methods inherited from class java.lang.Enum

  `clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

  ### Methods inherited from class java.lang.Object

  `getClass, notify, notifyAll, wait, wait, wait`

- ## Enum Constant Details

  - ### PLAIN

    public static final DoubleFormat PLAIN
    Number format without exponents.

    For example:

         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.

    For example:

         0.0
         1.2401E1
         1.0E5
         1.45E9
         1.23E-11

  - ### ENGINEERING

    public static final DoubleFormat ENGINEERING
    Number format similar to `scientific format` but adjusted so that the exponent value is always a multiple of 3, allowing easier alignment with SI prefixes.

    For example:

         0.0
         12.401
         100.0E3
         1.45E9
         12.3E-12

  - ### MIXED

    public static final DoubleFormat MIXED
    Number format that uses `plain format` for small numbers and `scientific format` for large numbers. The number thresholds can be configured through the `plainFormatMinDecimalExponent` and `plainFormatMaxDecimalExponent` properties.

    For example:

         0.0
         12.401
         100000.0
         1.45E9
         1.23E-11

- ## Method Details

  - ### values

    public static DoubleFormat[] values()
    Returns an array containing the constants of this enum type, in the order they are declared.
    Returns:
      an array containing the constants of this enum type, in the order they are declared

  - ### valueOf

    public static DoubleFormat valueOf(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:
      `IllegalArgumentException` - if this enum type has no constant with the specified name
      `NullPointerException` - if the argument is null

  - ### builder

    public DoubleFormat.Builder builder()
    Creates a `DoubleFormat.Builder` for building formatter functions for this format type.
    Returns:
      builder instance