Enum 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 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.

    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 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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      DoubleFormat.Builder builder()
      Creates a DoubleFormat.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.
      • 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 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 to scientific 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 uses plain format for small numbers and scientific format for large numbers. The number thresholds can be configured through the plainFormatMinDecimalExponent and plainFormatMaxDecimalExponent properties. Ex:
         0.0
         12.401
         100000.0
         1.45E9
         1.23E-11
         
    • 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 name
        java.lang.NullPointerException - if the argument is null