org.bitcoinj.utils

Class BtcFormat

java.lang.Object

java.text.Format

org.bitcoinj.utils.BtcFormat

All Implemented Interfaces:

Serializable, Cloneable

Direct Known Subclasses:

BtcAutoFormat, BtcFixedFormat

public abstract class BtcFormat
extends Format

Instances of this class format and parse locale-specific numerical representations of Bitcoin monetary values.

A primary goal of this class is to minimize the danger of human-misreading of monetary values due to mis-counting the number of zeros (or, more generally, of decimal places) in the number that represents a Bitcoin monetary value. Some of the features offered for doing this are:

1. automatic adjustment of denominational units in which a value is represented so as to lessen the number of adjacent zeros,
2. use of locale-specific decimal-separators to group digits in the integer portion of formatted numbers,
3. fine control over the number and grouping of fractional decimal places, and
4. access to character information that allows for vertical alignment of tabular columns of formatted values.

Basic Usage

Basic usage is very simple:

1. Construct a new formatter object using one of the factory methods.
2. Format a value by passing it as an argument to the Format.format(Object) method.
3. Parse a value by passing a String-type representation of it to the parse(String) method.

For example, depending on your locale, values might be formatted and parsed as follows:

 BtcFormat f = BtcFormat.getInstance();
 String c = f.format(Coin.COIN);                // "BTC 1.00"
 String k = f.format(Coin.COIN.multiply(1000)); // "BTC 1,000.00"
 String m = f.format(Coin.COIN.divide(1000));   // "mBTC 1.00"
 Coin all = f.parseObject("M฿ 21");             // All the money in the world
 

Auto-Denomination versus Fixed-Denomination

There are two provided concrete classes, one that automatically denominates values to be formatted, BtcAutoFormat, and another that formats any value in units of a fixed, specified denomination, BtcFixedFormat.

Automatic Denomination

Automatic denomination means that the formatter adjusts the denominational units in which a formatted number is expressed based on the monetary value that number represents. An auto-denominating formatter is defined by its style, specified by one of the enumerated values of BtcAutoFormat.Style. There are two styles constants: BtcAutoFormat.Style.CODE (the default), and BtcAutoFormat.Style.SYMBOL. The difference is that the CODE style uses an internationally-distinct currency code, such as "BTC", to indicate the units of denomination, while the SYMBOL style uses a possibly-ambiguous currency symbol such as "฿".

The denomination used when formatting will be either bitcoin, millicoin or microcoin, depending on the value being represented, chosen so as to minimize the number of consecutive zeros displayed without losing precision. For example, depending on the locale, a value of one bitcoin might be formatted as

฿1.00

where a value exceeding that by one satoshi would be

µ฿1,000,000.01

Fixed Denomination

Fixed denomination means that the same denomination of units is used for every value that is formatted or parsed by a given formatter instance. A fixed-denomination formatter is defined by its scale, which is the number of places one must shift the decimal point in increasing precision to convert the representation of a given quantity of bitcoins into a representation of the same value denominated in the formatter's units. For example, a scale value of 3 specifies a denomination of millibitcoins, because to represent 1.0000 BTC, or one bitcoin, in millibitcoins, one shifts the decimal point three places, that is, to 1000.0 mBTC.

Construction

There are two ways to obtain an instance of this class:

1. Use one of the factory methods; or
2. Use a BtcFormat.Builder object.

The factory methods are appropriate for basic use where the default configuration is either used or modified. The Builder class provides more control over the configuration, and gives access to some features not available through the factory methods, such as using custom formatting patterns and currency symbols.

Factory Methods

Although formatting and parsing is performed by one of the concrete subclasses, you can obtain formatters using the various static factory methods of this abstract base class BtcFormat. There are a variety of overloaded methods that allow you to obtain a formatter that behaves according to your needs.

The primary distinction is between automatic- and fixed-denomination formatters. By default, the getInstance() method with no arguments returns a new, automatic-denominating BtcAutoFormat instance for your default locale that will display exactly two fractional decimal places and a currency code. For example, if you happen to be in the USA:

 BtcFormat f = BtcFormat.getInstance();
 String s = f.format(Coin.COIN); // "BTC 1.00"
 

The first argument to getInstance() can determine whether you get an auto- or fixed-denominating formatter. If the type of the first argument is an int, then the value of that int will be interpreted as the decimal-place scale of the BtcFixedFormat instance that is returned, and thus will determine its denomination. For example, if you want to format values in units of microbitcoins:

BtcFormat m = BtcFormat.getInstance(6);
String s = m.format(Coin.COIN); // "1,000,000.00"
 

This class provides several constants bound to common scale values:

BtcFormat milliFormat = BtcFormat.getInstance(MILLICOIN_SCALE);

Alternatively, if the type of the first argument to getInstance() is one of the enumerated values of the BtcAutoFormat.Style type, either CODE or SYMBOL, then you will get a BtcAutoFormat instance that uses either a currency code or symbol, respectively, to indicate the results of its auto-denomination.

 BtcFormat s = BtcFormat.getInstance(SYMBOL);
 Coin value = Coin.parseCoin("0.1234");
 String mil = s.format(value);              // "₥฿123.40"
 String mic = s.format(value.divide(1000)); // "µ฿123.40"
 

An alternative way to specify whether you want an auto- or fixed-denomination formatter is to use one of the factory methods that is named to indicate that characteristics of the new instance returned. For fixed-denomination formatters, these methods are getCoinInstance(), getMilliInstance(), and getMicroInstance(). These three methods are equivalent to invoking getInstance() with a first argument of 0, 3 and 6, respectively. For auto-denominating formatters the relevant factory methods are getCodeInstance() and getSymbolInstance(), which are equivalent to getInstance(Style.CODE), and getInstance(Style.SYMBOL).

