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

Package org.apache.commons.text.numbers

# Class DoubleFormat.Builder

java.lang.Object
org.apache.commons.text.numbers.DoubleFormat.Builder

Enclosing class:
  `DoubleFormat`

public static final class DoubleFormat.Builder extends Object
Builds configured format functions for standard double format types.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DoubleFormat.Builder`
  `allowSignedZero(boolean signedZero)`
  Sets the flag determining whether or not the zero string may be returned with the minus sign or if it will always be returned in the positive form.
  `DoubleFormat.Builder`
  `alwaysIncludeExponent(boolean alwaysIncludeExponent)`
  Sets the flag indicating if an exponent value should always be included in the formatted value, even if the exponent value is zero.
  `DoubleFunction<String>`
  `build()`
  Builds a new double format function.
  `DoubleFormat.Builder`
  `decimalSeparator(char decimalSeparator)`
  Sets the decimal separator character, i.e., the character placed between the whole number and fractional portions of the formatted strings.
  `DoubleFormat.Builder`
  `digits(String digits)`
  Sets the string containing the digit characters 0-9, in that order.
  `DoubleFormat.Builder`
  `exponentSeparator(String exponentSeparator)`
  Sets the exponent separator character, i.e., the string placed between the mantissa and the exponent.
  `DoubleFormat.Builder`
  `formatSymbols(DecimalFormatSymbols symbols)`
  Configures this instance with the given format symbols.
  `DoubleFormat.Builder`
  `groupingSeparator(char groupingSeparator)`
  Sets the character used to separate groups of thousands.
  `DoubleFormat.Builder`
  `groupThousands(boolean groupThousands)`
  If set to `true`, thousands will be grouped with the `grouping separator`.
  `DoubleFormat.Builder`
  `includeFractionPlaceholder(boolean fractionPlaceholder)`
  Sets the flag determining whether or not a zero character is added in the fraction position when no fractional value is present.
  `DoubleFormat.Builder`
  `infinity(String infinity)`
  Sets the string used to represent infinity.
  `DoubleFormat.Builder`
  `maxPrecision(int maxPrecision)`
  Sets the maximum number of significant decimal digits used in format results.
  `DoubleFormat.Builder`
  `minDecimalExponent(int minDecimalExponent)`
  Sets the minimum decimal exponent for formatted strings.
  `DoubleFormat.Builder`
  `minusSign(char minusSign)`
  Sets the character used as the minus sign.
  `DoubleFormat.Builder`
  `nan(String nan)`
  Sets the string used to represent `Double.NaN`.
  `DoubleFormat.Builder`
  `plainFormatMaxDecimalExponent(int plainFormatMaxDecimalExponent)`
  Sets the maximum decimal exponent for numbers formatted as plain decimal strings when using the `MIXED` format type.
  `DoubleFormat.Builder`
  `plainFormatMinDecimalExponent(int plainFormatMinDecimalExponent)`
  Sets the minimum decimal exponent for numbers formatted as plain decimal strings when using the `MIXED` format type.

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### allowSignedZero

    public DoubleFormat.Builder allowSignedZero(boolean signedZero)
    Sets the flag determining whether or not the zero string may be returned with the minus sign or if it will always be returned in the positive form. For example, if set to `true`, the string `"-0.0"` may be returned for some input numbers. If `false`, only `"0.0"` will be returned, regardless of the sign of the input number. The default value is `true`.
    Parameters:
      `signedZero` - if `true`, the zero string may be returned with a preceding minus sign; if `false`, the zero string will only be returned in its positive form
    Returns:
      this instance

  - ### alwaysIncludeExponent

    public DoubleFormat.Builder alwaysIncludeExponent(boolean alwaysIncludeExponent)
    Sets the flag indicating if an exponent value should always be included in the formatted value, even if the exponent value is zero. This property only applies to formats that use scientific notation, namely `SCIENTIFIC`, `ENGINEERING`, and `MIXED`. The default value is `false`.
    Parameters:
      `alwaysIncludeExponent` - if `true`, exponents will always be included in formatted output even if the exponent value is zero
    Returns:
      this instance

  - ### build

    public DoubleFunction<String> build()
    Builds a new double format function.
    Returns:
      format function

  - ### decimalSeparator

    public DoubleFormat.Builder decimalSeparator(char decimalSeparator)
    Sets the decimal separator character, i.e., the character placed between the whole number and fractional portions of the formatted strings. The default value is `'.'`.
    Parameters:
      `decimalSeparator` - decimal separator character
    Returns:
      this instance

  - ### digits

    public DoubleFormat.Builder digits(String digits)
    Sets the string containing the digit characters 0-9, in that order. The default value is the string `"0123456789"`.
    Parameters:
      `digits` - string containing the digit characters 0-9
    Returns:
      this instance
    Throws:
      `NullPointerException` - if the argument is `null`
      `IllegalArgumentException` - if the argument does not have a length of exactly 10

  - ### exponentSeparator

    public DoubleFormat.Builder exponentSeparator(String exponentSeparator)
    Sets the exponent separator character, i.e., the string placed between the mantissa and the exponent. The default value is `"E"`, as in `"1.2E6"`.
    Parameters:
      `exponentSeparator` - exponent separator string
    Returns:
      this instance
    Throws:
      `NullPointerException` - if the argument is `null`

  - ### formatSymbols

    public DoubleFormat.Builder formatSymbols(DecimalFormatSymbols symbols)
    Configures this instance with the given format symbols. The following values are set:
    - `digit characters`
    - `decimal separator`
    - `thousands grouping separator`
    - `minus sign`
    - `exponent separator`
    - `infinity`
    - `NaN`
    The digit character string is constructed by starting at the configured `zero digit` and adding the next 9 consecutive characters.
    Parameters:
      `symbols` - format symbols
    Returns:
      this instance
    Throws:
      `NullPointerException` - if the argument is `null`

  - ### groupingSeparator

    public DoubleFormat.Builder groupingSeparator(char groupingSeparator)
    Sets the character used to separate groups of thousands. Default value is `','`.
    Parameters:
      `groupingSeparator` - character used to separate groups of thousands
    Returns:
      this instance
    See Also:
      - `groupThousands(boolean)`

  - ### groupThousands

    public DoubleFormat.Builder groupThousands(boolean groupThousands)
    If set to `true`, thousands will be grouped with the `grouping separator`. For example, if set to `true`, the number `1000` could be formatted as `"1,000"`. This property only applies to the `PLAIN` format. Default value is `false`.
    Parameters:
      `groupThousands` - if `true`, thousands will be grouped
    Returns:
      this instance
    See Also:
      - `groupingSeparator(char)`

  - ### includeFractionPlaceholder

    public DoubleFormat.Builder includeFractionPlaceholder(boolean fractionPlaceholder)
    Sets the flag determining whether or not a zero character is added in the fraction position when no fractional value is present. For example, if set to `true`, the number `1` would be formatted as `"1.0"`. If `false`, it would be formatted as `"1"`. The default value is `true`.
    Parameters:
      `fractionPlaceholder` - if `true`, a zero character is placed in the fraction position when no fractional value is present; if `false`, fractional digits are only included when needed
    Returns:
      this instance

  - ### infinity

    public DoubleFormat.Builder infinity(String infinity)
    Sets the string used to represent infinity. For negative infinity, this string is prefixed with the `minus sign`.
    Parameters:
      `infinity` - string used to represent infinity
    Returns:
      this instance
    Throws:
      `NullPointerException` - if the argument is `null`

  - ### maxPrecision

    public DoubleFormat.Builder maxPrecision(int maxPrecision)
    Sets the maximum number of significant decimal digits used in format results. A value of `0` indicates no limit. The default value is `0`.
    Parameters:
      `maxPrecision` - maximum precision
    Returns:
      this instance

  - ### minDecimalExponent

    public DoubleFormat.Builder minDecimalExponent(int minDecimalExponent)
    Sets the minimum decimal exponent for formatted strings. No digits with an absolute value of less than `10minDecimalExponent` will be included in format results. If the number being formatted does not contain any such digits, then zero is returned. For example, if `minDecimalExponent` is set to `-2` and the number `3.14159` is formatted, the plain format result will be `"3.14"`. If `0.001` is formatted, then the result is the zero string.
    Parameters:
      `minDecimalExponent` - minimum decimal exponent
    Returns:
      this instance

  - ### minusSign

    public DoubleFormat.Builder minusSign(char minusSign)
    Sets the character used as the minus sign.
    Parameters:
      `minusSign` - character to use as the minus sign
    Returns:
      this instance

  - ### nan

    public DoubleFormat.Builder nan(String nan)
    Sets the string used to represent `Double.NaN`.
    Parameters:
      `nan` - string used to represent `Double.NaN`
    Returns:
      this instance
    Throws:
      `NullPointerException` - if the argument is `null`

  - ### plainFormatMaxDecimalExponent

    public DoubleFormat.Builder plainFormatMaxDecimalExponent(int plainFormatMaxDecimalExponent)
    Sets the maximum decimal exponent for numbers formatted as plain decimal strings when using the `MIXED` format type. If the number being formatted has an absolute value less than `10plainFormatMaxDecimalExponent + 1` and greater than or equal to `10plainFormatMinDecimalExponent` after any necessary rounding, then the formatted result will use the `PLAIN` format type. Otherwise, `SCIENTIFIC` format will be used. For example, if this value is set to `2`, the number `999` will be formatted as `"999.0"` while `1000` will be formatted as `"1.0E3"`.

    The default value is `6`.

    This value is ignored for formats other than `DoubleFormat.MIXED`.

    Parameters:
      `plainFormatMaxDecimalExponent` - maximum decimal exponent for values formatted as plain strings when using the `MIXED` format type.
    Returns:
      this instance
    See Also:
      - `plainFormatMinDecimalExponent(int)`

  - ### plainFormatMinDecimalExponent

    public DoubleFormat.Builder plainFormatMinDecimalExponent(int plainFormatMinDecimalExponent)
    Sets the minimum decimal exponent for numbers formatted as plain decimal strings when using the `MIXED` format type. If the number being formatted has an absolute value less than `10plainFormatMaxDecimalExponent + 1` and greater than or equal to `10plainFormatMinDecimalExponent` after any necessary rounding, then the formatted result will use the `PLAIN` format type. Otherwise, `SCIENTIFIC` format will be used. For example, if this value is set to `-2`, the number `0.01` will be formatted as `"0.01"` while `0.0099` will be formatted as `"9.9E-3"`.

    The default value is `-3`.

    This value is ignored for formats other than `DoubleFormat.MIXED`.

    Parameters:
      `plainFormatMinDecimalExponent` - maximum decimal exponent for values formatted as plain strings when using the `MIXED` format type.
    Returns:
      this instance
    See Also:
      - `plainFormatMinDecimalExponent(int)`