units / org.apache.tuweni.units.bigints / UInt256Value

UInt256Value

interface UInt256Value<T : UInt256Value<T>> : Comparable<T> (source)

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.

Parameters

- The concrete type of the value.

Functions

add

abstract fun add(value: T): T
abstract fun add(value: Long): T

Returns a value that is (this + value).

addExact

open fun addExact(value: T): T
open fun addExact(value: Long): T

Returns a value that is (this + value).

addMod

abstract fun addMod(value: T, modulus: UInt256): T
abstract fun addMod(value: Long, modulus: UInt256): T
abstract fun addMod(value: Long, modulus: Long): T

Returns a value equivalent to ((this + value) mod modulus).

bitLength

open fun bitLength(): Int

divide

abstract fun divide(value: T): T
abstract fun divide(value: Long): T

Returns a value that is (this / value).

divideCeil

abstract fun divideCeil(value: T): T
abstract fun divideCeil(value: Long): T

Returns a value that is ceiling(this / value).

fitsInt

open fun fitsInt(): Boolean

fitsLong

open fun fitsLong(): Boolean

intValue

open fun intValue(): Int

isZero

open fun isZero(): Boolean

mod

abstract fun mod(modulus: UInt256): T
abstract fun mod(modulus: Long): T

Returns a value that is (this mod modulus).

mod0

abstract fun mod0(modulus: UInt256): T
abstract fun mod0(modulus: Long): T

Returns a value that is (this mod modulus), or 0 if modulus is 0.

multiply

abstract fun multiply(value: T): T
abstract fun multiply(value: Long): T

Returns a value that is (this * value).

multiplyMod

abstract fun multiplyMod(value: T, modulus: UInt256): T
abstract fun multiplyMod(value: Long, modulus: UInt256): T
abstract fun multiplyMod(value: Long, modulus: Long): T

Returns a value that is ((this * value) mod modulus).

numberOfLeadingZeros

open fun numberOfLeadingZeros(): Int

plus

open fun plus(value: T): T
open fun plus(value: Long): T

Returns a value that is (this + value).

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

pow

abstract fun pow(exponent: UInt256): T

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.

abstract fun pow(exponent: Long): T

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

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

subtract

abstract fun subtract(value: T): T
abstract fun subtract(value: Long): T

Returns a value that is (this - value).

subtractExact

open fun subtractExact(value: T): T
open fun subtractExact(value: Long): T

Returns a value that is (this - value).

toBigInteger

open fun toBigInteger(): BigInteger

toBytes

abstract fun toBytes(): Bytes32

toHexString

open fun toHexString(): String

This value represented as an hexadecimal string.

Note that this representation includes all the 32 underlying bytes, no matter what the integer actually represents (in other words, it can have many leading zeros). For a shorter representation that don't include leading zeros, use #toShortHexString.

toLong

open fun toLong(): Long

toMinimalBytes

abstract fun toMinimalBytes(): Bytes

toShortHexString

open fun toShortHexString(): String

toUInt256

abstract fun toUInt256(): UInt256

Convert this value to a UInt256.

Inheritors

BaseUInt256Value

abstract class BaseUInt256Value<T : UInt256Value<T>> : UInt256Value<T>

Base class for UInt256Value.

This class is abstract as it is not meant to be used directly, but it has no abstract methods. As mentioned in UInt256Value, this is used to create strongly-typed type aliases of UInt256. In other words, this allow to "tag" numbers with the unit of what they represent for the type-system, which can help clarity, but also forbid mixing numbers that are mean to be of different units (the strongly-typed part).

This class implements UInt256Value, but also adds a few operations that take a UInt256 directly, for instance #multiply(UInt256). The rational is that multiplying a given quantity of something by a "raw" number is always meaningful, and return a new quantity of the same thing.

UInt256

class UInt256 : UInt256Value<UInt256>

An unsigned 256-bit precision number. This is a raw UInt256Value - a 256-bit precision unsigned number of no particular unit.