Regardless of how you specify whether your new formatter is to be of automatic- or fixed-denomination, the next (and possibly first) parameter to each of the factory methods is an optional Locale value. For example, here we construct four instances for the same locale that each format differently the same one-bitcoin value:

 // Next line returns "1,00 BTC"
 BtcFormat.getInstance(Locale.GERMANY).format(Coin.COIN);
 // Next line returns "1,00 ฿"
 BtcFormat.getInstance(SYMBOL, Locale.GERMANY).format(Coin.COIN);
 // Next line returns "1.000,00"
 BtcFormat.getMilliInstance(Locale.GERMANY).format(Coin.COIN);
 // Next line returns "10.000,00"
 BtcFormat.getInstance(4, Locale.GERMANY).format(Coin.COIN);
 

Omitting such a Locale parameter will give you a formatter for your default locale.

The final (and possibly only) arguments to the factory methods serve to set the default number of fractional decimal places that will be displayed when formatting monetary values. In the case of an auto-denominating formatter, this can be a single int value, which will determine the number of fractional decimal places to be used in all cases, except where either (1) doing so would provide a place for fractional satoshis, or (2) that default value is overridden when invoking the format() method as described below.

In the case of a fixed-denomination formatter, you can pass any number of int values. The first will determine the minimum number of fractional decimal places, and each following int value specifies the size of an optional group of decimal-places to be displayed only if useful for expressing precision. As with auto-denominating formatters, numbers will never be formatted with a decimal place that represents a fractional quantity of satoshis, and these defaults can be overridden by arguments to the format() method. See below for examples.

The Builder Class

A new BtcFormat.Builder instance is returned by the builder() method. Such an object has methods that set the configuration parameters of a BtcFormat object. Its BtcFormat.Builder.build() method constructs and returns a BtcFormat instance configured according to those settings.

In addition to setter-methods that correspond to the factory-method parameters explained above, a Builder also allows you to specify custom formatting and parsing patterns and currency symbols and codes. For example, rather than using the default currency symbol, which has the same unicode character point as the national currency symbol of Thailand, some people prefer to use a capital letter "B" with a vertical overstrike.

 BtcFormat.Builder builder = BtcFormat.builder();
 builder.style(SYMBOL);
 builder.symbol("B\u20e6"); // unicode char "double vertical stroke overlay"
 BtcFormat f = builder.build();
 String out = f.format(COIN); // "B⃦1.00" depending on locale
 

The Builder methods are chainable. So, for example, if you are deferential to ISO 4217, you might construct a formatter in a single line this way:

 BtcFormat f = BtcFormat.builder().style(CODE).code("XBT").build();
 String out = f.format(COIN); // "XBT 1.00"
 

See the documentation of the BtcFormat.Builder class for details.

Formatting

You format a Bitcoin monetary value by passing it to the Format.format(Object) method. This argument can be either a Coin-type object or a numerical object such as Long or BigDecimal. Integer-based types such as BigInteger are interpreted as representing a number of satoshis, while a BigDecimal is interpreted as representing a number of bitcoins. A value having a fractional amount of satoshis is rounded to the nearest whole satoshi at least, and possibly to a greater unit depending on the number of fractional decimal-places displayed. The format() method will not accept an argument whose type is String, Float nor Double.

Subsequent to the monetary value to be formatted, the Format.format(Object) method also accepts as arguments optional int values that specify the number of decimal places to use to represent the fractional portion of the number. This overrides the default, and enables a single formatter instance to be reused, formatting different values that require different numbers of fractional decimal places. These parameters have the same meaning as those that set the default values in the factory methods as described above. Namely, a single int value determines the minimum number of fractional decimal places that will be used in all cases, to a precision limit of satoshis. Instances of BtcFixedFormat also accept a variable-length sequence of additional int values, each of which specifies the size of a group of fractional decimal-places to be used in addition to all preceding places, only if useful to express precision, and only to a maximum precision of satoshis. For example:

 BtcFormat f = BtcFormat.getCoinInstance();
 Coin value = COIN.add(Coin.valueOf(5)); // 100000005 satoshis
 f.format(value, 2);       // "1.00"
 f.format(value, 3);       // "1.000"
 f.format(value, 2, 3);    // "1.00" three more zeros doesn't help 
 f.format(value, 2, 3, 3); // "1.00000005" 
 f.format(value, 2, 3, 4); // "1.00000005" fractions of satoshis have no place
 f.format(value, 2, 3, 2); // "1.0000001" rounds to nearest usable place
 

Note that if using all the fractional decimal places in a specified group would give a place to fractions of satoshis, then the size of that group will be reduced to a maximum precision of satoshis. Either all or none of the allowed decimal places of that group will still be applied as doing so is useful for expressing the precision of the value being formatted.

Several convenient constants of repeating group-size sequences are provided: BtcFixedFormat.REPEATING_PLACES, BtcFixedFormat.REPEATING_DOUBLETS and BtcFixedFormat.REPEATING_TRIPLETS. These signify repeating groups of one, two and three decimals places, respectively. For example, to display only as many fractional places as useful in order to prevent hanging zeros on the least-significant end of formatted numbers:

 format(value, 0, REPEATING_PLACES);
 

