Status | |
---|---|
Stability | stable |
Component Type | library |
Apache Tuweni provides support for manipulating unsigned integers and base Ethereum currencies.
To get started, install the units
library.
With Maven:
<dependency> <groupId>org.apache.tuweni</groupId> <artifactId>units</artifactId> <version>2.3.1</version> <!-- replace with latest release --> </dependency>
Or using Gradle:
implementation("org.apache.tuweni:units:2.3.1") // replace with latest release
The units library revolves mainly around the Uint256
, Uint384
and Uint64
interfaces.
This tutorial goes over the main uses of Uint256
- you can apply the same behaviors over to Uint384
, Uint64
or Uint32
.
It will also touch on Wei
and Gas
.
NOTE: We are going to use the UInt256
class for all examples, but the same behaviors are possible with the UInt384
, UInt64
, UInt32
classes.
We refer to those classes as UInt
.
valueOf
You can initialize a UInt
with the static method valueOf
, with an integer, a long, or a BigInteger object. This only accepts positive values.
// from an int UInt256 value = UInt256.valueOf(42); // from a long UInt256 value = UInt256.valueOf(42L); // from a BigInteger UInt256 value = UInt256.valueOf(BigInteger.ONE);
fromBytes
You can initialize a UInt
from a Bytes
object, using the fromBytes
method.
UInt256 value = UInt256.fromBytes(Bytes.wrap(new byte[] {0x01, 0x02, 0x03}));
fromHexString
You can initialize a UInt
from a string representing a hexadecimal encoding of bytes, with an optional prefix of 0x
.
UInt256 value = UInt256.fromHexString("0xdeadbeef");
Uints
are immutable, so all operations create a new object as the result of the operation.
Since these are bound integers, they will overflow and underflow if the operation returns a value outside the boundaries - for a Uint256
, 0 to 2^256.
For this reason, the API also contains exact
methods that throw exceptions if the operations overflows or underflows.
Additionally, the method divideCeil(other)
divides integers but returns the ceiling of the rounding.
UInt256 result = UInt256.valueOf(12L).divide(UInt256.valueOf(5L)); // returns 2 UInt256 resultCeiling = UInt256.valueOf(12L).divideCeil(UInt256.valueOf(5L)); // returns 3
You can use the method mod(divisor)
to get the modulus of the value by the divisor.
The method mod0
is more forgiving - if you divide by zero, it will return zero instead of throwing an exception.
The method pow(exponent)
returns a value that is `value^exponent mod 2^256.
You can use the following methods to perform boolean operations:
not()
: bit-wise NOT of this value.and(other)
: bit-wise AND of this value and the supplied value.or(other)
: bit-wise OR of this value and the supplied value.xor(other)
: bit-wise XOR of this value and the supplied value.You can shift right and left the bits of the underlying bytes object by a given distance. This is equivalent to the <<<
or >>>
operators in Java.
You can create your own domain class based off the Uints
. A good example is the Wei class
.
You will need to provide the super constructor the constructor of your class.
public final class Wei extends BaseUInt256Value<Wei> { private Wei(UInt256 bytes) { super(bytes, Wei::new); } }