Module org.joda.money
Package org.joda.money.format

Class MoneyFormatterBuilder

java.lang.Object
org.joda.money.format.MoneyFormatterBuilder
public final class MoneyFormatterBuilder extends Object
Provides the ability to build a formatter for monetary values.

This class is mutable and intended for use by a single thread. A new instance should be created for each use. The formatters produced by the builder are immutable and thread-safe.

  • Constructor Details

    • MoneyFormatterBuilder

      public MoneyFormatterBuilder()
      Constructor, creating a new empty builder.

  • Method Details

    • appendAmount

      public MoneyFormatterBuilder appendAmount()
      Appends the amount to the builder using a standard format.

      The format used is MoneyAmountStyle.ASCII_DECIMAL_POINT_GROUP3_COMMA. The amount is the value itself, such as '12.34'.

      Returns:
      this, for chaining, never null

    • appendAmountLocalized

      public MoneyFormatterBuilder appendAmountLocalized()
      Appends the amount to the builder using a grouped localized format.

      The format used is MoneyAmountStyle.LOCALIZED_GROUPING. The amount is the value itself, such as '12.34'.

      Returns:
      this, for chaining, never null

    • appendAmount

      public MoneyFormatterBuilder appendAmount(MoneyAmountStyle style)
      Appends the amount to the builder using the specified amount style.

      The amount is the value itself, such as '12.34'.

      The amount style allows the formatting of the number to be controlled in detail. This includes the characters for positive, negative, decimal, grouping and whether to output the absolute or signed amount. See MoneyAmountStyle for more details.

      Parameters:
      style - the style to use, not null
      Returns:
      this, for chaining, never null

    • appendCurrencyCode

      public MoneyFormatterBuilder appendCurrencyCode()
      Appends the currency code to the builder.

      The currency code is the three letter ISO code, such as 'GBP'.

      Returns:
      this, for chaining, never null

    • appendCurrencyNumeric3Code

      public MoneyFormatterBuilder appendCurrencyNumeric3Code()
      Appends the currency code to the builder.

      The numeric code is the ISO numeric code, such as '826' and is zero padded to three digits.

      Returns:
      this, for chaining, never null

    • appendCurrencyNumericCode

      public MoneyFormatterBuilder appendCurrencyNumericCode()
      Appends the currency code to the builder.

      The numeric code is the ISO numeric code, such as '826'.

      Returns:
      this, for chaining, never null

    • appendCurrencySymbolLocalized

      public MoneyFormatterBuilder appendCurrencySymbolLocalized()
      Appends the localized currency symbol to the builder.

      The localized currency symbol is the symbol as chosen by the locale of the formatter.

      Symbols cannot be parsed.

      Returns:
      this, for chaining, never null

    • appendLiteral

      public MoneyFormatterBuilder appendLiteral(CharSequence literal)
      Appends a literal to the builder.

      The localized currency symbol is the symbol as chosen by the locale of the formatter.

      Parameters:
      literal - the literal to append, null or empty ignored
      Returns:
      this, for chaining, never null

    • append

      public MoneyFormatterBuilder append(MoneyFormatter formatter)
      Appends the printers and parsers from the specified formatter to this builder.

      If the specified formatter cannot print, then the the output of this builder will be unable to print. If the specified formatter cannot parse, then the output of this builder will be unable to parse.

      Parameters:
      formatter - the formatter to append, not null
      Returns:
      this for chaining, never null

    • append

      public MoneyFormatterBuilder append(MoneyPrinter printer, MoneyParser parser)
      Appends the specified printer and parser to this builder.

      If null is specified then the formatter will be unable to print/parse.

      Parameters:
      printer - the printer to append, null makes the formatter unable to print
      parser - the parser to append, null makes the formatter unable to parse
      Returns:
      this for chaining, never null

    • appendSigned

      public MoneyFormatterBuilder appendSigned(MoneyFormatter whenPositiveOrZero, MoneyFormatter whenNegative)
      Appends the specified formatters, one used when the amount is positive, and one when the amount is negative.

      When printing, the amount is queried and the appropriate formatter is used.

      When parsing, each formatter is tried, with the longest successful match, or the first match if multiple are successful. If the negative parser is matched, the amount returned will be negative no matter what amount is parsed.

      A typical use case for this would be to produce a format like '($123)' for negative amounts and '$123' for positive amounts.

      In order to use this method, it may be necessary to output an unsigned amount. This can be achieved using appendAmount(MoneyAmountStyle) and MoneyAmountStyle.withAbsValue(boolean).

      Parameters:
      whenPositiveOrZero - the formatter to use when the amount is positive or zero
      whenNegative - the formatter to use when the amount is negative
      Returns:
      this for chaining, never null

    • appendSigned

      public MoneyFormatterBuilder appendSigned(MoneyFormatter whenPositive, MoneyFormatter whenZero, MoneyFormatter whenNegative)
      Appends the specified formatters, one used when the amount is positive, one when the amount is zero and one when the amount is negative.

      When printing, the amount is queried and the appropriate formatter is used.

      When parsing, each formatter is tried, with the longest successful match, or the first match if multiple are successful. If the zero parser is matched, the amount returned will be zero no matter what amount is parsed. If the negative parser is matched, the amount returned will be negative no matter what amount is parsed.

      A typical use case for this would be to produce a format like '($123)' for negative amounts and '$123' for positive amounts.

      In order to use this method, it may be necessary to output an unsigned amount. This can be achieved using appendAmount(MoneyAmountStyle) and MoneyAmountStyle.withAbsValue(boolean).

      Parameters:
      whenPositive - the formatter to use when the amount is positive
      whenZero - the formatter to use when the amount is zero
      whenNegative - the formatter to use when the amount is negative
      Returns:
      this for chaining, never null

    • toFormatter

      public MoneyFormatter toFormatter()
      Builds the formatter from the builder using the default locale.

      Once the builder is in the correct state it must be converted to a MoneyFormatter to be used. Calling this method does not change the state of this instance, so it can still be used.

      This method uses the default locale within the returned formatter. It can be changed by calling MoneyFormatter.withLocale(Locale).

      Returns:
      the formatter built from this builder, never null

    • toFormatter

      public MoneyFormatter toFormatter(Locale locale)
      Builds the formatter from the builder setting the locale.

      Once the builder is in the correct state it must be converted to a MoneyFormatter to be used. Calling this method does not change the state of this instance, so it can still be used.

      This method uses the specified locale within the returned formatter. It can be changed by calling MoneyFormatter.withLocale(Locale).

      Parameters:
      locale - the initial locale for the formatter, not null
      Returns:
      the formatter built from this builder, never null