Package 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 BtcFormat.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 BtcAutoFormat.Style.CODE or BtcAutoFormat.Style.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 BtcFormat.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 BtcFormat.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 BtcFormat.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:

  • Field Details

    • 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:

    • 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:

    • MILLICOIN_SCALE

      public static final int MILLICOIN_SCALE
      A constant useful for specifying a denomination of millibitcoins, the int value 3.
      See Also:

    • MICROCOIN_SCALE

      public static final int MICROCOIN_SCALE
      A constant useful for specifying a denomination of microbitcoins, the int value 6.
      See Also:

  • Constructor Details

    • BtcFormat

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

  • Method Details

    • 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 necessary 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 fixed-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 fixed-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 fixed-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:

    • 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:

    • 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:

    • 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)
      END OF PARSING STUFF

    • 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 throughout 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: