Package org.apache.commons.text.numbers

Class ParsedDecimal

java.lang.Object
org.apache.commons.text.numbers.ParsedDecimal
final class ParsedDecimal extends Object
Internal class representing a decimal value parsed into separate components. Each number is represented with
  • a boolean flag for the sign,
  • a sequence of the digits 0 - 10 representing an unsigned integer with leading and trailing zeros removed, and
  • an exponent value that when applied to the base 10 digits produces a floating point value with the correct magnitude.

Examples

DoubleNegativeDigitsExponent
0.0false[0]0
1.2false[1, 2]-1
-0.00971true[9, 7, 1]-5
56300true[5, 6, 3]2

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    (package private) static interface 
    ParsedDecimal.FormatOptions
    Interface containing values used during string formatting.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final int
    DECIMAL_RADIX
    Radix for decimal numbers.
    private static final char
    DECIMAL_SEP_CHAR
    Decimal separator character.
    (package private) int
    digitCount
    Number of digits used in the digits array; not necessarily equal to the length.
    (package private) final int[]
    digits
    Array containing the significant decimal digits for the value.
    private static final int
    ENG_EXPONENT_MOD
    Number that exponents in engineering format must be a multiple of.
    (package private) int
    exponent
    Exponent for the value.
    private static final char
    EXPONENT_CHAR
    Exponent character.
    private static final char
    MINUS_CHAR
    Minus sign character.
    (package private) final boolean
    negative
    True if the value is negative.
    private char[]
    outputChars
    Output buffer for use in creating string representations.
    private int
    outputIdx
    Output buffer index.
    private static final int
    ROUND_CENTER
    Center value used when rounding.
    private static final int
    THOUSANDS_GROUP_SIZE
    Number of characters in thousands groupings.
    private static final char
    ZERO_CHAR
    Zero digit character.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    ParsedDecimal(boolean negative, int[] digits, int digitCount, int exponent)
    Constructs a new instance from its parts.

  • Method Summary

    Modifier and Type
    Method
    Description
    private void
    append(char ch)
    Appends the given character to the output buffer.
    private void
    append(char[] chars)
    Appends the given character array directly to the output buffer.
    private void
    appendFraction(int zeroCount, int startIdx, ParsedDecimal.FormatOptions opts)
    Appends the fractional component of the number to the current output buffer.
    private void
    appendLocalizedDigit(int n, char[] digitChars)
    Appends the localized representation of the digit n to the output buffer.
    private int
    appendWhole(int wholeCount, ParsedDecimal.FormatOptions opts)
    Appends the whole number portion of this value to the output buffer.
    private int
    appendWholeGrouped(int wholeCount, ParsedDecimal.FormatOptions opts)
    Appends the whole number portion of this value to the output buffer, adding thousands separators as needed.
    private static int
    digitValue(char ch)
    Gets the numeric value of the given digit character.
    static ParsedDecimal
    from(double d)
    Constructs a new instance from the given double value.
    private int
    getDigitStringSize(int decimalPos, ParsedDecimal.FormatOptions opts)
    Gets the number of characters required for the digit portion of a string representation of this value.
    int
    getExponent()
    Gets the exponent value.
    private int
    getPlainStringSize(int decimalPos, ParsedDecimal.FormatOptions opts)
    Gets the number of characters required to create a plain format representation of this value.
    int
    getScientificExponent()
    Get sthe exponent that would be used when representing this number in scientific notation (i.e., with a single non-zero digit in front of the decimal point).
    (package private) boolean
    isZero()
    Returns true if this value is equal to zero.
    void
    maxPrecision(int precision)
    Ensures that this instance has at most the given number of significant digits (i.e.
    private String
    outputString()
    Gets the output buffer as a string.
    private static int
    parseExponent(char[] chars, int start)
    Parses a double exponent value from chars, starting at the start index and continuing through the end of the array.
    private void
    prepareOutput(int size)
    Prepares the output buffer for a string of the given size.
    private boolean
    requiresGroupingSeparatorAfterPosition(int pos)
    Returns true if a grouping separator should be added after the whole digit character at the given position.
    void
    round(int roundExponent)
    Rounds the instance to the given decimal exponent position using half-even rounding.
    private void
    roundUp(int count)
    Rounds the value up to the given number of digits.
    private void
    setSingleDigitValue(int digit, int newExponent)
    Sets the value of this instance to a single digit with the given exponent.
    private boolean
    shouldIncludeExponent(int targetExponent, ParsedDecimal.FormatOptions opts)
    Returns true if a formatted string with the given target exponent should include the exponent field.
    private boolean
    shouldIncludeMinus(ParsedDecimal.FormatOptions opts)
    Returns true if formatted strings should include the minus sign, considering the value of this instance and the given format options.
    private boolean
    shouldRoundUp(int count)
    Returns true if a rounding operation for the given number of digits should round up.
    String
    toEngineeringString(ParsedDecimal.FormatOptions opts)
    Returns a string representation of this value in engineering notation.
    String
    toPlainString(ParsedDecimal.FormatOptions opts)
    Returns a string representation of this value with no exponent field.
    private String
    toScientificString(int decimalPos, ParsedDecimal.FormatOptions opts)
    Returns a string representation of the value in scientific notation using the given decimal point position.
    String
    toScientificString(ParsedDecimal.FormatOptions opts)
    Returns a string representation of this value in scientific notation.
    private void
    truncate(int count)
    Truncates the value to the given number of digits.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • MINUS_CHAR

      private static final char MINUS_CHAR
      Minus sign character.
      See Also:

    • DECIMAL_SEP_CHAR

      private static final char DECIMAL_SEP_CHAR
      Decimal separator character.
      See Also:

    • EXPONENT_CHAR

      private static final char EXPONENT_CHAR
      Exponent character.
      See Also:

    • ZERO_CHAR

      private static final char ZERO_CHAR
      Zero digit character.
      See Also:

    • THOUSANDS_GROUP_SIZE

      private static final int THOUSANDS_GROUP_SIZE
      Number of characters in thousands groupings.
      See Also:

    • DECIMAL_RADIX

      private static final int DECIMAL_RADIX
      Radix for decimal numbers.
      See Also:

    • ROUND_CENTER

      private static final int ROUND_CENTER
      Center value used when rounding.
      See Also:

    • ENG_EXPONENT_MOD

      private static final int ENG_EXPONENT_MOD
      Number that exponents in engineering format must be a multiple of.
      See Also:

    • negative

      final boolean negative
      True if the value is negative.

    • digits

      final int[] digits
      Array containing the significant decimal digits for the value.

    • digitCount

      int digitCount
      Number of digits used in the digits array; not necessarily equal to the length.

    • exponent

      int exponent
      Exponent for the value.

    • outputChars

      private char[] outputChars
      Output buffer for use in creating string representations.

    • outputIdx

      private int outputIdx
      Output buffer index.

  • Constructor Details

    • ParsedDecimal

      private ParsedDecimal(boolean negative, int[] digits, int digitCount, int exponent)
      Constructs a new instance from its parts.
      Parameters:
      negative - true if the value is negative
      digits - array containing significant digits
      digitCount - number of digits used from the digits array
      exponent - exponent value

  • Method Details

    • digitValue

      private static int digitValue(char ch)
      Gets the numeric value of the given digit character. No validation of the character type is performed.
      Parameters:
      ch - digit character
      Returns:
      numeric value of the digit character, ex: '1' = 1

    • from

      public static ParsedDecimal from(double d)
      Constructs a new instance from the given double value.
      Parameters:
      d - double value
      Returns:
      a new instance containing the parsed components of the given double value
      Throws:
      IllegalArgumentException - if d is NaN or infinite

    • parseExponent

      private static int parseExponent(char[] chars, int start)
      Parses a double exponent value from chars, starting at the start index and continuing through the end of the array.
      Parameters:
      chars - character array to parse a double exponent value from
      start - start index
      Returns:
      parsed exponent value

    • append

      private void append(char ch)
      Appends the given character to the output buffer.
      Parameters:
      ch - character to append

    • append

      private void append(char[] chars)
      Appends the given character array directly to the output buffer.
      Parameters:
      chars - characters to append

    • appendFraction

      private void appendFraction(int zeroCount, int startIdx, ParsedDecimal.FormatOptions opts)
      Appends the fractional component of the number to the current output buffer.
      Parameters:
      zeroCount - number of zeros to add after the decimal point and before the first significant digit
      startIdx - significant digit start index
      opts - format options

    • appendLocalizedDigit

      private void appendLocalizedDigit(int n, char[] digitChars)
      Appends the localized representation of the digit n to the output buffer.
      Parameters:
      n - digit to append
      digitChars - character array containing localized versions of the digits 0-9 in that order

    • appendWhole

      private int appendWhole(int wholeCount, ParsedDecimal.FormatOptions opts)
      Appends the whole number portion of this value to the output buffer. No thousands separators are added.
      Parameters:
      wholeCount - total number of digits required to the left of the decimal point
      opts - format options
      Returns:
      number of digits from digits appended to the output buffer
      See Also:

    • appendWholeGrouped

      private int appendWholeGrouped(int wholeCount, ParsedDecimal.FormatOptions opts)
      Appends the whole number portion of this value to the output buffer, adding thousands separators as needed.
      Parameters:
      wholeCount - total number of digits required to the right of the decimal point
      opts - format options
      Returns:
      number of digits from digits appended to the output buffer
      See Also:

    • getDigitStringSize

      private int getDigitStringSize(int decimalPos, ParsedDecimal.FormatOptions opts)
      Gets the number of characters required for the digit portion of a string representation of this value. This excludes any exponent or thousands groupings characters.
      Parameters:
      decimalPos - decimal point position relative to the digits array
      opts - format options
      Returns:
      number of characters required for the digit portion of a string representation of this value

    • getExponent

      public int getExponent()
      Gets the exponent value. This exponent produces a floating point value with the correct magnitude when applied to the internal unsigned integer.
      Returns:
      exponent value

    • getPlainStringSize

      private int getPlainStringSize(int decimalPos, ParsedDecimal.FormatOptions opts)
      Gets the number of characters required to create a plain format representation of this value.
      Parameters:
      decimalPos - decimal position relative to the digits array
      opts - format options
      Returns:
      number of characters in the plain string representation of this value, created using the given parameters

    • getScientificExponent

      public int getScientificExponent()
      Get sthe exponent that would be used when representing this number in scientific notation (i.e., with a single non-zero digit in front of the decimal point).
      Returns:
      the exponent that would be used when representing this number in scientific notation

    • isZero

      boolean isZero()
      Returns true if this value is equal to zero. The sign field is ignored, meaning that this method will return true for both +0 and -0.
      Returns:
      true if the value is equal to zero

    • maxPrecision

      public void maxPrecision(int precision)
      Ensures that this instance has at most the given number of significant digits (i.e. precision). If this instance already has a precision less than or equal to the argument, nothing is done. If the given precision requires a reduction in the number of digits, then the value is rounded using half-even rounding.
      Parameters:
      precision - maximum number of significant digits to include

    • outputString

      private String outputString()
      Gets the output buffer as a string.
      Returns:
      output buffer as a string

    • prepareOutput

      private void prepareOutput(int size)
      Prepares the output buffer for a string of the given size.
      Parameters:
      size - buffer size

    • requiresGroupingSeparatorAfterPosition

      private boolean requiresGroupingSeparatorAfterPosition(int pos)
      Returns true if a grouping separator should be added after the whole digit character at the given position.
      Parameters:
      pos - whole digit character position, with values starting at 1 and increasing from right to left.
      Returns:
      true if a grouping separator should be added

    • round

      public void round(int roundExponent)
      Rounds the instance to the given decimal exponent position using half-even rounding. For example, a value of -2 will round the instance to the digit at the position 10-2 (i.e. to the closest multiple of 0.01).
      Parameters:
      roundExponent - exponent defining the decimal place to round to

    • roundUp

      private void roundUp(int count)
      Rounds the value up to the given number of digits.
      Parameters:
      count - target number of digits; must be greater than zero and less than the current number of digits

    • setSingleDigitValue

      private void setSingleDigitValue(int digit, int newExponent)
      Sets the value of this instance to a single digit with the given exponent. The sign of the value is retained.
      Parameters:
      digit - digit value
      newExponent - new exponent value

    • shouldIncludeExponent

      private boolean shouldIncludeExponent(int targetExponent, ParsedDecimal.FormatOptions opts)
      Returns true if a formatted string with the given target exponent should include the exponent field.
      Parameters:
      targetExponent - exponent of the formatted result
      opts - format options
      Returns:
      true if the formatted string should include the exponent field

    • shouldIncludeMinus

      private boolean shouldIncludeMinus(ParsedDecimal.FormatOptions opts)
      Returns true if formatted strings should include the minus sign, considering the value of this instance and the given format options.
      Parameters:
      opts - format options
      Returns:
      true if a minus sign should be included in the output

    • shouldRoundUp

      private boolean shouldRoundUp(int count)
      Returns true if a rounding operation for the given number of digits should round up.
      Parameters:
      count - number of digits to round to; must be greater than zero and less than the current number of digits
      Returns:
      true if a rounding operation for the given number of digits should round up

    • toEngineeringString

      public String toEngineeringString(ParsedDecimal.FormatOptions opts)
      Returns a string representation of this value in engineering notation. This is similar to scientific notation but with the exponent forced to be a multiple of 3, allowing easier alignment with SI prefixes. 
       0 = "0.0"
 10 = "10.0"
 1e-6 = "1.0E-6"
 1e11 = "100.0E9"
      Parameters:
      opts - format options
      Returns:
      value in engineering format

    • toPlainString

      public String toPlainString(ParsedDecimal.FormatOptions opts)
      Returns a string representation of this value with no exponent field. Ex: 
       10 = "10.0"
 1e-6 = "0.000001"
 1e11 = "100000000000.0"
      Parameters:
      opts - format options
      Returns:
      value in plain format

    • toScientificString

      public String toScientificString(ParsedDecimal.FormatOptions opts)
      Returns a string representation of this value in scientific notation. Ex: 
       0 = "0.0"
 10 = "1.0E1"
 1e-6 = "1.0E-6"
 1e11 = "1.0E11"
      Parameters:
      opts - format options
      Returns:
      value in scientific format

    • toScientificString

      private String toScientificString(int decimalPos, ParsedDecimal.FormatOptions opts)
      Returns a string representation of the value in scientific notation using the given decimal point position.
      Parameters:
      decimalPos - decimal position relative to the digits array; this value is expected to be greater than 0
      opts - format options
      Returns:
      value in scientific format

    • truncate

      private void truncate(int count)
      Truncates the value to the given number of digits.
      Parameters:
      count - number of digits; must be greater than zero and less than the current number of digits