When using an automatically-denominating formatter, you might want to know what denomination was chosen. You can get the currency-units indicator, as well as any other field in the formatted output, by using a FieldPosition instance constructed using an appropriate constant from the NumberFormat.Field class:

 BtcFormat de = BtcFormat.getInstance(Locale.GERMANY);
 FieldPosition currField = new FieldPosition(NumberFormat.Field.CURRENCY);
 // next line formats the value as "987.654.321,23 µBTC"
 String output = de.format(valueOf(98765432123L), new StringBuffer(), currField);
 // next line sets variable currencyCode to "µBTC"
 String currencyCode = output.substring(currField.getBeginIndex(), currField.getEndIndex()));
 

When using a fixed-denomination formatter whose scale can be expressed as a standard "metric" prefix, you can invoke the code() and symbol() methods to obtain a String whose value is the appropriate currency code or symbol, respectively, for that formatter.

 BtcFixedFormat kilo = (BtcFixedFormat)BtcFormat(-3); // scale -3 for kilocoins
 Coin value = Coin.parseCoin("1230");
 // variable coded will be set to "kBTC 1.23"
 String coded = kilo.code() + " " + kilo.format(value);
 // variable symbolic will be set to "k฿1.23"
 String symbolic = kilo.symbol() + kilo.format(value);
 BtcFormat(4).code(); // unnamed denomination has no code; raises exception
 

Formatting for Tabular Columns

When displaying tables of monetary values, you can lessen the risk of human misreading-error by vertically aligning the decimal separator of those values. This example demonstrates one way to do that:

 // The elements of this array are the values we will format:
 Coin[] rows = {MAX_MONEY, MAX_MONEY.subtract(SATOSHI), Coin.parseCoin("1234"),
                COIN, COIN.divide(1000),
                valueOf(10000), valueOf(1000), valueOf(100),
                SATOSHI};
 BtcFormat f = BtcFormat.getCoinInstance(2, REPEATING_PLACES);
 FieldPosition fp = new FieldPosition(DECIMAL_SEPARATOR); // see java.text.NumberFormat.Field
 String[] output = new String[rows.length];
 int[] indexes = new int[rows.length];
 int maxIndex = 0;
 for (int i = 0; i < rows.length; i++) {
     output[i] = f.format(rows[i], new StringBuffer(), fp).toString();
     indexes[i] = fp.getBeginIndex();
     if (indexes[i] > maxIndex) maxIndex = indexes[i];
 }
 for (int i = 0; i < output.length; i++) {
     System.out.println(repeat(" ", (maxIndex - indexes[i])) + output[i]);
 }
 

Assuming you are using a monospaced font, and depending on your locale, the foregoing will print the following:

 21,000,000.00
 20,999,999.99999999
      1,234.00
          1.00
          0.001
          0.0001
          0.00001
          0.000001
          0.00000001
 

If you need to vertically-align columns printed in a proportional font, then see the documentation for the NumberFormat class for an explanation of how to do that.

Parsing

The parse(String) method accepts a String argument, and returns a Coin-type value. The difference in parsing behavior between instances of BtcFixedFormat and BtcAutoFormat is analogous to the difference in formatting behavior between instances of those classes. Instances of BtcAutoFormat recognize currency codes and symbols in the String being parsed, and interpret them as indicators of the units in which the number being parsed is denominated. On the other hand, instances of BtcFixedFormat by default recognize no codes nor symbols, but rather interpret every number as being denominated in the units that were specified when constructing the instance doing the parsing. This default behavior of BtcFixedFormat can be overridden by setting a parsing pattern that includes a currency sign using the pattern() method.

The parse(String) method of BtcAutoFormat (and of BtcAutoFormat configured with applicable non-default pattern) will recognize a variety of currency symbols and codes, including all standard international (metric) prefixes from micro to mega. For example, denominational units of microcoins may be specified by µ฿, u฿, µB⃦, µɃ, µBTC or other appropriate permutations of those characters. Additionally, if either or both of a custom currency code or symbol is configured using BtcFormat.Builder.code or BtcFormat.Builder.code, then such code or symbol will be recognized in addition to those recognized by default..

Instances of this class that recognize currency signs will recognize both currency symbols and codes, regardless of which that instance uses for formatting. However, if the style is CODE (and unless overridden by a custom pattern) then a space character must separate the units indicator from the number. When parsing with a SYMBOL-style BtcFormat instance, on the other hand, whether or not the units indicator must be separated by a space from the number is determined by the locale. The pattern() method returns a representation of the pattern that can be examined to determine whether a space must separate currency signs from numbers in parsed Strings.

When parsing, if the currency-units indicator is absent, then a BtcAutoFormat instance will infer a denomination of bitcoins while a BtcFixedFormat will infer the denomination in which it expresses formatted values. Note: by default (unless overridden by a custom pattern), if the locale or style requires a space to separate the number from the units indicator, that space must be present in the String to be parsed, even if the units indicator is absent.

The parse() method returns an instance of the Coin class. Therefore, attempting to parse a value greater than the maximum that a Coin object can represent will raise a ParseException, as will any other detected parsing error.

Limitations

Parsing

Parsing is performed by an underlying NumberFormat object. While this delivers the benefit of recognizing locale-specific patterns, some have criticized other aspects of its behavior. For example, see this article by Joe Sam Shirah. In particular, explicit positive-signs are not recognized. If you are parsing input from end-users, then you should consider whether you would benefit from any of the work-arounds mentioned in that article.

Exotic Locales

This class is not well-tested in locales that use non-ascii character sets, especially those where writing proceeds from right-to-left. Helpful feedback in that regard is appreciated.

Thread-Safety

Instances of this class are immutable.

See Also:

