Units

Getting started

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.

Java API

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.

Creating Uints

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");

UInt operations

Uints are immutable, so all operations create a new object as the result of the operation.

Arithmetic operations

Adding and subtracting

• add(other)
• substract(other)

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.

• addExact(other)
• subtractExact(other)

Multiplying and dividing

• multiply(other)
• divide(other)

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

Modulus

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.

Power

The method pow(exponent) returns a value that is `value^exponent mod 2^256.

Boolean operations

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.

Shifting bytes

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.

Your own UInt class

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);
  }
}