Class Coin

  • All Implemented Interfaces:
    java.lang.Comparable<Coin>, Monetary

    public final class Coin
    extends java.lang.Object
    implements Monetary, java.lang.Comparable<Coin>
    Represents a monetary Bitcoin value. This class is immutable and should be treated as a Java Value-based class. We recommend using the Coin class wherever possible to represent Bitcoin monetary values. If you have existing code that uses other numeric types and need to convert there are conversion methods.

    Internally Coin is implemented as a long (see value) that represents a number of satoshis. It can also be considered a fixed-point number of bitcoins.

    To create a Coin from an integer number of satoshis, use ofSat(long). To convert to a long number of satoshis use toSat(). (You can also use valueOf(long), getValue() or value.)

    To create a Coin from a decimal number of bitcoins, use ofBtc(BigDecimal). To convert to a BigDecimal of bitcoins use toBtc(). (Performing fixed-point conversion, these methods essentially multiply or divide by Coin.COIN.toSat().)

    Never ever use float or double to represent monetary values.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int BYTES
      Number of bytes to store this amount.
      static Coin CENT
      0.01 Bitcoins.
      static Coin COIN
      One Bitcoin.
      static Coin FIFTY_COINS  
      static Coin MICROCOIN
      0.000001 Bitcoins, also known as 1 µBTC or 1 uBTC.
      static Coin MILLICOIN
      0.001 Bitcoins, also known as 1 mBTC.
      static Coin NEGATIVE_SATOSHI
      Represents a monetary value of minus one satoshi.
      static Coin SATOSHI
      A satoshi is the smallest unit that can be transferred.
      static int SMALLEST_UNIT_EXPONENT
      Number of decimals for one Bitcoin.
      long value
      The number of satoshis of this monetary value.
      static Coin ZERO
      Zero Bitcoins.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Coin add​(Coin value)  
      static long btcToSatoshi​(java.math.BigDecimal coins)
      Convert a decimal amount of BTC into satoshis.
      int compareTo​(Coin other)  
      Coin div​(int divisor)
      Alias for divide
      Coin div​(long divisor)
      Alias for divide
      Coin divide​(long divisor)  
      long divide​(Coin divisor)  
      Coin[] divideAndRemainder​(long divisor)  
      boolean equals​(java.lang.Object o)  
      long getValue()
      Returns the number of satoshis of this monetary value.
      int hashCode()  
      boolean isGreaterThan​(Coin other)
      Returns true if the monetary value represented by this instance is greater than that of the given other Coin, otherwise false.
      boolean isLessThan​(Coin other)
      Returns true if the monetary value represented by this instance is less than that of the given other Coin, otherwise false.
      boolean isNegative()
      Returns true if and only if this instance represents a monetary value less than zero, otherwise false.
      boolean isPositive()
      Returns true if and only if this instance represents a monetary value greater than zero, otherwise false.
      boolean isZero()
      Returns true if and only if this instance represents zero monetary value, otherwise false.
      long longValue()
      Returns the number of satoshis of this monetary value.
      Coin minus​(Coin value)
      Alias for subtract
      Coin multiply​(long factor)  
      Coin negate()  
      static Coin ofBtc​(java.math.BigDecimal coins)
      Create a Coin from a decimal amount of BTC.
      static Coin ofSat​(long satoshis)
      Create a Coin from a long integer number of satoshis.
      static Coin parseCoin​(java.lang.String str)
      Create a Coin by parsing a String amount expressed in "the way humans are used to".
      static Coin parseCoinInexact​(java.lang.String str)
      Create a Coin by parsing a String amount expressed in "the way humans are used to".
      Coin plus​(Coin value)
      Alias for add
      static Coin read​(java.nio.ByteBuffer buf)
      Read a Coin amount from the given buffer as 8 bytes in little-endian order.
      static java.math.BigDecimal satoshiToBtc​(long satoshis)
      Convert an amount in satoshis to an amount in BTC.
      byte[] serialize()
      Allocates a byte array and serializes the amount.
      Coin shiftLeft​(int n)  
      Coin shiftRight​(int n)  
      int signum()  
      int smallestUnitExponent()
      Returns the absolute value of exponent of the value of a "smallest unit" in scientific notation.
      Coin subtract​(Coin value)  
      Coin times​(int factor)
      Alias for multiply
      Coin times​(long factor)
      Alias for multiply
      java.math.BigDecimal toBtc()
      Convert to number of bitcoin (in BTC)
      java.lang.String toFriendlyString()
      Returns the value as a 0.12 type string.
      java.lang.String toPlainString()
      Returns the value as a plain string denominated in BTC.
      long toSat()
      Convert to number of satoshis
      java.lang.String toString()  
      static Coin valueOf​(int coins, int cents)
      Create a Coin from an amount expressed in "the way humans are used to".
      static Coin valueOf​(long satoshis)
      Create a Coin from a long integer number of satoshis.
      java.nio.ByteBuffer write​(java.nio.ByteBuffer buf)
      Write the amount into the given buffer as 8 bytes in little-endian order.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • SMALLEST_UNIT_EXPONENT

        public static final int SMALLEST_UNIT_EXPONENT
        Number of decimals for one Bitcoin. This constant is useful for quick adapting to other coins because a lot of constants derive from it.
        See Also:
        Constant Field Values
      • ZERO

        public static final Coin ZERO
        Zero Bitcoins.
      • COIN

        public static final Coin COIN
        One Bitcoin.
      • CENT

        public static final Coin CENT
        0.01 Bitcoins. This unit is not really used much.
      • MILLICOIN

        public static final Coin MILLICOIN
        0.001 Bitcoins, also known as 1 mBTC.
      • MICROCOIN

        public static final Coin MICROCOIN
        0.000001 Bitcoins, also known as 1 µBTC or 1 uBTC.
      • SATOSHI

        public static final Coin SATOSHI
        A satoshi is the smallest unit that can be transferred. 100 million of them fit into a Bitcoin.
      • FIFTY_COINS

        public static final Coin FIFTY_COINS
      • NEGATIVE_SATOSHI

        public static final Coin NEGATIVE_SATOSHI
        Represents a monetary value of minus one satoshi.
      • BYTES

        public static final int BYTES
        Number of bytes to store this amount.
        See Also:
        Constant Field Values
      • value

        public final long value
        The number of satoshis of this monetary value.
    • Method Detail

      • valueOf

        public static Coin valueOf​(long satoshis)
        Create a Coin from a long integer number of satoshis.
        Parameters:
        satoshis - number of satoshis
        Returns:
        Coin object containing value in satoshis
      • read

        public static Coin read​(java.nio.ByteBuffer buf)
                         throws java.nio.BufferUnderflowException
        Read a Coin amount from the given buffer as 8 bytes in little-endian order.
        Parameters:
        buf - buffer to read from
        Returns:
        read amount
        Throws:
        java.nio.BufferUnderflowException - if the read value extends beyond the remaining bytes of the buffer
      • smallestUnitExponent

        public int smallestUnitExponent()
        Description copied from interface: Monetary
        Returns the absolute value of exponent of the value of a "smallest unit" in scientific notation. For Bitcoin, a satoshi is worth 1E-8 so this would be 8.
        Specified by:
        smallestUnitExponent in interface Monetary
      • getValue

        public long getValue()
        Returns the number of satoshis of this monetary value.
        Specified by:
        getValue in interface Monetary
      • valueOf

        public static Coin valueOf​(int coins,
                                   int cents)
        Create a Coin from an amount expressed in "the way humans are used to".
        Parameters:
        coins - Number of bitcoins
        cents - Number of bitcents (0.01 bitcoin)
        Returns:
        Coin object containing value in satoshis
      • btcToSatoshi

        public static long btcToSatoshi​(java.math.BigDecimal coins)
                                 throws java.lang.ArithmeticException
        Convert a decimal amount of BTC into satoshis.
        Parameters:
        coins - number of coins
        Returns:
        number of satoshis
        Throws:
        java.lang.ArithmeticException - if value has too much precision or will not fit in a long
      • satoshiToBtc

        public static java.math.BigDecimal satoshiToBtc​(long satoshis)
        Convert an amount in satoshis to an amount in BTC.
        Parameters:
        satoshis - number of satoshis
        Returns:
        number of bitcoins (in BTC)
      • ofBtc

        public static Coin ofBtc​(java.math.BigDecimal coins)
                          throws java.lang.ArithmeticException
        Create a Coin from a decimal amount of BTC.
        Parameters:
        coins - number of coins (in BTC)
        Returns:
        Coin object containing value in satoshis
        Throws:
        java.lang.ArithmeticException - if value has too much precision or will not fit in a long
      • ofSat

        public static Coin ofSat​(long satoshis)
        Create a Coin from a long integer number of satoshis.
        Parameters:
        satoshis - number of satoshis
        Returns:
        Coin object containing value in satoshis
      • parseCoin

        public static Coin parseCoin​(java.lang.String str)
        Create a Coin by parsing a String amount expressed in "the way humans are used to".
        Parameters:
        str - string in a format understood by BigDecimal(String), for example "0", "1", "0.10", * "1.23E3", "1234.5E-5".
        Returns:
        Coin object containing value in satoshis
        Throws:
        java.lang.IllegalArgumentException - if you try to specify fractional satoshis, or a value out of range.
      • parseCoinInexact

        public static Coin parseCoinInexact​(java.lang.String str)
        Create a Coin by parsing a String amount expressed in "the way humans are used to". The amount is cut to satoshi precision.
        Parameters:
        str - string in a format understood by BigDecimal(String), for example "0", "1", "0.10", * "1.23E3", "1234.5E-5".
        Returns:
        Coin object containing value in satoshis
        Throws:
        java.lang.IllegalArgumentException - if you try to specify a value out of range.
      • plus

        public Coin plus​(Coin value)
        Alias for add
      • subtract

        public Coin subtract​(Coin value)
      • minus

        public Coin minus​(Coin value)
        Alias for subtract
      • multiply

        public Coin multiply​(long factor)
      • times

        public Coin times​(long factor)
        Alias for multiply
      • times

        public Coin times​(int factor)
        Alias for multiply
      • divide

        public Coin divide​(long divisor)
      • div

        public Coin div​(long divisor)
        Alias for divide
      • div

        public Coin div​(int divisor)
        Alias for divide
      • divideAndRemainder

        public Coin[] divideAndRemainder​(long divisor)
      • divide

        public long divide​(Coin divisor)
      • isPositive

        public boolean isPositive()
        Returns true if and only if this instance represents a monetary value greater than zero, otherwise false.
      • isNegative

        public boolean isNegative()
        Returns true if and only if this instance represents a monetary value less than zero, otherwise false.
      • isZero

        public boolean isZero()
        Returns true if and only if this instance represents zero monetary value, otherwise false.
      • isGreaterThan

        public boolean isGreaterThan​(Coin other)
        Returns true if the monetary value represented by this instance is greater than that of the given other Coin, otherwise false.
      • isLessThan

        public boolean isLessThan​(Coin other)
        Returns true if the monetary value represented by this instance is less than that of the given other Coin, otherwise false.
      • shiftLeft

        public Coin shiftLeft​(int n)
      • shiftRight

        public Coin shiftRight​(int n)
      • signum

        public int signum()
        Specified by:
        signum in interface Monetary
      • negate

        public Coin negate()
      • longValue

        public long longValue()
        Returns the number of satoshis of this monetary value. It's deprecated in favour of accessing value directly.
      • toSat

        public long toSat()
        Convert to number of satoshis
        Returns:
        decimal number of satoshis
      • toBtc

        public java.math.BigDecimal toBtc()
        Convert to number of bitcoin (in BTC)
        Returns:
        decimal number of bitcoin (in BTC)
      • write

        public java.nio.ByteBuffer write​(java.nio.ByteBuffer buf)
                                  throws java.nio.BufferOverflowException
        Write the amount into the given buffer as 8 bytes in little-endian order.
        Parameters:
        buf - buffer to write into
        Returns:
        the buffer
        Throws:
        java.nio.BufferOverflowException - if the value doesn't fit the remaining buffer
      • serialize

        public byte[] serialize()
        Allocates a byte array and serializes the amount.
        Returns:
        serialized amount
      • toFriendlyString

        public java.lang.String toFriendlyString()
        Returns the value as a 0.12 type string. More digits after the decimal place will be used if necessary, but two will always be present.
      • toPlainString

        public java.lang.String toPlainString()

        Returns the value as a plain string denominated in BTC. The result is unformatted with no trailing zeroes. For instance, a value of 150000 satoshis gives an output string of "0.0015" BTC

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • hashCode

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

        public int compareTo​(Coin other)
        Specified by:
        compareTo in interface java.lang.Comparable<Coin>