Format, NumberFormat, DecimalFormat, DecimalFormatSymbols, FieldPosition, Coin, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BtcFormat.Builder This class constructs new instances of BtcFormat, allowing for the configuration of those instances before they are constructed.

Nested classes/interfaces inherited from class java.text.Format

Format.Field

Field Summary

Fields

Modifier and Type	Field and Description
static int	COIN_SCALE A constant useful for specifying a denomination of bitcoins, the int value 0.
protected static String	COIN_SYMBOL_ALT An alternative currency symbol to use in locales where the default symbol is used for the national currency.
protected List<Integer>	decimalGroups
static int	MICROCOIN_SCALE A constant useful for specifying a denomination of microbitcoins, the int value 6.
static int	MILLICOIN_SCALE A constant useful for specifying a denomination of millibitcoins, the int value 3.
protected int	minimumFractionDigits
protected DecimalFormat	numberFormat

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BtcFormat(DecimalFormat numberFormat, int minDecimals, List<Integer> groups) This single constructor is invoked by the overriding subclass constructors.

Method Summary

Modifier and Type	Method and Description
static BtcFormat.Builder	builder() Return a new BtcFormat.Builder object.
String	coinCode() Return the unprefixed international currency code for bitcoins configured for this object.
String	coinSymbol() Return the unprefixed currency symbol for bitcoins configured for this object.
boolean	equals(Object o) Return true if the given object is equivalent to this one.
String	format(Object qty, int minDecimals, int... fractionGroups) Formats a bitcoin value as a number and possibly a units indicator to a String.The type of monetary value argument can be any one of any of the following classes: Coin, Integer, Long, BigInteger, BigDecimal.
StringBuffer	format(Object qty, StringBuffer toAppendTo, FieldPosition pos) Formats a bitcoin value as a number and possibly a units indicator and appends the resulting text to the given string buffer.
StringBuffer	format(Object qty, StringBuffer toAppendTo, FieldPosition pos, int minDecimals, int... fractionGroups) Formats a bitcoin value as a number and possibly a units indicator and appends the resulting text to the given string buffer.
AttributedCharacterIterator	formatToCharacterIterator(Object obj) Formats a bitcoin monetary value and returns an AttributedCharacterIterator.
static Locale[]	getAvailableLocales() Return an array of all locales for which the getInstance() method of this class can return localized instances.
static BtcFormat	getCodeInstance() Return a new auto-denominating instance that will indicate units using a currency code, for example, "BTC".
static BtcFormat	getCodeInstance(int minDecimals) Return a new code-style auto-formatter with the given number of fractional decimal places.
static BtcFormat	getCodeInstance(Locale locale) Return a new code-style auto-formatter for the given locale.
static BtcFormat	getCodeInstance(Locale locale, int minDecimals) Return a new code-style auto-formatter for the given locale with the given number of fraction places.
static BtcFormat	getCoinInstance() Return a new coin-denominated formatter.
static BtcFormat	getCoinInstance(int minFractionPlaces, int... groups) Return a new coin-denominated formatter with the specified fraction-places.
static BtcFormat	getCoinInstance(Locale locale) Return a new coin-denominated formatter for the given locale.
static BtcFormat	getCoinInstance(Locale locale, int scale, int... groups) Return a newly-constructed instance for the given locale that will format values in terms of bitcoins, with the given minimum number of fractional decimal places.
static BtcFormat	getInstance() Return a new instance of this class using all defaults.
static BtcFormat	getInstance(BtcAutoFormat.Style style) Return a new auto-denominating formatter.
static BtcFormat	getInstance(BtcAutoFormat.Style style, int fractionPlaces) Return a new auto-denominating formatter with the given number of fractional decimal places.
static BtcFormat	getInstance(BtcAutoFormat.Style style, Locale locale) Return a new auto-formatter with the given style for the given locale.
static BtcFormat	getInstance(BtcAutoFormat.Style style, Locale locale, int fractionPlaces) Return a new auto-formatter for the given locale with the given number of fraction places.
static BtcFormat	getInstance(int scale) Return a new fixeed-denomination formatter.
static BtcFormat	getInstance(int scale, int minDecimals, int... groups) Return a new fixeed-denomination formatter with the specified fractional decimal placing.
static BtcFormat	getInstance(int scale, Locale locale) Return a new fixeed-denomination formatter for the given locale.
static BtcFormat	getInstance(int scale, Locale locale, int minDecimals, int... groups) Return a new fixed-denomination formatter for the given locale, with the specified fractional decimal placing.
static BtcFormat	getInstance(int scale, Locale locale, int minDecimals, List<Integer> groups) Return a new fixed-denomination formatter for the given locale, with the specified fractional decimal placing.
static BtcFormat	getInstance(Locale locale) Return a new code-style auto-formatter for the given locale.
static BtcFormat	getInstance(Locale locale, int minDecimals) Return a new code-style auto-formatter for the given locale with the given number of fraction places.
static BtcFormat	getMicroInstance() Return a new microcoin-denominated formatter for the default locale.
static BtcFormat	getMicroInstance(int scale, int... groups) Return a new microcoin-denominated formatter with the specified fractional decimal placing.
static BtcFormat	getMicroInstance(Locale locale) Return a new microcoin-denominated formatter for the given locale.
static BtcFormat	getMicroInstance(Locale locale, int scale, int... groups) Return a new microcoin-denominated formatter for the given locale with the specified fractional decimal placing.
static BtcFormat	getMilliInstance() Return a new millicoin-denominated formatter.
static BtcFormat	getMilliInstance(int scale, int... groups) Return a new millicoin-denominated formatter with the specified fractional decimal placing.
static BtcFormat	getMilliInstance(Locale locale) Return a new millicoin-denominated formatter for the given locale.
static BtcFormat	getMilliInstance(Locale locale, int scale, int... groups) Return a new millicoin-denominated formatter for the given locale with the specified fractional decimal placing.
static BtcFormat	getSymbolInstance() Return a new auto-denominating instance that will indicate units using a currency symbol, for example, "฿".
static BtcFormat	getSymbolInstance(int fractionPlaces) Return a new symbol-style auto-formatter with the given number of fractional decimal places.
static BtcFormat	getSymbolInstance(Locale locale) Return a new symbol-style auto-formatter for the given locale.
static BtcFormat	getSymbolInstance(Locale locale, int fractionPlaces) Return a new symbol-style auto-formatter for the given locale with the given number of fraction places.
int	hashCode() Return a hash code value for this instance.
protected static String	negify(String pattern) Guarantee a formatting pattern has a subpattern for negative values.
Coin	parse(String source) Parse a String representation of a Bitcoin monetary value.
Coin	parse(String source, ParsePosition pos) Parse a String representation of a Bitcoin monetary value.
Object	parseObject(String source, ParsePosition pos) Parse a String representation of a Bitcoin monetary value.
String	pattern() Return a representation of the pattern used by this instance for formatting and parsing.
protected static String	prefixCode(String code, int scale)
protected static String	prefixSymbol(String symbol, int scale)
protected static void	prefixUnitsIndicator(DecimalFormat numberFormat, int scale) Set both the currency symbol and code of the underlying, mutable NumberFormat object according to the given denominational units scale factor.
protected abstract int	scale() Return the denomination of this object.
protected abstract int	scale(BigInteger satoshis, int fractionPlaces) Return the denomination for formatting the given value.
DecimalFormatSymbols	symbols() Return a copy of the localized symbols used by this instance for formatting and parsing.

