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 Details

    • getContext

      AmountFormatContext getContext()
      The AmountFormatContext to be applied when a MonetaryAmount is formatted.
      Returns:
      the AmountFormatContext used, never null.

    • 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