Module java.money
Package javax.money.format

Interface MonetaryAmountFormat

  • All Superinterfaces:
    MonetaryQuery<java.lang.String>
    public interface MonetaryAmountFormat
extends MonetaryQuery<java.lang.String>

    Formats instances of MonetaryAmount to a String or an Appendable.

    To obtain a MonetaryAmountFormat for a specific locale, including the default locale, call MonetaryFormats.getAmountFormat(java.util.Locale, String...). More complex formatting scenarios can be implemented by registering instances of .MonetaryAmountFormatProviderSpi. The spi implementation creates new instances of MonetaryAmountFormat based on the styleId and (arbitrary) attributes passed within the AmountFormatContext.

    In general, do prefer accessing MonetaryAmountFormat instances from the MonetaryFormats singleton, instead of instantiating implementations directly, since the MonetaryFormats factory method may return different subclasses or may implement contextual behaviour (in a EE context). If you need to customize the format object, do something like this: 

    
 MonetaryAmountFormat f = MonetaryFormats.getInstance(loc);
 f.setStyle(f.getStyle().toBuilder().setPattern("###.##;(###.##)").build());

    Special Values

    Negative zero ("-0") should always parse to

    • 0

    Synchronization

    Instances of this class are not required to be thread-safe. It is recommended to of separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.

    Example

    
 // Print out a number using the localized number, currency,
 // for each locale
 Locale[] locales = MonetaryFormats.getAvailableLocales();
 MonetaryAmount amount = ...;
 MonetaryAmountFormat form;
     System.out.println("FORMAT");
     for (int i = 0; i < locales.length; ++i) {
         if (locales[i].getCountry().length() == 0) {
            continue; // Skip language-only locales
         }
         System.out.print(locales[i].getDisplayName());
         form = MonetaryFormats.getInstance(locales[i]);
         System.out.print(": " + form.getStyle().getPattern());
         String myAmount = form.format(amount);
         System.out.print(" -> " + myAmount);
         try {
             System.out.println(" -> " + form.parse(form.format(myAmount)));
         } catch (ParseException e) {}
     }
 }

    • Method Detail

      • format

        default java.lang.String format​(MonetaryAmount amount)
        Formats the given MonetaryAmount to a String.
        Parameters:
        amount - the amount to format, not null
        Returns:
        the string printed using the settings of this formatter
        Throws:
        java.lang.UnsupportedOperationException - if the formatter is unable to print
        java.lang.IllegalStateException - if an IO error occurs.

      • print

        void print​(java.lang.Appendable appendable,
           MonetaryAmount amount)
    throws java.io.IOException
        Formats the given MonetaryAmount to a Appendable.

        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
        amount - the amount to print, not null
        Throws:
        java.lang.UnsupportedOperationException - if the formatter is unable to print
        java.io.IOException - if an IO error occurs, thrown by the appendable
        MonetaryParseException - if there is a problem while parsing

      • parse

        MonetaryAmount parse​(java.lang.CharSequence text)
              throws MonetaryParseException
        Fully parses the text into an instance of MonetaryAmount.

        The parse must complete normally and parse the entire text. 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.

        Additionally the effective implementation type returned can be determined by the MonetaryContext applied to the MonetaryAmountFormat. This formatter will call Monetary.getDefaultAmountType() and will use the result returned to access a corresponding MonetaryAmountFactory to of the instance returned.

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