Methods inherited from class java.text.Format

clone, format, parseObject

Methods inherited from class java.lang.Object

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

Field Detail

COIN_SYMBOL_ALT

protected static final String COIN_SYMBOL_ALT

An alternative currency symbol to use in locales where the default symbol is used for the national currency.

See Also:

Constant Field Values

numberFormat

protected final DecimalFormat numberFormat

minimumFractionDigits

protected final int minimumFractionDigits

decimalGroups

protected final List<Integer> decimalGroups

COIN_SCALE

public static final int COIN_SCALE

A constant useful for specifying a denomination of bitcoins, the int value 0.

See Also:

Constant Field Values

MILLICOIN_SCALE

public static final int MILLICOIN_SCALE

A constant useful for specifying a denomination of millibitcoins, the int value 3.

See Also:

Constant Field Values

MICROCOIN_SCALE

public static final int MICROCOIN_SCALE

A constant useful for specifying a denomination of microbitcoins, the int value 6.

See Also:

Constant Field Values

Constructor Detail

BtcFormat

protected BtcFormat(DecimalFormat numberFormat,
                    int minDecimals,
                    List<Integer> groups)

This single constructor is invoked by the overriding subclass constructors.

Method Detail

builder

public static BtcFormat.Builder builder()

Return a new BtcFormat.Builder object. See the documentation of that class for usage details.

getInstance

public static BtcFormat getInstance()

Return a new instance of this class using all defaults. The returned formatter will auto-denominate values so as to minimize zeros without loss of precision and display a currency code, for example "BTC", to indicate that denomination. The returned object will uses the default locale for formatting the number and placement of the currency-code. Two fractional decimal places will be displayed in all formatted numbers.

getSymbolInstance

public static BtcFormat getSymbolInstance()

Return a new auto-denominating instance that will indicate units using a currency symbol, for example, "฿". Formatting and parsing will be done according to the default locale.

getCodeInstance

public static BtcFormat getCodeInstance()

Return a new auto-denominating instance that will indicate units using a currency code, for example, "BTC". Formatting and parsing will be done according to the default locale.

getSymbolInstance

public static BtcFormat getSymbolInstance(int fractionPlaces)

Return a new symbol-style auto-formatter with the given number of fractional decimal places. Denominational units will be indicated using a currency symbol, for example, "฿". The returned object will format the fraction-part of numbers using the given number of decimal places, or fewer as necessary to avoid giving a place to fractional satoshis. Formatting and parsing will be done according to the default locale.

getCodeInstance

public static BtcFormat getCodeInstance(int minDecimals)

Return a new code-style auto-formatter with the given number of fractional decimal places. Denominational units will be indicated using a currency code, for example, "BTC". The returned object will format the fraction-part of numbers using the given number of decimal places, or fewer as necessary to avoid giving a place to fractional satoshis. Formatting and parsing will be done according to the default locale.

getInstance

public static BtcFormat getInstance(Locale locale)

Return a new code-style auto-formatter for the given locale. The returned object will select denominational units based on each value being formatted, and will indicate those units using a currency code, for example, "mBTC".

getCodeInstance

public static BtcFormat getCodeInstance(Locale locale)

Return a new code-style auto-formatter for the given locale. The returned object will select denominational units based on each value being formatted, and will indicate those units using a currency code, for example, "mBTC".

getInstance

public static BtcFormat getInstance(Locale locale,
                                    int minDecimals)

Return a new code-style auto-formatter for the given locale with the given number of fraction places. The returned object will select denominational units based on each value being formatted, and will indicate those units using a currency code, for example, "mBTC". The returned object will format the fraction-part of numbers using the given number of decimal places, or fewer as necessary to avoid giving a place to fractional satoshis.

getCodeInstance

