Package org.apache.tuweni.units.bigints

Interface UInt256Value<T extends UInt256Value<T>>

Type Parameters:
T - The concrete type of the value.
All Superinterfaces:
org.apache.tuweni.bytes.Bytes, org.apache.tuweni.bytes.Bytes32, Comparable<org.apache.tuweni.bytes.Bytes>
All Known Subinterfaces:
BytesUInt256Value<T>
All Known Implementing Classes:
BaseUInt256Value, Gas, UInt256, Wei
public interface UInt256Value<T extends UInt256Value<T>> extends org.apache.tuweni.bytes.Bytes32
Represents a 256-bit (32 bytes) unsigned integer value.

A UInt256Value is an unsigned integer value stored with 32 bytes, so whose value can range between 0 and 2^256-1.

This interface defines operations for value types with a 256-bit precision range. The methods provided by this interface take parameters of the same type (and also long. This provides type safety by ensuring calculations cannot mix different UInt256Value types.

Where only a pure numerical 256-bit value is required, UInt256 should be used.

It is strongly advised to extend BaseUInt256Value rather than implementing this interface directly. Doing so provides type safety in that quantities of different units cannot be mixed accidentally.

  • Field Summary

    Fields inherited from interface org.apache.tuweni.bytes.Bytes

    EMPTY

    Fields inherited from interface org.apache.tuweni.bytes.Bytes32

    SIZE, ZERO

  • Method Summary

    Modifier and Type
    Method
    Description
    T
    add(long value)
    Returns a value that is (this + value).
    T
    add(T value)
    Returns a value that is (this + value).
    default T
    addExact(long value)
    Returns a value that is (this + value).
    default T
    addExact(T value)
    Returns a value that is (this + value).
    T
    addMod(long value, long modulus)
    Returns a value equivalent to ((this + value) mod modulus).
    T
    addMod(long value, UInt256 modulus)
    Returns a value equivalent to ((this + value) mod modulus).
    T
    addMod(T value, UInt256 modulus)
    Returns a value equivalent to ((this + value) mod modulus).
    default T
    addSafe(long value)
    Returns a value that is (this + value), or MAX_VALUE if it overflows.
    default T
    addSafe(T value)
    Returns a value that is (this + value), or MAX_VALUE if it overflows.
    T
    divide(long value)
    Returns a value that is (this / value).
    T
    divide(T value)
    Returns a value that is (this / value).
    T
    divideCeil(long value)
    Returns a value that is ceiling(this / value).
    T
    divideCeil(T value)
    Returns a value that is ceiling(this / value).
    default boolean
    fitsInt()
    Returns true if the value can fit in an int.
    default boolean
    fitsInt(ByteOrder order)
    Returns true if the value can fit in an int according to the byte order.
    default boolean
    fitsLong()
    Returns true if the value can fit in a long.
    default boolean
    fitsLong(ByteOrder order)
    Returns true if the value can fit in a long.
    default boolean
    greaterOrEqualThan(UInt256Value<T> other)
    Returns true if this value is greater or equal than the other one
    default boolean
    greaterThan(UInt256Value<T> other)
    Returns true if this value is greater than the other one
    default int
    intValue()
    Provides this value as an int.
    default boolean
    lessOrEqualThan(UInt256Value<T> other)
    Returns true if this value is less or equal than the other one
    default boolean
    lessThan(UInt256Value<T> other)
    Returns true if this value is less than the other one
    T
    max()
    Return the max value for this type.
    T
    mod(long modulus)
    Returns a value that is (this mod modulus).
    T
    mod(UInt256 modulus)
    Returns a value that is (this mod modulus).
    T
    mod0(long modulus)
    Returns a value that is (this mod modulus), or 0 if modulus is 0.
    T
    mod0(UInt256 modulus)
    Returns a value that is (this mod modulus), or 0 if modulus is 0.
    T
    multiply(long value)
    Returns a value that is (this * value).
    T
    multiply(T value)
    Returns a value that is (this * value).
    T
    multiplyMod(long value, long modulus)
    Returns a value that is ((this * value) mod modulus).
    T
    multiplyMod(long value, UInt256 modulus)
    Returns a value that is ((this * value) mod modulus).
    T
    multiplyMod(T value, UInt256 modulus)
    Returns a value that is ((this * value) mod modulus).
    default T
    plus(long value)
    Returns a value that is (this + value).
    default T
    plus(T value)
    Returns a value that is (this + value).
    T
    pow(long exponent)
    Returns a value that is (this<sup>exponent</sup> mod 2<sup>256</sup>)
    T
    pow(UInt256 exponent)
    Returns a value that is (this<sup>exponent</sup> mod 2<sup>256</sup>)
    T
    subtract(long value)
    Returns a value that is (this - value).
    T
    subtract(T value)
    Returns a value that is (this - value).
    default T
    subtractExact(long value)
    Returns a value that is (this - value).
    default T
    subtractExact(T value)
    Returns a value that is (this - value).
    default BigInteger
    toBigInteger()
    The BigInteger corresponding to interpreting these bytes as an unsigned integer.
    default BigInteger
    toBigInteger(ByteOrder order)
    The BigInteger corresponding to interpreting these bytes as an unsigned integer.
    org.apache.tuweni.bytes.Bytes32
    toBytes()
    Provides the value as bytes.
    default String
    toDecimalString()
    Returns the decimal representation of this value as a String.
    default int
    toInt(ByteOrder order)
     
    default long
    toLong(ByteOrder order)
     
    org.apache.tuweni.bytes.Bytes
    toMinimalBytes()
    Provides the value as bytes without any leading zero bytes.
    default BigInteger
    toSignedBigInteger()
    The BigInteger corresponding to interpreting these bytes as a two's-complement signed integer.
    default BigInteger
    toSignedBigInteger(ByteOrder order)
    The BigInteger corresponding to interpreting these bytes as a two's-complement signed integer.
    UInt256
    toUInt256()
    Convert this value to a UInt256.

    Methods inherited from interface org.apache.tuweni.bytes.Bytes

    and, and, appendHexTo, appendTo, appendTo, bitLength, commonPrefix, commonPrefixLength, compareTo, copyTo, copyTo, get, getInt, getInt, getLong, getLong, hasLeadingZero, hasLeadingZeroByte, isEmpty, isZero, not, numberOfLeadingZeroBytes, numberOfLeadingZeros, numberOfTrailingZeroBytes, or, or, reverse, shiftLeft, shiftRight, slice, slice, toArray, toArray, toArrayUnsafe, toBase64String, toEllipsisHexString, toFastHex, toHexString, toInt, toLong, toQuantityHexString, toShortHexString, toString, toUnprefixedHexString, toUnsignedBigInteger, toUnsignedBigInteger, trimLeadingZeros, trimTrailingZeros, update, xor, xor

    Methods inherited from interface org.apache.tuweni.bytes.Bytes32

    and, copy, mutableCopy, not, or, shiftLeft, shiftRight, size, xor

  • Method Details

    • add

      T add(T value)
      Returns a value that is (this + value).
      Parameters:
      value - The amount to be added to this value.
      Returns:
      this + value

    • plus

      default T plus(T value)
      Returns a value that is (this + value).

      This notation can be used in Kotlin with the + operator.

      Parameters:
      value - The amount to be added to this value.
      Returns:
      this + value

    • plus

      default T plus(long value)
      Returns a value that is (this + value).

      This notation can be used in Kotlin with the + operator.

      Parameters:
      value - The amount to be added to this value.
      Returns:
      this + value

    • addExact

      default T addExact(T value)
      Returns a value that is (this + value).
      Parameters:
      value - the amount to be added to this value
      Returns:
      this + value
      Throws:
      ArithmeticException - if the result of the addition overflows

    • addSafe

      default T addSafe(T value)
      Returns a value that is (this + value), or MAX_VALUE if it overflows.
      Parameters:
      value - the amount to be added to this value
      Returns:
      this + value or UInt256.MAX

    • add

      T add(long value)
      Returns a value that is (this + value).
      Parameters:
      value - The amount to be added to this value.
      Returns:
      this + value

    • addExact

      default T addExact(long value)
      Returns a value that is (this + value).
      Parameters:
      value - the amount to be added to this value
      Returns:
      this + value
      Throws:
      ArithmeticException - if the result of the addition overflows

    • addSafe

      default T addSafe(long value)
      Returns a value that is (this + value), or MAX_VALUE if it overflows.
      Parameters:
      value - the amount to be added to this value
      Returns:
      this + value or UInt256.MAX

    • addMod

      T addMod(T value, UInt256 modulus)
      Returns a value equivalent to ((this + value) mod modulus).
      Parameters:
      value - The amount to be added to this value.
      modulus - The modulus.
      Returns:
      (this + value) mod modulus
      Throws:
      ArithmeticException - modulus == 0.

    • addMod

      T addMod(long value, UInt256 modulus)
      Returns a value equivalent to ((this + value) mod modulus).
      Parameters:
      value - The amount to be added to this value.
      modulus - The modulus.
      Returns:
      (this + value) mod modulus
      Throws:
      ArithmeticException - modulus == 0.

    • addMod

      T addMod(long value, long modulus)
      Returns a value equivalent to ((this + value) mod modulus).
      Parameters:
      value - The amount to be added to this value.
      modulus - The modulus.
      Returns:
      (this + value) mod modulus
      Throws:
      ArithmeticException - modulus ≤ 0.

    • subtract

      T subtract(T value)
      Returns a value that is (this - value).
      Parameters:
      value - The amount to be subtracted from this value.
      Returns:
      this - value

    • subtractExact

      default T subtractExact(T value)
      Returns a value that is (this - value).
      Parameters:
      value - the amount to be subtracted to this value
      Returns:
      this - value
      Throws:
      ArithmeticException - if the result of the addition overflows

    • subtract

      T subtract(long value)
      Returns a value that is (this - value).
      Parameters:
      value - The amount to be subtracted from this value.
      Returns:
      this - value

    • subtractExact

      default T subtractExact(long value)
      Returns a value that is (this - value).
      Parameters:
      value - the amount to be subtracted to this value
      Returns:
      this - value
      Throws:
      ArithmeticException - if the result of the addition overflows

    • max

      T max()
      Return the max value for this type.

      The default implementation of this method returns a value obtained from calling the concrete type constructor with an argument of UInt256.MAX_VALUE. Most implementations will want to override this method to instead return a static constant.

      Returns:
      The max value for this type.

    • multiply

      T multiply(T value)
      Returns a value that is (this * value).
      Parameters:
      value - The amount to multiply this value by.
      Returns:
      this * value

    • multiply

      T multiply(long value)
      Returns a value that is (this * value).
      Parameters:
      value - The amount to multiply this value by.
      Returns:
      this * value
      Throws:
      ArithmeticException - value < 0.

    • multiplyMod

      T multiplyMod(T value, UInt256 modulus)
      Returns a value that is ((this * value) mod modulus).
      Parameters:
      value - The amount to multiply this value by.
      modulus - The modulus.
      Returns:
      (this * value) mod modulus
      Throws:
      ArithmeticException - value < 0 or modulus == 0.

    • multiplyMod

      T multiplyMod(long value, UInt256 modulus)
      Returns a value that is ((this * value) mod modulus).
      Parameters:
      value - The amount to multiply this value by.
      modulus - The modulus.
      Returns:
      (this * value) mod modulus
      Throws:
      ArithmeticException - value < 0 or modulus == 0.

    • multiplyMod

      T multiplyMod(long value, long modulus)
      Returns a value that is ((this * value) mod modulus).
      Parameters:
      value - The amount to multiply this value by.
      modulus - The modulus.
      Returns:
      (this * value) mod modulus
      Throws:
      ArithmeticException - value < 0 or modulus ≤ 0.

    • divide

      T divide(T value)
      Returns a value that is (this / value).
      Parameters:
      value - The amount to divide this value by.
      Returns:
      this / value
      Throws:
      ArithmeticException - value == 0.

    • divide

      T divide(long value)
      Returns a value that is (this / value).
      Parameters:
      value - The amount to divide this value by.
      Returns:
      this / value
      Throws:
      ArithmeticException - value ≤ 0.

    • divideCeil

      T divideCeil(T value)
      Returns a value that is ceiling(this / value).
      Parameters:
      value - The amount to divide this value by.
      Returns:
      this / value + ( this % value == 0 ? 0 : 1)
      Throws:
      ArithmeticException - value == 0.

    • divideCeil

      T divideCeil(long value)
      Returns a value that is ceiling(this / value).
      Parameters:
      value - The amount to divide this value by.
      Returns:
      this / value + ( this % value == 0 ? 0 : 1)
      Throws:
      ArithmeticException - value == 0.

    • pow

      T pow(UInt256 exponent)
      Returns a value that is (this<sup>exponent</sup> mod 2<sup>256</sup>)

      This calculates an exponentiation over the modulus of 2^256.

      Note that exponent is an UInt256 rather than of the type T.

      Parameters:
      exponent - The exponent to which this value is to be raised.
      Returns:
      this<sup>exponent</sup> mod 2<sup>256</sup>

    • pow

      T pow(long exponent)
      Returns a value that is (this<sup>exponent</sup> mod 2<sup>256</sup>)

      This calculates an exponentiation over the modulus of 2^256.

      Parameters:
      exponent - The exponent to which this value is to be raised.
      Returns:
      this<sup>exponent</sup> mod 2<sup>256</sup>

    • mod

      T mod(UInt256 modulus)
      Returns a value that is (this mod modulus).
      Parameters:
      modulus - The modulus.
      Returns:
      this mod modulus.
      Throws:
      ArithmeticException - modulus == 0.

    • mod

      T mod(long modulus)
      Returns a value that is (this mod modulus).
      Parameters:
      modulus - The modulus.
      Returns:
      this mod modulus.
      Throws:
      ArithmeticException - modulus ≤ 0.

    • mod0

      T mod0(UInt256 modulus)
      Returns a value that is (this mod modulus), or 0 if modulus is 0.
      Parameters:
      modulus - The modulus.
      Returns:
      this mod modulus.

    • mod0

      T mod0(long modulus)
      Returns a value that is (this mod modulus), or 0 if modulus is 0.
      Parameters:
      modulus - The modulus.
      Returns:
      this mod modulus.

    • fitsInt

      default boolean fitsInt()
      Returns true if the value can fit in an int.
      Returns:
      True if this value fits a java int (i.e. is less or equal to Integer.MAX_VALUE).

    • fitsInt

      default boolean fitsInt(ByteOrder order)
      Returns true if the value can fit in an int according to the byte order.
      Parameters:
      order - the byte order, little or big endian
      Returns:
      True if this value fits a java int (i.e. is less or equal to Integer.MAX_VALUE).

    • intValue

      default int intValue()
      Provides this value as an int.
      Returns:
      This value as a java int assuming it is small enough to fit an int.
      Throws:
      ArithmeticException - If the value does not fit an int, that is if !fitsInt().

    • toInt

      default int toInt(ByteOrder order)
      Specified by:
      toInt in interface org.apache.tuweni.bytes.Bytes

    • toLong

      default long toLong(ByteOrder order)
      Specified by:
      toLong in interface org.apache.tuweni.bytes.Bytes

    • fitsLong

      default boolean fitsLong()
      Returns true if the value can fit in a long.
      Returns:
      True if this value fits a java long (i.e. is less or equal to Long.MAX_VALUE).

    • fitsLong

      default boolean fitsLong(ByteOrder order)
      Returns true if the value can fit in a long.
      Parameters:
      order - byte order, little or big endian
      Returns:
      True if this value fits a java long (i.e. is less or equal to Long.MAX_VALUE).

    • toUInt256

      UInt256 toUInt256()
      Convert this value to a UInt256.
      Returns:
      This value as a UInt256.

    • toBytes

      org.apache.tuweni.bytes.Bytes32 toBytes()
      Provides the value as bytes.
      Returns:
      The value as bytes.

    • toMinimalBytes

      org.apache.tuweni.bytes.Bytes toMinimalBytes()
      Provides the value as bytes without any leading zero bytes.
      Returns:
      The value as bytes without any leading zero bytes.

    • greaterThan

      default boolean greaterThan(UInt256Value<T> other)
      Returns true if this value is greater than the other one
      Parameters:
      other - the other value being compared
      Returns:
      true if this value is greater than the other one, false otherwise

    • greaterOrEqualThan

      default boolean greaterOrEqualThan(UInt256Value<T> other)
      Returns true if this value is greater or equal than the other one
      Parameters:
      other - the other value being compared
      Returns:
      true if this value is greater or equal than the other one, false otherwise

    • lessThan

      default boolean lessThan(UInt256Value<T> other)
      Returns true if this value is less than the other one
      Parameters:
      other - the other value being compared
      Returns:
      true if this value is less than the other one, false otherwise

    • lessOrEqualThan

      default boolean lessOrEqualThan(UInt256Value<T> other)
      Returns true if this value is less or equal than the other one
      Parameters:
      other - the other value being compared
      Returns:
      true if this value is less or equal than the other one, false otherwise

    • toDecimalString

      default String toDecimalString()
      Returns the decimal representation of this value as a String.
      Returns:
      the decimal representation of this value as a String.

    • toSignedBigInteger

      default BigInteger toSignedBigInteger()
      The BigInteger corresponding to interpreting these bytes as a two's-complement signed integer.
      Returns:
      A BigInteger corresponding to interpreting these bytes as a two's-complement signed integer.

    • toSignedBigInteger

      default BigInteger toSignedBigInteger(ByteOrder order)
      The BigInteger corresponding to interpreting these bytes as a two's-complement signed integer.
      Parameters:
      order - The byte-order for decoding the integer.
      Returns:
      A BigInteger corresponding to interpreting these bytes as a two's-complement signed integer.

    • toBigInteger

      default BigInteger toBigInteger()
      The BigInteger corresponding to interpreting these bytes as an unsigned integer.
      Specified by:
      toBigInteger in interface org.apache.tuweni.bytes.Bytes
      Returns:
      A positive (or zero) BigInteger corresponding to interpreting these bytes as an unsigned integer.

    • toBigInteger

      default BigInteger toBigInteger(ByteOrder order)
      The BigInteger corresponding to interpreting these bytes as an unsigned integer.
      Specified by:
      toBigInteger in interface org.apache.tuweni.bytes.Bytes
      Parameters:
      order - The byte-order for decoding the integer.
      Returns:
      A positive (or zero) BigInteger corresponding to interpreting these bytes as an unsigned integer.