Class NumberFormatter


  • public final class NumberFormatter
    extends java.lang.Object
    Provides the ability to parse and format numbers.

    This exists as an alternative to NumberFormat and DecimalFormat which are not thread-safe.

    Instances of this class are immutable and thread-safe.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String format​(double number)
      Formats a double using this formatter.
      java.lang.String format​(long number)
      Formats a long using this formatter.
      static NumberFormatter of​(boolean grouped, int decimalPlaces)
      Obtains a standard formatter configured by grouping and decimal places.
      static NumberFormatter of​(boolean grouped, int minDecimalPlaces, int maxDecimalPlaces)
      Obtains a standard formatter configured by grouping and decimal places.
      static NumberFormatter ofLocalizedNumber​(java.util.Locale locale)
      Obtains a number formatter for general-purpose use in the specified locale.
      static NumberFormatter ofPattern​(java.lang.String pattern, java.util.Locale locale)
      Obtains a formatter based on a pattern in the specified locale.
      static NumberFormatter ofPercentage​(boolean grouped, int minDecimalPlaces, int maxDecimalPlaces)
      Obtains a formatter for decimal percentages configured by grouping and decimal places.
      double parse​(java.lang.String text)
      Parses the specific string, returning a double.
      java.lang.String toString()
      Returns a string representation of this formatter.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Method Detail

      • of

        public static NumberFormatter of​(boolean grouped,
                                         int decimalPlaces)
        Obtains a standard formatter configured by grouping and decimal places.

        The formatter will have the specified number of decimal places. The integer part will be grouped if the flag is set. The decimal part will never be grouped or truncated. The implementation uses English locale data, which uses commas as a separator and a decimal point (dot). Numbers will be rounded using RoundingMode.HALF_EVEN

        Parameters:
        grouped - true to group, false to not group
        decimalPlaces - the minimum number of decimal places, from 0 to 9
        Returns:
        the formatter
        Throws:
        java.lang.IllegalArgumentException - if the decimal places is invalid
      • of

        public static NumberFormatter of​(boolean grouped,
                                         int minDecimalPlaces,
                                         int maxDecimalPlaces)
        Obtains a standard formatter configured by grouping and decimal places.

        The formatter will have the specified number of decimal places. The integer part will be grouped if the flag is set. The decimal part will never be grouped or truncated. The implementation uses English locale data, which uses commas as a separator and a decimal point (dot). Numbers will be rounded using RoundingMode.HALF_EVEN

        Parameters:
        grouped - true to group, false to not group
        minDecimalPlaces - the minimum number of decimal places, from 0 to 9
        maxDecimalPlaces - the minimum number of decimal places, from 0 to 9
        Returns:
        the formatter
        Throws:
        java.lang.IllegalArgumentException - if the decimal places is invalid
      • ofPercentage

        public static NumberFormatter ofPercentage​(boolean grouped,
                                                   int minDecimalPlaces,
                                                   int maxDecimalPlaces)
        Obtains a formatter for decimal percentages configured by grouping and decimal places.

        The formatter will have the specified number of decimal places. The integer part will be grouped if the flag is set. The decimal part will never be grouped or truncated. The implementation uses English locale data, which uses commas as a separator and a decimal point (dot). The formatter will suffix the output with '%'. Numbers will be rounded using RoundingMode.HALF_EVEN

        The number passed in must be the decimal representation of the percentage. It will be multiplied by 100 before formatting.

        Parameters:
        grouped - true to group, false to not group
        minDecimalPlaces - the minimum number of decimal places, from 0 to 9
        maxDecimalPlaces - the minimum number of decimal places, from 0 to 9
        Returns:
        the formatter
        Throws:
        java.lang.IllegalArgumentException - if the decimal places is invalid
      • ofPattern

        public static NumberFormatter ofPattern​(java.lang.String pattern,
                                                java.util.Locale locale)
        Obtains a formatter based on a pattern in the specified locale.
        Parameters:
        pattern - the pattern string to use
        locale - the locale to use
        Returns:
        the formatter
        Throws:
        java.lang.IllegalArgumentException - if the pattern is invalid
        See Also:
        DecimalFormat
      • ofLocalizedNumber

        public static NumberFormatter ofLocalizedNumber​(java.util.Locale locale)
        Obtains a number formatter for general-purpose use in the specified locale.
        Parameters:
        locale - the locale to use
        Returns:
        the formatter
        See Also:
        NumberFormat.getNumberInstance(Locale)
      • format

        public java.lang.String format​(double number)
        Formats a double using this formatter.
        Parameters:
        number - the number to format
        Returns:
        the formatted string
      • format

        public java.lang.String format​(long number)
        Formats a long using this formatter.
        Parameters:
        number - the number to format
        Returns:
        the formatted string
      • parse

        public double parse​(java.lang.String text)
        Parses the specific string, returning a double.
        Parameters:
        text - the string to parse
        Returns:
        the parsed number
        Throws:
        java.lang.IllegalArgumentException - if the text cannot be parsed
      • toString

        public java.lang.String toString()
        Returns a string representation of this formatter.
        Overrides:
        toString in class java.lang.Object
        Returns:
        the string