public static BtcFormat getCodeInstance(Locale locale,
                                        int minDecimals)

Return a new code-style auto-formatter for the given locale with the given number of fraction places. The returned object will select denominational units based on each value being formatted, and will indicate those units using a currency code, for example, "mBTC". The returned object will format the fraction-part of numbers using the given number of decimal places, or fewer as necessary to avoid giving a place to fractional satoshis.

getSymbolInstance

public static BtcFormat getSymbolInstance(Locale locale)

Return a new symbol-style auto-formatter for the given locale. The returned object will select denominational units based on each value being formatted, and will indicate those units using a currency symbol, for example, "µ฿".

getSymbolInstance

public static BtcFormat getSymbolInstance(Locale locale,
                                          int fractionPlaces)

Return a new symbol-style auto-formatter for the given locale with the given number of fraction places. The returned object will select denominational units based on each value being formatted, and will indicate those units using a currency symbol, for example, "µ฿". The returned object will format the fraction-part of numbers using the given number of decimal places, or fewer as necessary to avoid giving a place to fractional satoshis.

getInstance

public static BtcFormat getInstance(BtcAutoFormat.Style style)

Return a new auto-denominating formatter. The returned object will indicate the denominational units of formatted values using either a currency symbol, such as, "฿", or code, such as "mBTC", depending on the value of the argument. Formatting and parsing will be done according to the default locale.

getInstance

public static BtcFormat getInstance(BtcAutoFormat.Style style,
                                    int fractionPlaces)

Return a new auto-denominating formatter with the given number of fractional decimal places. The returned object will indicate the denominational units of formatted values using either a currency symbol, such as, "฿", or code, such as "mBTC", depending on the value of the first argument. The returned object will format the fraction-part of numbers using the given number of decimal places, or fewer as necessary to avoid giving a place to fractional satoshis. Formatting and parsing will be done according to the default locale.

getInstance

public static BtcFormat getInstance(BtcAutoFormat.Style style,
                                    Locale locale)

Return a new auto-formatter with the given style for the given locale. The returned object that will auto-denominate each formatted value, and will indicate that denomination using either a currency code, such as "BTC", or symbol, such as "฿", depending on the value of the first argument.

The number of fractional decimal places in formatted number will be two, or fewer as necessary to avoid giving a place to fractional satoshis.

getInstance

public static BtcFormat getInstance(BtcAutoFormat.Style style,
                                    Locale locale,
                                    int fractionPlaces)

Return a new auto-formatter for the given locale with the given number of fraction places. The returned object will automatically-denominate each formatted value, and will indicate that denomination using either a currency code, such as "mBTC", or symbol, such as "฿", according to the given style argument. It will format each number according to the given locale.

The third parameter is the number of fractional decimal places to use for each formatted number, reduced as neccesary when formatting to avoid giving a place to fractional satoshis.

getCoinInstance

public static BtcFormat getCoinInstance()

Return a new coin-denominated formatter. The returned object will format and parse values according to the default locale, and will format numbers with two fractional decimal places, rounding values as necessary.

getCoinInstance

public static BtcFormat getCoinInstance(int minFractionPlaces,
                                        int... groups)

Return a new coin-denominated formatter with the specified fraction-places. The returned object will format and parse values according to the default locale, and will format the fraction part of numbers with at least two decimal places. The sizes of additional groups of decimal places can be specified by a variable number of int arguments. Each optional decimal-place group will be applied only if useful for expressing precision, and will be only partially applied if necessary to avoid giving a place to fractional satoshis.

getCoinInstance

public static BtcFormat getCoinInstance(Locale locale)

Return a new coin-denominated formatter for the given locale. The returned object will format the fractional part of numbers with two decimal places, rounding as necessary.

getCoinInstance

public static BtcFormat getCoinInstance(Locale locale,
                                        int scale,
                                        int... groups)

Return a newly-constructed instance for the given locale that will format values in terms of bitcoins, with the given minimum number of fractional decimal places. Optionally, repeating integer arguments can be passed, each indicating the size of an additional group of fractional decimal places to be used as necessary to avoid rounding, to a limiting precision of satoshis.

getMilliInstance

public static BtcFormat getMilliInstance()

Return a new millicoin-denominated formatter. The returned object will format and parse values for the default locale, and will format the fractional part of numbers with two decimal places, rounding as necessary.

getMilliInstance

public static BtcFormat getMilliInstance(Locale locale)

Return a new millicoin-denominated formatter for the given locale. The returned object will format the fractional part of numbers with two decimal places, rounding as necessary.

getMilliInstance

public static BtcFormat getMilliInstance(int scale,
                                         int... groups)

Return a new millicoin-denominated formatter with the specified fractional decimal placing. The returned object will format and parse values according to the default locale, and will format the fractional part of numbers with the given minimum number of fractional decimal places. Optionally, repeating integer arguments can be passed, each indicating the size of an additional group of fractional decimal places to be used as necessary to avoid rounding, to a limiting precision of satoshis.

getMilliInstance

public static BtcFormat getMilliInstance(Locale locale,
                                         int scale,
                                         int... groups)

Return a new millicoin-denominated formatter for the given locale with the specified fractional decimal placing. The returned object will format the fractional part of numbers with the given minimum number of fractional decimal places. Optionally, repeating integer arguments can be passed, each indicating the size of an additional group of fractional decimal places to be used as necessary to avoid rounding, to a limiting precision of satoshis.

getMicroInstance

public static BtcFormat getMicroInstance()

Return a new microcoin-denominated formatter for the default locale. The returned object will format the fractional part of numbers with two decimal places, rounding as necessary.

