Package org.bitcoinj.utils

Class BtcFormat.Builder

  • Enclosing class:
    BtcFormat
    public static class BtcFormat.Builder
extends java.lang.Object

    This class constructs new instances of BtcFormat, allowing for the configuration of those instances before they are constructed. After obtaining a Builder object from the BtcFormat.builder() method, invoke the necessary setter methods to obtain your desired configuration. Finally, the build() method returns a new BtcFormat object that has the specified configuration.

    All the setter methods override defaults. Invoking build() without invoking any of the setting methods is equivalent to invoking BtcFormat.getInstance() with no arguments.

    Each setter methods returns the same instance on which it is invoked, thus these methods can be chained.

    Instances of this class are not thread-safe.

    • Method Detail

      • style

        public BtcFormat.Builder style​(BtcAutoFormat.Style val)
        Specify the new BtcFormat is to be automatically-denominating. The argument determines which of either codes or symbols the new BtcFormat will use by default to indicate the denominations it chooses when formatting values.

        Note that the Style argument specifies the default style, which is overridden by invoking either pattern(String) or localizedPattern(String).

        Throws:
        java.lang.IllegalArgumentException - if scale(int) has previously been invoked on this instance.

      • fractionDigits

        public BtcFormat.Builder fractionDigits​(int val)
        Specify the number of decimal places in the fraction part of formatted numbers. This is equivalent to the minimumFractionDigits(int) method, but named appropriately for the context of generating BtcAutoFormat instances.

        If neither this method nor minimumFactionDigits() is invoked, the default value will be 2.

      • scale

        public BtcFormat.Builder scale​(int val)
        Specify a fixed-denomination of units to use when formatting and parsing values. The argument specifies the number of decimal places, in increasing precision, by which each formatted value will differ from that same value denominated in bitcoins. For example, a denomination of millibitcoins is specified with a value of 3.

        The BtcFormat class provides appropriately named int-type constants for the three common values, BtcFormat.COIN_SCALE, BtcFormat.MILLICOIN_SCALE BtcFormat.MICROCOIN_SCALE.

        If neither this method nor style(BtcAutoFormat.Style) is invoked on a BtcFormat.Builder, then the BtcFormat will default to a fixed-denomination of bitcoins, equivalent to invoking this method with an argument of 0.

      • minimumFractionDigits

        public BtcFormat.Builder minimumFractionDigits​(int val)
        Specify the minimum number of decimal places in the fraction part of formatted values. This method is equivalent to fractionDigits(int), but named appropriately for the context of generating a fixed-denomination formatter.

        If neither this method nor fractionDigits() is invoked, the default value will be 2.

      • fractionGroups

        public BtcFormat.Builder fractionGroups​(int... val)
        Specify the sizes of a variable number of optional decimal-place groups in the fraction part of formatted values. A group of each specified size will be used in addition to all previously applied decimal places only if doing so is useful for expressing precision. The size of each group is limited to a maximum precision of satoshis.

        If this method is not invoked, then the number of fractional decimal places will be limited to the value passed to minimumFractionDigits, or 2 if that method is not invoked.

      • locale

        public BtcFormat.Builder locale​(java.util.Locale val)
        Specify the Locale for formatting and parsing. If this method is not invoked, then the runtime default locale will be used.

      • symbol

        public BtcFormat.Builder symbol​(java.lang.String val)
        Specify a currency symbol to be used in the denomination-unit indicators of formatted values. This method only sets the symbol, but does not cause it to be used. You must also invoke either style(SYMBOL), or else apply a custom pattern that includes a single currency-sign character by invoking either pattern(String) or localizedPattern(String).

        Specify only the base symbol. The appropriate prefix will be applied according to the denomination of formatted and parsed values.

      • code

        public BtcFormat.Builder code​(java.lang.String val)
        Specify a custom currency code to be used in the denomination-unit indicators of formatted values. This method only sets the code, but does not cause it to be used. You must also invoke either style(CODE), or else apply a custom pattern that includes a double currency-sign character by invoking either pattern(String) or localizedPattern(String).

        Specify only the base code. The appropriate prefix will be applied according to the denomination of formatted and parsed values.

      • pattern

        public BtcFormat.Builder pattern​(java.lang.String val)
        Use the given pattern when formatting and parsing. The format of this pattern is identical to that used by the DecimalFormat class.

        If the pattern lacks a negative subpattern, then the formatter will indicate negative values by placing a minus sign immediately preceding the number part of formatted values.

        Note that while the pattern format specified by the DecimalFormat class includes a mechanism for setting the number of fractional decimal places, that part of the pattern is ignored. Instead, use the fractionDigits(int), minimumFractionDigits(int) and fractionGroups(int...) methods.

        Warning: if you set a pattern that includes a currency-sign for a fixed-denomination formatter that uses a non-standard scale, then an exception will be raised when you try to format a value. The standard scales include all for which a metric prefix exists from micro to mega.

        Note that by applying a pattern you override the configured formatting style of BtcAutoFormat instances.

      • localizedPattern

        public BtcFormat.Builder localizedPattern​(java.lang.String val)
        Use the given localized-pattern for formatting and parsing. The format of this pattern is identical to the patterns used by the DecimalFormat class.

        The pattern is localized according to the locale of the BtcFormat instance, the symbols for which can be examined by inspecting the DecimalFormatSymbols object returned by BtcFormat.symbols(). So, for example, if you are in Germany, then the non-localized pattern of 

        "#,##0.###"
        would be localized as 
        "#.##0,###"

        If the pattern lacks a negative subpattern, then the formatter will indicate negative values by placing a minus sign immediately preceding the number part of formatted values.

        Note that while the pattern format specified by the DecimalFormat class includes a mechanism for setting the number of fractional decimal places, that part of the pattern is ignored. Instead, use the fractionDigits(int), minimumFractionDigits(int) and fractionGroups(int...) methods.

        Warning: if you set a pattern that includes a currency-sign for a fixed-denomination formatter that uses a non-standard scale, then an exception will be raised when you try to format a value. The standard scales include all for which a metric prefix exists from micro to mega.

        Note that by applying a pattern you override the configured formatting style of BtcAutoFormat instances.

      • build

        public BtcFormat build()
        Return a new BtcFormat instance. The object returned will be configured according to the state of this Builder instance at the time this method is invoked.