org.bitcoinj.utils

Class MonetaryFormat

java.lang.Object

org.bitcoinj.utils.MonetaryFormat

public final class MonetaryFormat
extends 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 and Description
static MonetaryFormat	BTC Standard format for the BTC denomination.
static String	CODE_BTC Currency code for base 1 Bitcoin.
static String	CODE_MBTC Currency code for base 1/1000 Bitcoin.
static 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	UBTC Standard format for the µBTC denomination.

Constructor Summary

Constructors

Constructor and Description
MonetaryFormat()

Method Summary

Modifier and Type	Method and Description
String	code() Get currency code that will be used for current shift.
MonetaryFormat	code(int codeShift, 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.
CharSequence	format(Monetary monetary) Format the given monetary value to a human readable form.
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(String str) Parse a human readable coin value to a Coin instance.
Fiat	parseFiat(String currencyCode, 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(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(Locale locale) Configure this instance with values from a Locale.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, 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.

FIAT

public static final MonetaryFormat FIAT

Standard format for fiat amounts.

CODE_BTC

public static final String CODE_BTC

Currency code for base 1 Bitcoin.

See Also:

Constant Field Values

CODE_MBTC

public static final String CODE_MBTC

Currency code for base 1/1000 Bitcoin.

See Also:

Constant Field Values

CODE_UBTC

public static final String CODE_UBTC

Currency code for base 1/1000000 Bitcoin.

See Also:

Constant Field Values

MAX_DECIMALS

public static final int MAX_DECIMALS

See Also:

Constant Field Values

Constructor Detail

MonetaryFormat

public MonetaryFormat()

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(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,
                           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(Locale locale)

Configure this instance with values from a Locale.

format

public CharSequence format(Monetary monetary)

Format the given monetary value to a human readable form.

parse

public Coin parse(String str)
           throws NumberFormatException

Parse a human readable coin value to a Coin instance.

Throws:

NumberFormatException - if the string cannot be parsed for some reason

parseFiat

public Fiat parseFiat(String currencyCode,
                      String str)
               throws NumberFormatException

Parse a human readable fiat value to a Fiat instance.

Throws:

NumberFormatException - if the string cannot be parsed for some reason

code

public String code()

Get currency code that will be used for current shift.