getMicroInstance

public static BtcFormat getMicroInstance(Locale locale)

Return a new microcoin-denominated formatter for the given locale. The returned object will format the fractional part of numbers with two decimal places, rounding as necessary.

getMicroInstance

public static BtcFormat getMicroInstance(int scale,
                                         int... groups)

Return a new microcoin-denominated formatter with the specified fractional decimal placing. The returned object will format and parse values according to the default locale, and will format the fractional part of numbers with the given minimum number of fractional decimal places. Optionally, repeating integer arguments can be passed, each indicating the size of an additional group of fractional decimal places to be used as necessary to avoid rounding, to a limiting precision of satoshis.

getMicroInstance

public static BtcFormat getMicroInstance(Locale locale,
                                         int scale,
                                         int... groups)

Return a new microcoin-denominated formatter for the given locale with the specified fractional decimal placing. The returned object will format the fractional part of numbers with the given minimum number of fractional decimal places. Optionally, repeating integer arguments can be passed, each indicating the size of an additional group of fractional decimal places to be used as necessary to avoid rounding, to a limiting precision of satoshis.

getInstance

public static BtcFormat getInstance(int scale,
                                    int minDecimals,
                                    int... groups)

Return a new fixeed-denomination formatter with the specified fractional decimal placing. The first argument specifies the denomination as the size of the shift from coin-denomination in increasingly-precise decimal places. The returned object will format and parse values according to the default locale, and will format the fractional part of numbers with the given minimum number of fractional decimal places. Optionally, repeating integer arguments can be passed, each indicating the size of an additional group of fractional decimal places to be used as necessary to avoid rounding, to a limiting precision of satoshis.

getInstance

public static BtcFormat getInstance(int scale)

Return a new fixeed-denomination formatter. The argument specifies the denomination as the size of the shift from coin-denomination in increasingly-precise decimal places. The returned object will format and parse values according to the default locale, and will format the fractional part of numbers with two decimal places, or fewer as necessary to avoid giving a place to fractional satoshis.

getInstance

public static BtcFormat getInstance(int scale,
                                    Locale locale)

Return a new fixeed-denomination formatter for the given locale. The first argument specifies the denomination as the size of the shift from coin-denomination in increasingly-precise decimal places. The returned object will format and parse values according to the locale specified by the second argument, and will format the fractional part of numbers with two decimal places, or fewer as necessary to avoid giving a place to fractional satoshis.

getInstance

public static BtcFormat getInstance(int scale,
                                    Locale locale,
                                    int minDecimals,
                                    int... groups)

Return a new fixed-denomination formatter for the given locale, with the specified fractional decimal placing. The first argument specifies the denomination as the size of the shift from coin-denomination in increasingly-precise decimal places. The third parameter is the minimum number of fractional decimal places to use, followed by optional repeating integer parameters each specifying the size of an additional group of fractional decimal places to use as necessary to avoid rounding, down to a maximum precision of satoshis.

getInstance

public static BtcFormat getInstance(int scale,
                                    Locale locale,
                                    int minDecimals,
                                    List<Integer> groups)

Return a new fixed-denomination formatter for the given locale, with the specified fractional decimal placing. The first argument specifies the denomination as the size of the shift from coin-denomination in increasingly-precise decimal places. The third parameter is the minimum number of fractional decimal places to use. The third argument specifies the minimum number of fractional decimal places in formatted numbers. The last argument is a List of Integer values, each of which specifies the size of an additional group of fractional decimal places to use as necessary to avoid rounding, down to a maximum precision of satoshis.

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object obj)

Formats a bitcoin monetary value and returns an AttributedCharacterIterator. By iterating, you can examine what fields apply to each character. This can be useful since a character may be part of more than one field, for example a grouping separator that is also part of the integer field.

Overrides:

formatToCharacterIterator in class Format

See Also:

AttributedCharacterIterator

format

