Class MoneyFormatter

  • All Implemented Interfaces:
    java.io.Serializable

    public final class MoneyFormatter
    extends java.lang.Object
    implements java.io.Serializable
    Formats instances of money to and from a String.

    Instances of MoneyFormatter can be created by MoneyFormatterBuilder.

    This class is immutable and thread-safe.

    See Also:
    Serialized Form
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) static void checkNotNull​(java.lang.Object object, java.lang.String message)
      Validates that the object specified is not null
      java.util.Locale getLocale()
      Gets the locale to use.
      (package private) MultiPrinterParser getPrinterParser()
      Gets the printer/parser.
      boolean isParser()
      Checks whether this formatter can parse.
      boolean isPrinter()
      Checks whether this formatter can print.
      MoneyParseContext parse​(java.lang.CharSequence text, int startIndex)
      Parses the text extracting monetary information.
      BigMoney parseBigMoney​(java.lang.CharSequence text)
      Fully parses the text into a BigMoney.
      Money parseMoney​(java.lang.CharSequence text)
      Fully parses the text into a Money requiring that the parsed amount has the correct number of decimal places.
      void print​(java.lang.Appendable appendable, BigMoneyProvider moneyProvider)
      Prints a monetary value to an Appendable converting any IOException to a MoneyFormatException.
      java.lang.String print​(BigMoneyProvider moneyProvider)
      Prints a monetary value to a String.
      void printIO​(java.lang.Appendable appendable, BigMoneyProvider moneyProvider)
      Prints a monetary value to an Appendable potentially throwing an IOException.
      java.lang.String toString()
      Gets a string summary of the formatter.
      MoneyFormatter withLocale​(java.util.Locale locale)
      Returns a copy of this instance with the specified locale.
      • Methods inherited from class java.lang.Object

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

      • serialVersionUID

        private static final long serialVersionUID
        Serialization version.
        See Also:
        Constant Field Values
      • locale

        private final java.util.Locale locale
        The locale to use.
    • Constructor Detail

      • MoneyFormatter

        MoneyFormatter​(java.util.Locale locale,
                       MoneyPrinter[] printers,
                       MoneyParser[] parsers)
        Constructor, creating a new formatter.
        Parameters:
        locale - the locale to use, not null
        printers - the printers, not null
        parsers - the parsers, not null
      • MoneyFormatter

        private MoneyFormatter​(java.util.Locale locale,
                               MultiPrinterParser printerParser)
        Constructor, creating a new formatter.
        Parameters:
        locale - the locale to use, not null
        printerParser - the printer/parser, not null
    • Method Detail

      • checkNotNull

        static void checkNotNull​(java.lang.Object object,
                                 java.lang.String message)
        Validates that the object specified is not null
        Parameters:
        object - the object to check, null throws exception
        message - the message to use in the exception, not null
        Throws:
        java.lang.NullPointerException - if the input value is null
      • getPrinterParser

        MultiPrinterParser getPrinterParser()
        Gets the printer/parser.
        Returns:
        the printer/parser, never null
      • getLocale

        public java.util.Locale getLocale()
        Gets the locale to use.
        Returns:
        the locale, never null
      • withLocale

        public MoneyFormatter withLocale​(java.util.Locale locale)
        Returns a copy of this instance with the specified locale.

        Changing the locale may change the style of output depending on how the formatter has been configured.

        Parameters:
        locale - the locale, not null
        Returns:
        the new instance, never null
      • isPrinter

        public boolean isPrinter()
        Checks whether this formatter can print.

        If the formatter cannot print, an UnsupportedOperationException will be thrown from the print methods.

        Returns:
        true if the formatter can print
      • isParser

        public boolean isParser()
        Checks whether this formatter can parse.

        If the formatter cannot parse, an UnsupportedOperationException will be thrown from the parse methods.

        Returns:
        true if the formatter can parse
      • print

        public java.lang.String print​(BigMoneyProvider moneyProvider)
        Prints a monetary value to a String.
        Parameters:
        moneyProvider - the money to print, not null
        Returns:
        the string printed using the settings of this formatter
        Throws:
        java.lang.UnsupportedOperationException - if the formatter is unable to print
        MoneyFormatException - if there is a problem while printing
      • print

        public void print​(java.lang.Appendable appendable,
                          BigMoneyProvider moneyProvider)
        Prints a monetary value to an Appendable converting any IOException to a MoneyFormatException.

        Example implementations of Appendable are StringBuilder, StringBuffer or Writer. Note that StringBuilder and StringBuffer never throw an IOException.

        Parameters:
        appendable - the appendable to add to, not null
        moneyProvider - the money to print, not null
        Throws:
        java.lang.UnsupportedOperationException - if the formatter is unable to print
        MoneyFormatException - if there is a problem while printing
      • printIO

        public void printIO​(java.lang.Appendable appendable,
                            BigMoneyProvider moneyProvider)
                     throws java.io.IOException
        Prints a monetary value to an Appendable potentially throwing an IOException.

        Example implementations of Appendable are StringBuilder, StringBuffer or Writer. Note that StringBuilder and StringBuffer never throw an IOException.

        Parameters:
        appendable - the appendable to add to, not null
        moneyProvider - the money to print, not null
        Throws:
        java.lang.UnsupportedOperationException - if the formatter is unable to print
        MoneyFormatException - if there is a problem while printing
        java.io.IOException - if an IO error occurs
      • parseBigMoney

        public BigMoney parseBigMoney​(java.lang.CharSequence text)
        Fully parses the text into a BigMoney.

        The parse must complete normally and parse the entire text (currency and amount). If the parse completes without reading the entire length of the text, an exception is thrown. If any other problem occurs during parsing, an exception is thrown.

        Parameters:
        text - the text to parse, not null
        Returns:
        the parsed monetary value, never null
        Throws:
        java.lang.UnsupportedOperationException - if the formatter is unable to parse
        MoneyFormatException - if there is a problem while parsing
      • parseMoney

        public Money parseMoney​(java.lang.CharSequence text)
        Fully parses the text into a Money requiring that the parsed amount has the correct number of decimal places.

        The parse must complete normally and parse the entire text (currency and amount). If the parse completes without reading the entire length of the text, an exception is thrown. If any other problem occurs during parsing, an exception is thrown.

        Parameters:
        text - the text to parse, not null
        Returns:
        the parsed monetary value, never null
        Throws:
        java.lang.UnsupportedOperationException - if the formatter is unable to parse
        MoneyFormatException - if there is a problem while parsing
        java.lang.ArithmeticException - if the scale of the parsed money exceeds the scale of the currency
      • parse

        public MoneyParseContext parse​(java.lang.CharSequence text,
                                       int startIndex)
        Parses the text extracting monetary information.

        This method parses the input providing low-level access to the parsing state. The resulting context contains the parsed text, indicator of error, position following the parse and the parsed currency and amount. Together, these provide enough information for higher level APIs to use.

        Parameters:
        text - the text to parse, not null
        startIndex - the start index to parse from
        Returns:
        the parsed monetary value, null only if the parse results in an error
        Throws:
        java.lang.IndexOutOfBoundsException - if the start index is invalid
        java.lang.UnsupportedOperationException - if this formatter cannot parse
      • toString

        public java.lang.String toString()
        Gets a string summary of the formatter.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string summarising the formatter, never null