Package org.bitcoinj.utils

Class MonetaryFormat

  • public final class MonetaryFormat
extends java.lang.Object

    Utility for formatting and parsing coin values to and from human readable form.

    MonetaryFormat instances are immutable. Invoking a configuration method has no effect on the receiving instance; you must store and use the new instance it returns, instead. Instances are thread safe, so they may be stored safely as static constants.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static MonetaryFormat BTC
      Standard format for the BTC denomination.
      static java.lang.String CODE_BTC
      Currency code for base 1 Bitcoin.
      static java.lang.String CODE_MBTC
      Currency code for base 1/1000 Bitcoin.
      static java.lang.String CODE_SAT
      Currency code for base 1 satoshi.
      static java.lang.String CODE_UBTC
      Currency code for base 1/1000000 Bitcoin.
      static MonetaryFormat FIAT
      Standard format for fiat amounts.
      static int MAX_DECIMALS  
      static MonetaryFormat MBTC
      Standard format for the mBTC denomination.
      static MonetaryFormat SAT
      Standard format for the satoshi denomination.
      static java.lang.String SYMBOL_BTC
      Currency symbol for base 1 Bitcoin.
      static java.lang.String SYMBOL_MBTC
      Currency symbol for base 1/1000 Bitcoin.
      static java.lang.String SYMBOL_SAT
      Currency symbol for base 1 satoshi.
      static java.lang.String SYMBOL_UBTC
      Currency symbol for base 1/1000000 Bitcoin.
      static MonetaryFormat UBTC
      Standard format for the µBTC denomination.

    • Constructor Summary

      Constructors 
      Constructor Description
      MonetaryFormat()
      Construct a MonetaryFormat with the default configuration.
      MonetaryFormat​(boolean useSymbol)
      Construct a MonetaryFormat with the default configuration.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String code()
      Get currency code that will be used for current shift.
      MonetaryFormat code​(int codeShift, java.lang.String code)
      Configure currency code for given decimal separator shift.
      MonetaryFormat codeSeparator​(char codeSeparator)
      Separator between currency code and formatted value.
      MonetaryFormat decimalMark​(char decimalMark)
      Set character to use as the decimal mark.
      MonetaryFormat digits​(char zeroDigit)
      Set character range to use for representing digits.
      boolean equals​(java.lang.Object o)
      Two formats are equal if they have the same parameters.
      java.lang.CharSequence format​(Monetary monetary)
      Format the given monetary value to a human readable form.
      int hashCode()  
      MonetaryFormat minDecimals​(int minDecimals)
      Set minimum number of decimals to use for formatting.
      MonetaryFormat negativeSign​(char negativeSign)
      Set character to prefix negative values.
      MonetaryFormat noCode()
      Don't display currency code when formatting.
      MonetaryFormat optionalDecimals​(int... groups)
      Set additional groups of decimals to use after the minimum decimals, if they are useful for expressing precision.
      Coin parse​(java.lang.String str)
      Parse a human readable coin value to a Coin instance.
      Fiat parseFiat​(java.lang.String currencyCode, java.lang.String str)
      Parse a human readable fiat value to a Fiat instance.
      MonetaryFormat positiveSign​(char positiveSign)
      Set character to prefix positive values.
      MonetaryFormat postfixCode()
      Postfix formatted output with currency code.
      MonetaryFormat prefixCode()
      Prefix formatted output by currency code.
      MonetaryFormat repeatOptionalDecimals​(int decimals, int repetitions)
      Set repeated additional groups of decimals to use after the minimum decimals, if they are useful for expressing precision.
      MonetaryFormat roundingMode​(java.math.RoundingMode roundingMode)
      Set rounding mode to use when it becomes necessary.
      MonetaryFormat shift​(int shift)
      Set number of digits to shift the decimal separator to the right, coming from the standard BTC notation that was common pre-2014.
      MonetaryFormat withLocale​(java.util.Locale locale)
      Configure this instance with values from a Locale.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • BTC

        public static final MonetaryFormat BTC
        Standard format for the BTC denomination.

      • MBTC

        public static final MonetaryFormat MBTC
        Standard format for the mBTC denomination.

      • UBTC

        public static final MonetaryFormat UBTC
        Standard format for the µBTC denomination.

      • SAT

        public static final MonetaryFormat SAT
        Standard format for the satoshi denomination.

      • FIAT

        public static final MonetaryFormat FIAT
        Standard format for fiat amounts.

      • CODE_BTC

        public static final java.lang.String CODE_BTC
        Currency code for base 1 Bitcoin.
        See Also:
        Constant Field Values

      • CODE_MBTC

        public static final java.lang.String CODE_MBTC
        Currency code for base 1/1000 Bitcoin.
        See Also:
        Constant Field Values

      • CODE_UBTC

        public static final java.lang.String CODE_UBTC
        Currency code for base 1/1000000 Bitcoin.
        See Also:
        Constant Field Values

      • CODE_SAT

        public static final java.lang.String CODE_SAT
        Currency code for base 1 satoshi.
        See Also:
        Constant Field Values

      • SYMBOL_BTC

        public static final java.lang.String SYMBOL_BTC
        Currency symbol for base 1 Bitcoin.
        See Also:
        Constant Field Values

      • SYMBOL_MBTC

        public static final java.lang.String SYMBOL_MBTC
        Currency symbol for base 1/1000 Bitcoin.
        See Also:
        Constant Field Values

      • SYMBOL_UBTC

        public static final java.lang.String SYMBOL_UBTC
        Currency symbol for base 1/1000000 Bitcoin.
        See Also:
        Constant Field Values

      • SYMBOL_SAT

        public static final java.lang.String SYMBOL_SAT
        Currency symbol for base 1 satoshi.
        See Also:
        Constant Field Values

    • Constructor Detail

      • MonetaryFormat

        public MonetaryFormat()
        Construct a MonetaryFormat with the default configuration.

      • MonetaryFormat

        public MonetaryFormat​(boolean useSymbol)
        Construct a MonetaryFormat with the default configuration.
        Parameters:
        useSymbol - use unicode symbols instead of the BTC and sat codes

    • Method Detail

      • negativeSign

        public MonetaryFormat negativeSign​(char negativeSign)
        Set character to prefix negative values.

      • positiveSign

        public MonetaryFormat positiveSign​(char positiveSign)
        Set character to prefix positive values. A zero value means no sign is used in this case. For parsing, a missing sign will always be interpreted as if the positive sign was used.

      • digits

        public MonetaryFormat digits​(char zeroDigit)
        Set character range to use for representing digits. It starts with the specified character representing zero.

      • decimalMark

        public MonetaryFormat decimalMark​(char decimalMark)
        Set character to use as the decimal mark. If the formatted value does not have any decimals, no decimal mark is used either.

      • minDecimals

        public MonetaryFormat minDecimals​(int minDecimals)
        Set minimum number of decimals to use for formatting. If the value precision exceeds all decimals specified (including additional decimals specified by optionalDecimals(int...) or repeatOptionalDecimals(int, int)), the value will be rounded. This configuration is not relevant for parsing.

      • optionalDecimals

        public MonetaryFormat optionalDecimals​(int... groups)

        Set additional groups of decimals to use after the minimum decimals, if they are useful for expressing precision. Each value is a number of decimals in that group. If the value precision exceeds all decimals specified (including minimum decimals), the value will be rounded. This configuration is not relevant for parsing.

        For example, if you pass 4,2 it will add four decimals to your formatted string if needed, and then add another two decimals if needed. At this point, rather than adding further decimals the value will be rounded.

        Parameters:
        groups - any number numbers of decimals, one for each group

      • repeatOptionalDecimals

        public MonetaryFormat repeatOptionalDecimals​(int decimals,
                                             int repetitions)

        Set repeated additional groups of decimals to use after the minimum decimals, if they are useful for expressing precision. If the value precision exceeds all decimals specified (including minimum decimals), the value will be rounded. This configuration is not relevant for parsing.

        For example, if you pass 1,8 it will up to eight decimals to your formatted string if needed. After these have been used up, rather than adding further decimals the value will be rounded.

        Parameters:
        decimals - value of the group to be repeated
        repetitions - number of repetitions

      • shift

        public MonetaryFormat shift​(int shift)
        Set number of digits to shift the decimal separator to the right, coming from the standard BTC notation that was common pre-2014. Note this will change the currency code if enabled.

      • roundingMode

        public MonetaryFormat roundingMode​(java.math.RoundingMode roundingMode)
        Set rounding mode to use when it becomes necessary.

      • noCode

        public MonetaryFormat noCode()
        Don't display currency code when formatting. This configuration is not relevant for parsing.

      • code

        public MonetaryFormat code​(int codeShift,
                           java.lang.String code)
        Configure currency code for given decimal separator shift. This configuration is not relevant for parsing.
        Parameters:
        codeShift - decimal separator shift, see shift
        code - currency code

      • codeSeparator

        public MonetaryFormat codeSeparator​(char codeSeparator)
        Separator between currency code and formatted value. This configuration is not relevant for parsing.

      • prefixCode

        public MonetaryFormat prefixCode()
        Prefix formatted output by currency code. This configuration is not relevant for parsing.

      • postfixCode

        public MonetaryFormat postfixCode()
        Postfix formatted output with currency code. This configuration is not relevant for parsing.

      • withLocale

        public MonetaryFormat withLocale​(java.util.Locale locale)
        Configure this instance with values from a Locale.

      • format

        public java.lang.CharSequence format​(Monetary monetary)
        Format the given monetary value to a human readable form.

      • parse

        public Coin parse​(java.lang.String str)
           throws java.lang.NumberFormatException
        Parse a human readable coin value to a Coin instance.
        Throws:
        java.lang.NumberFormatException - if the string cannot be parsed for some reason

      • parseFiat

        public Fiat parseFiat​(java.lang.String currencyCode,
                      java.lang.String str)
               throws java.lang.NumberFormatException
        Parse a human readable fiat value to a Fiat instance.
        Throws:
        java.lang.NumberFormatException - if the string cannot be parsed for some reason

      • code

        public java.lang.String code()
        Get currency code that will be used for current shift.

      • equals

        public boolean equals​(java.lang.Object o)
        Two formats are equal if they have the same parameters.
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object