public StringBuffer format(Object qty,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Formats a bitcoin value as a number and possibly a units indicator and appends the resulting text to the given string buffer. The type of monetary value argument can be any one of any of the following classes: Coin, Integer, Long, BigInteger, BigDecimal. Numeric types that can represent only an integer are interpreted as that number of satoshis. The value of a BigDecimal is interpreted as that number of bitcoins, rounded to the nearest satoshi as necessary.

Specified by:

format in class Format

Returns:

the StringBuffer passed in as toAppendTo

format

public String format(Object qty,
                     int minDecimals,
                     int... fractionGroups)

Formats a bitcoin value as a number and possibly a units indicator to a String.The type of monetary value argument can be any one of any of the following classes: Coin, Integer, Long, BigInteger, BigDecimal. Numeric types that can represent only an integer are interpreted as that number of satoshis. The value of a BigDecimal is interpreted as that number of bitcoins, rounded to the nearest satoshi as necessary.

Parameters:

minDecimals - The minimum number of decimal places in the fractional part of the formatted number

fractionGroups - The sizes of optional additional fractional decimal-place groups

Throws:

IllegalArgumentException - if the number of fraction places is negative.

format

public StringBuffer format(Object qty,
                           StringBuffer toAppendTo,
                           FieldPosition pos,
                           int minDecimals,
                           int... fractionGroups)

Formats a bitcoin value as a number and possibly a units indicator and appends the resulting text to the given string buffer. The type of monetary value argument can be any one of any of the following classes: Coin, Integer, Long, BigInteger, BigDecimal. Numeric types that can represent only an integer are interpreted as that number of satoshis. The value of a BigDecimal is interpreted as that number of bitcoins, rounded to the nearest satoshi as necessary.

Parameters:

minDecimals - The minimum number of decimal places in the fractional part of the formatted number

fractionGroups - The sizes of optional additional fractional decimal-place groups

Throws:

IllegalArgumentException - if the number of fraction places is negative.

scale

protected abstract int scale(BigInteger satoshis,
                             int fractionPlaces)

Return the denomination for formatting the given value. The returned int is the size of the decimal-place shift between the given Bitcoin-value denominated in bitcoins and that same value as formatted. A fixed-denomination formatter will ignore the arguments.

Parameters:

satoshis - The number of satoshis having the value for which the shift is calculated

fractionPlaces - The number of decimal places available for displaying the fractional part of the denominated value

Returns:

The size of the shift in increasingly-precise decimal places

scale

protected abstract int scale()

Return the denomination of this object. Fixed-denomination formatters will override with their configured denomination, auto-formatters with coin denomination. This determines the interpretation of parsed numbers lacking a units-indicator.

parseObject

public final Object parseObject(String source,
                                ParsePosition pos)

Parse a String representation of a Bitcoin monetary value. Returns a Coin object that represents the parsed value.

Specified by:

parseObject in class Format

See Also:

NumberFormat

prefixUnitsIndicator

protected static void prefixUnitsIndicator(DecimalFormat numberFormat,
                                           int scale)

Set both the currency symbol and code of the underlying, mutable NumberFormat object according to the given denominational units scale factor. This is for formatting, not parsing.

Set back to zero when you're done formatting otherwise immutability, equals() and hashCode() will break!

Parameters:

scale - Number of places the decimal point will be shifted when formatting a quantity of satoshis.

parse

public Coin parse(String source,
                  ParsePosition pos)

Parse a String representation of a Bitcoin monetary value. If this object's pattern includes a currency sign, either symbol or code, as by default is true for instances of BtcAutoFormat and false for instances of BtcFixedFormat, then denominated (i.e., prefixed) currency signs in the parsed String will be recognized, and the parsed number will be interpreted as a quantity of units having that recognized denomination.

If the pattern includes a currency sign but no currency sign is detected in the parsed String, then the number is interpreted as a quatity of bitcoins.

If the pattern contains neither a currency symbol nor sign, then instances of BtcAutoFormat will interpret the parsed number as a quantity of bitcoins, and instances of BtcAutoFormat will interpret the number as a quantity of that instance's configured denomination, which can be ascertained by invoking the BtcFixedFormat.symbol() or BtcFixedFormat.code() method.

Consider using the single-argument version of this overloaded method unless you need to keep track of the current parse position.

Returns:

a Coin object representing the parsed value

See Also:

ParsePosition

parse

public Coin parse(String source)
           throws ParseException

Parse a String representation of a Bitcoin monetary value. If this object's pattern includes a currency sign, either symbol or code, as by default is true for instances of BtcAutoFormat and false for instances of BtcFixedFormat, then denominated (i.e., prefixed) currency signs in the parsed String will be recognized, and the parsed number will be interpreted as a quantity of units having that recognized denomination.

If the pattern includes a currency sign but no currency sign is detected in the parsed String, then the number is interpreted as a quatity of bitcoins.

If the pattern contains neither a currency symbol nor sign, then instances of BtcAutoFormat will interpret the parsed number as a quantity of bitcoins, and instances of BtcAutoFormat will interpret the number as a quantity of that instance's configured denomination, which can be ascertained by invoking the BtcFixedFormat.symbol() or BtcFixedFormat.code() method.

Returns:

a Coin object representing the parsed value

Throws:

ParseException

prefixCode

protected static String prefixCode(String code,
                                   int scale)

prefixSymbol

protected static String prefixSymbol(String symbol,
                                     int scale)

negify

protected static String negify(String pattern)

Guarantee a formatting pattern has a subpattern for negative values. This method takes a pattern that may be missing a negative subpattern, and returns the same pattern with a negative subpattern appended as needed.

This method accommodates an imperfection in the Java formatting code and distributed locale data. To wit: the subpattern for negative numbers is optional and not all locales have one. In those cases, DecimalFormat will indicate numbers less than zero by adding a negative sign as the first character of the prefix of the positive subpattern.

We don't like this, since we claim the negative sign applies to the number not the units, and therefore it ought to be adjacent to the number, displacing the currency-units indicator if necessary.

getAvailableLocales

public static Locale[] getAvailableLocales()

Return an array of all locales for which the getInstance() method of this class can return localized instances. See NumberFormat.getAvailableLocales()

coinSymbol

public String coinSymbol()

Return the unprefixed currency symbol for bitcoins configured for this object. The return value of this method is constant throughough the life of an instance.

coinCode

public String coinCode()

Return the unprefixed international currency code for bitcoins configured for this object. The return value of this method is constant throughough the life of an instance.

pattern

public String pattern()

Return a representation of the pattern used by this instance for formatting and parsing. The format is similar to, but not the same as the format recognized by the BtcFormat.Builder.pattern and BtcFormat.Builder.localizedPattern methods. The pattern returned by this method is localized, any currency signs expressed are literally, and optional fractional decimal places are shown grouped in parentheses.

symbols

public DecimalFormatSymbols symbols()

Return a copy of the localized symbols used by this instance for formatting and parsing.

equals

public boolean equals(Object o)

Return true if the given object is equivalent to this one. Formatters for different locales will never be equal, even if they behave identically.

Overrides:

equals in class Object

hashCode

public int hashCode()

Return a hash code value for this instance.

Overrides:

hashCode in class Object

See Also:

Object.hashCode()