Package org.apache.tuweni.bytes

Interface Bytes

All Superinterfaces:

Comparable<Bytes>

All Known Subinterfaces:

Bytes32, Bytes48, MutableBytes, MutableBytes32, MutableBytes48

All Known Implementing Classes:

AbstractBytes, DelegatingBytes, DelegatingBytes32, DelegatingBytes48, DelegatingMutableBytes, MutableByteBufferWrappingBytes

public interface Bytes
extends Comparable<Bytes>

A value made of bytes.

This interface makes no thread-safety guarantee, and a Bytes value is generally not thread safe. However, specific implementations may be thread-safe. For instance, the value returned by copy() is guaranteed to be thread-safe as it is immutable.

Field Summary

Fields

Modifier and Type	Field	Description
static final Bytes	EMPTY	The empty value (with 0 bytes).

Method Summary

Modifier and Type	Method	Description
default Bytes	and(Bytes other)	Return a bit-wise AND of these bytes and the supplied bytes.
default <T extends MutableBytes> T	and(Bytes other, T result)	Calculate a bit-wise AND of these bytes and the supplied bytes.
default <T extends Appendable> T	appendHexTo(T appendable)	Append this value as a sequence of hexadecimal characters.
default void	appendTo(io.vertx.core.buffer.Buffer buffer)	Append the bytes of this value to the provided Vert.x Buffer.
default void	appendTo(ByteBuffer byteBuffer)	Append the bytes of this value to the ByteBuffer.
default int	bitLength()	Provides the number of bits following and including the highest-order ("leftmost") one-bit, or zero if all bits are zero.
default Bytes	commonPrefix(Bytes other)	Return a slice over the common prefix between this set of bytes and another.
default int	commonPrefixLength(Bytes other)	Return the number of bytes in common between this set of bytes and another.
default int	compareTo(Bytes b)
static Bytes	concatenate(List<Bytes> values)	Create a value containing the concatenation of the values provided.
static Bytes	concatenate(Bytes... values)	Create a value containing the concatenation of the values provided.
Bytes	copy()	Return a value equivalent to this one but guaranteed to 1) be deeply immutable (i.e.
default void	copyTo(MutableBytes destination)	Copy the bytes of this value to the provided mutable one, which must have the same size.
default void	copyTo(MutableBytes destination, int destinationOffset)	Copy the bytes of this value to the provided mutable one from a particular offset.
static Bytes	fromBase64String(CharSequence str)	Parse a base 64 string into a Bytes value.
static Bytes	fromHexString(CharSequence str)	Parse a hexadecimal string into a Bytes value.
static Bytes	fromHexString(CharSequence str, int destinationSize)	Parse a hexadecimal string into a Bytes value.
static Bytes	fromHexStringLenient(CharSequence str)	Parse a hexadecimal string into a Bytes value.
static Bytes	fromHexStringLenient(CharSequence str, int destinationSize)	Parse a hexadecimal string into a Bytes value of the provided size.
byte	get(int i)	Retrieve a byte in this value.
default int	getInt(int i)	Retrieve the 4 bytes starting at the provided index in this value as an integer.
default int	getInt(int i, ByteOrder order)	Retrieve the 4 bytes starting at the provided index in this value as an integer.
default long	getLong(int i)	Retrieves the 8 bytes starting at the provided index in this value as a long.
default long	getLong(int i, ByteOrder order)	Retrieves the 8 bytes starting at the provided index in this value as a long.
default boolean	hasLeadingZero()	Whether the bytes start with a zero bit value.
default boolean	hasLeadingZeroByte()	Whether the bytes start with a zero byte value.
default boolean	isEmpty()	Whether this value contains no bytes.
default boolean	isZero()	Whether this value has only zero bytes.
static Bytes	minimalBytes(long value)	Return the smallest bytes value whose bytes correspond to the provided long.
MutableBytes	mutableCopy()	Return a new mutable value initialized with the content of this value.
default Bytes	not()	Return a bit-wise NOT of these bytes.
default <T extends MutableBytes> T	not(T result)	Calculate a bit-wise NOT of these bytes.
default int	numberOfLeadingZeroBytes()	Provides the number of leading zero bytes of the value
default int	numberOfLeadingZeros()	Provides the number of zero bits preceding the highest-order ("leftmost") one-bit, or size() * 8 if all bits * are zero.
default int	numberOfTrailingZeroBytes()	Provides the number of trailing zero bytes of the value.
static Bytes	of(byte... bytes)	Create a value that contains the specified bytes in their specified order.
static Bytes	of(int... bytes)	Create a value that contains the specified bytes in their specified order.
static Bytes	ofUnsignedInt(long value)	Return a 4-byte value corresponding to the provided value interpreted as an unsigned int.
static Bytes	ofUnsignedInt(long value, ByteOrder order)	Return a 4-byte value corresponding to the provided value interpreted as an unsigned int.
static Bytes	ofUnsignedLong(long value)	Return an 8-byte value corresponding to the provided value interpreted as an unsigned long.
static Bytes	ofUnsignedLong(long value, ByteOrder order)	Return an 8-byte value corresponding to the provided value interpreted as an unsigned long.
static Bytes	ofUnsignedShort(int value)	Return a 2-byte value corresponding to the provided value interpreted as an unsigned short.
static Bytes	ofUnsignedShort(int value, ByteOrder order)	Return a 2-byte value corresponding to the provided value interpreted as an unsigned short.
default Bytes	or(Bytes other)	Return a bit-wise OR of these bytes and the supplied bytes.
default <T extends MutableBytes> T	or(Bytes other, T result)	Calculate a bit-wise OR of these bytes and the supplied bytes.
static Bytes	random(int size)	Generate random bytes.
static Bytes	random(int size, Random generator)	Generate random bytes.
static Bytes	repeat(byte b, int size)	Generate a bytes object filled with the same byte.
default Bytes	reverse()	Computes the reverse array of bytes of the current bytes.
static Bytes	secure(byte[] value)	Wrap the provided byte array as a Bytes value, encrypted in memory.
static Bytes	secure(byte[] value, int offset, int length)	Wrap a slice of a byte array as a Bytes value, encrypted in memory.
static Bytes32[]	segment(Bytes bytes)	Splits a Bytes object into Bytes32 objects.
default Bytes	shiftLeft(int distance)	Shift all bits in this value to the left.
default <T extends MutableBytes> T	shiftLeft(int distance, T result)	Shift all bits in this value to the left.
default Bytes	shiftRight(int distance)	Shift all bits in this value to the right.
default <T extends MutableBytes> T	shiftRight(int distance, T result)	Shift all bits in this value to the right.
int	size()	Provides the number of bytes this value represents.
default Bytes	slice(int i)	Create a new value representing (a view of) a slice of the bytes of this value.
Bytes	slice(int i, int length)	Create a new value representing (a view of) a slice of the bytes of this value.
default byte[]	toArray()	Extract the bytes of this value into a byte array.
default byte[]	toArray(ByteOrder byteOrder)	Extract the bytes of this value into a byte array.
default byte[]	toArrayUnsafe()	Get the bytes represented by this value as byte array.
default String	toBase64String()	Provides this value represented as base 64
default BigInteger	toBigInteger()	The BigInteger corresponding to interpreting these bytes as a two's-complement signed integer.
default BigInteger	toBigInteger(ByteOrder order)	The BigInteger corresponding to interpreting these bytes as a two's-complement signed integer.
default String	toEllipsisHexString()
default String	toFastHex(boolean prefix)
default String	toHexString()	Provides this value represented as hexadecimal, starting with "0x".
default int	toInt()	The value corresponding to interpreting these bytes as an integer.
default int	toInt(ByteOrder order)	The value corresponding to interpreting these bytes as an integer.
default long	toLong()	The value corresponding to interpreting these bytes as a long.
default long	toLong(ByteOrder order)	The value corresponding to interpreting these bytes as a long.
default String	toQuantityHexString()	Provides this value represented as a minimal hexadecimal string (without any leading zero, except if it's valued zero or empty, in which case it returns 0x0).
default String	toShortHexString()	Provides this value represented as a minimal hexadecimal string (without any leading zero)
String	toString()	Return the hexadecimal string representation of this value.
default String	toUnprefixedHexString()	Provides this value represented as hexadecimal, with no prefix
default BigInteger	toUnsignedBigInteger()	The BigInteger corresponding to interpreting these bytes as an unsigned integer.
default BigInteger	toUnsignedBigInteger(ByteOrder order)	The BigInteger corresponding to interpreting these bytes as an unsigned integer.
default Bytes	trimLeadingZeros()	Return a slice of representing the same value but without any leading zero bytes.
default Bytes	trimTrailingZeros()	Return a slice of representing the same value but without any trailing zero bytes.
default void	update(MessageDigest digest)	Update the provided message digest with the bytes of this value.
static Bytes	wrap(byte[] value)	Wrap the provided byte array as a Bytes value.
static Bytes	wrap(byte[] value, int offset, int length)	Wrap a slice of a byte array as a Bytes value.
static Bytes	wrap(List<Bytes> values)	Wrap a list of other values into a concatenated view.
static Bytes	wrap(Bytes... values)	Wrap a list of other values into a concatenated view.
static Bytes	wrapBuffer(io.vertx.core.buffer.Buffer buffer)	Wrap a full Vert.x Buffer as a Bytes value.
static Bytes	wrapBuffer(io.vertx.core.buffer.Buffer buffer, int offset, int size)	Wrap a slice of a Vert.x Buffer as a Bytes value.
static Bytes	wrapByteBuf(io.netty.buffer.ByteBuf byteBuf)	Wrap a full Netty ByteBuf as a Bytes value.
static Bytes	wrapByteBuf(io.netty.buffer.ByteBuf byteBuf, int offset, int size)	Wrap a slice of a Netty ByteBuf as a Bytes value.
static Bytes	wrapByteBuffer(ByteBuffer byteBuffer)	Wrap a full Java NIO ByteBuffer as a Bytes value.
static Bytes	wrapByteBuffer(ByteBuffer byteBuffer, int offset, int size)	Wrap a slice of a Java NIO ByteBuf as a Bytes value.
default Bytes	xor(Bytes other)	Return a bit-wise XOR of these bytes and the supplied bytes.
default <T extends MutableBytes> T	xor(Bytes other, T result)	Calculate a bit-wise XOR of these bytes and the supplied bytes.

Field Details

EMPTY

static final Bytes EMPTY

The empty value (with 0 bytes).

Method Details

wrap

static Bytes wrap(byte[] value)

Wrap the provided byte array as a Bytes value.

Note that value is not copied and thus any future update to value will be reflected in the returned value.

Parameters:

value - The value to wrap.

Returns:

A Bytes value wrapping value.

wrap

static Bytes wrap(byte[] value,
 int offset,
 int length)

Wrap a slice of a byte array as a Bytes value.

Note that value is not copied and thus any future update to value within the slice will be reflected in the returned value.

Parameters:

value - The value to wrap.

offset - The index (inclusive) in value of the first byte exposed by the returned value. In other words, you will have wrap(value, o, l).get(0) == value[o].

length - The length of the resulting value.

Returns:

A Bytes value that expose the bytes of value from offset (inclusive) to offset + length (exclusive).

Throws:

IndexOutOfBoundsException - if offset < 0 || (value.length > 0 && offset >= value.length).

IllegalArgumentException - if length < 0 || offset + length > value.length.

secure

static Bytes secure(byte[] value)

Wrap the provided byte array as a Bytes value, encrypted in memory.

Parameters:

value - The value to secure.

Returns:

A Bytes value securing value.

secure

static Bytes secure(byte[] value,
 int offset,
 int length)

Wrap a slice of a byte array as a Bytes value, encrypted in memory.

Parameters:

value - The value to secure.

offset - The index (inclusive) in value of the first byte exposed by the returned value. In other words, you will have wrap(value, o, l).get(0) == value[o].

length - The length of the resulting value.

Returns:

A Bytes value that holds securely the bytes of value from offset (inclusive) to offset + length (exclusive).

Throws:

IndexOutOfBoundsException - if offset < 0 || (value.length > 0 && offset >= value.length).

IllegalArgumentException - if length < 0 || offset + length > value.length.

wrap

static Bytes wrap(Bytes... values)

Wrap a list of other values into a concatenated view.

Note that the values are not copied and thus any future update to the values will be reflected in the returned value. If copying the inputs is desired, use concatenate(Bytes...).

Parameters:

values - The values to wrap.

Returns:

A value representing a view over the concatenation of all values.

Throws:

IllegalArgumentException - if the result overflows an int.

wrap

static Bytes wrap(List<Bytes> values)

Wrap a list of other values into a concatenated view.

Note that the values are not copied and thus any future update to the values will be reflected in the returned value. If copying the inputs is desired, use concatenate(Bytes...).

Parameters:

values - The values to wrap.

Returns:

A value representing a view over the concatenation of all values.

Throws:

IllegalArgumentException - if the result overflows an int.

concatenate

static Bytes concatenate(List<Bytes> values)

Create a value containing the concatenation of the values provided.

Parameters:

values - The values to copy and concatenate.

Returns:

A value containing the result of concatenating the value from values in their provided order.

Throws:

IllegalArgumentException - if the result overflows an int.

concatenate

static Bytes concatenate(Bytes... values)

Create a value containing the concatenation of the values provided.

Parameters:

values - The values to copy and concatenate.

Returns:

A value containing the result of concatenating the value from values in their provided order.

Throws:

IllegalArgumentException - if the result overflows an int.

wrapBuffer

static Bytes wrapBuffer(io.vertx.core.buffer.Buffer buffer)

Wrap a full Vert.x Buffer as a Bytes value.

Note that any change to the content of the buffer may be reflected in the returned value.

Parameters:

buffer - The buffer to wrap.

Returns:

A Bytes value.

wrapBuffer

static Bytes wrapBuffer(io.vertx.core.buffer.Buffer buffer,
 int offset,
 int size)

Wrap a slice of a Vert.x Buffer as a Bytes value.

Note that any change to the content of the buffer may be reflected in the returned value.

Parameters:

buffer - The buffer to wrap.

offset - The offset in buffer from which to expose the bytes in the returned value. That is, wrapBuffer(buffer, i, 1).get(0) == buffer.getByte(i).

size - The size of the returned value.

Returns:

A Bytes value.

Throws:

IndexOutOfBoundsException - if offset < 0 || (buffer.length() > 0 && offset >= buffer.length()).

IllegalArgumentException - if length < 0 || offset + length > buffer.length().

wrapByteBuf

static Bytes wrapByteBuf(io.netty.buffer.ByteBuf byteBuf)

Wrap a full Netty ByteBuf as a Bytes value.

Note that any change to the content of the byteBuf may be reflected in the returned value.

Parameters:

byteBuf - The ByteBuf to wrap.

Returns:

A Bytes value.

wrapByteBuf

static Bytes wrapByteBuf(io.netty.buffer.ByteBuf byteBuf,
 int offset,
 int size)

Wrap a slice of a Netty ByteBuf as a Bytes value.

Note that any change to the content of the buffer may be reflected in the returned value.

Parameters:

byteBuf - The ByteBuf to wrap.

offset - The offset in byteBuf from which to expose the bytes in the returned value. That is, wrapByteBuf(byteBuf, i, 1).get(0) == byteBuf.getByte(i).

size - The size of the returned value.

Returns:

A Bytes value.

Throws:

IndexOutOfBoundsException - if offset < 0 || (byteBuf.capacity() > 0 && offset >= byteBuf.capacity()).

IllegalArgumentException - if length < 0 || offset + length > byteBuf.capacity().

wrapByteBuffer

static Bytes wrapByteBuffer(ByteBuffer byteBuffer)

Wrap a full Java NIO ByteBuffer as a Bytes value.

Note that any change to the content of the byteBuf may be reflected in the returned value.

Parameters:

byteBuffer - The ByteBuffer to wrap.

Returns:

A Bytes value.

wrapByteBuffer

static Bytes wrapByteBuffer(ByteBuffer byteBuffer,
 int offset,
 int size)

Wrap a slice of a Java NIO ByteBuf as a Bytes value.

Note that any change to the content of the buffer may be reflected in the returned value.

Parameters:

byteBuffer - The ByteBuffer to wrap.

offset - The offset in byteBuffer from which to expose the bytes in the returned value. That is, wrapByteBuffer(byteBuffer, i, 1).get(0) == byteBuffer.getByte(i).

size - The size of the returned value.

Returns:

A Bytes value.

Throws:

IndexOutOfBoundsException - if offset < 0 || (byteBuffer.limit() > 0 && offset >= byteBuf.limit()).

IllegalArgumentException - if length < 0 || offset + length > byteBuffer.limit().

of

static Bytes of(byte... bytes)

Create a value that contains the specified bytes in their specified order.

Parameters:

bytes - The bytes that must compose the returned value.

Returns:

A value containing the specified bytes.

of

static Bytes of(int... bytes)

Create a value that contains the specified bytes in their specified order.

Parameters:

bytes - The bytes.

Returns:

A value containing bytes are the one from bytes.

Throws:

IllegalArgumentException - if any of the specified would be truncated when storing as a byte.

ofUnsignedShort

static Bytes ofUnsignedShort(int value)

Return a 2-byte value corresponding to the provided value interpreted as an unsigned short.

Parameters:

value - The value, which must be no larger than an unsigned short.

Returns:

A 2 bytes value corresponding to value.

Throws:

IllegalArgumentException - if value < 0 or value is too big to fit an unsigned 2-byte short (that is, if value >= (1 << 16)).

ofUnsignedShort

static Bytes ofUnsignedShort(int value,
 ByteOrder order)

Return a 2-byte value corresponding to the provided value interpreted as an unsigned short.

Parameters:

value - The value, which must be no larger than an unsigned short.

order - The byte-order for the integer encoding.

Returns:

A 2 bytes value corresponding to value.

Throws:

IllegalArgumentException - if value < 0 or value is too big to fit an unsigned 2-byte short (that is, if value >= (1 << 16)).

ofUnsignedInt

static Bytes ofUnsignedInt(long value)

Return a 4-byte value corresponding to the provided value interpreted as an unsigned int.

Parameters:

value - The value, which must be no larger than an unsigned int.

Returns:

A 4 bytes value corresponding to value.

Throws:

IllegalArgumentException - if value < 0 or value is too big to fit an unsigned 4-byte int (that is, if value >= (1L << 32)).

ofUnsignedInt

static Bytes ofUnsignedInt(long value,
 ByteOrder order)

Return a 4-byte value corresponding to the provided value interpreted as an unsigned int.

Parameters:

value - The value, which must be no larger than an unsigned int.

order - The byte-order for the integer encoding.

Returns:

A 4 bytes value corresponding to the encoded value.

Throws:

IllegalArgumentException - if value < 0 or value is too big to fit an unsigned 4-byte int (that is, if value >= (1L << 32)).

ofUnsignedLong

static Bytes ofUnsignedLong(long value)

Return an 8-byte value corresponding to the provided value interpreted as an unsigned long.

Parameters:

value - The value, which will be interpreted as an unsigned long.

Returns:

A 8 bytes value corresponding to value.

Throws:

IllegalArgumentException - if value < 0 or value is too big to fit an unsigned 8-byte int (that is, if value >= (1L << 64)).

ofUnsignedLong

static Bytes ofUnsignedLong(long value,
 ByteOrder order)

Return an 8-byte value corresponding to the provided value interpreted as an unsigned long.

Parameters:

value - The value, which will be interpreted as an unsigned long.

order - The byte-order for the integer encoding.

Returns:

A 8 bytes value corresponding to value.

Throws:

IllegalArgumentException - if value < 0 or value is too big to fit an unsigned 8-byte int (that is, if value >= (1L << 64)).

minimalBytes

static Bytes minimalBytes(long value)

Return the smallest bytes value whose bytes correspond to the provided long. That is, the returned value may be of size less than 8 if the provided long has leading zero bytes.

Parameters:

value - The long from which to create the bytes value.

Returns:

The minimal bytes representation corresponding to l.

fromHexStringLenient

static Bytes fromHexStringLenient(CharSequence str)

Parse a hexadecimal string into a Bytes value.

This method is lenient in that str may of an odd length, in which case it will behave exactly as if it had an additional 0 in front.

Parameters:

str - The hexadecimal string to parse, which may or may not start with "0x".

Returns:

The value corresponding to str.

Throws:

IllegalArgumentException - if str does not correspond to a valid hexadecimal representation.

fromHexStringLenient

static Bytes fromHexStringLenient(CharSequence str,
 int destinationSize)

Parse a hexadecimal string into a Bytes value of the provided size.

This method allows for str to have an odd length, in which case it will behave exactly as if it had an additional 0 in front.

Parameters:

str - The hexadecimal string to parse, which may or may not start with "0x".

destinationSize - The size of the returned value, which must be big enough to hold the bytes represented by str. If it is strictly bigger those bytes from str, the returned value will be left padded with zeros.

Returns:

A value of size destinationSize corresponding to str potentially left-padded.

Throws:

IllegalArgumentException - if str does not correspond to a valid hexadecimal representation, represents more bytes than destinationSize or destinationSize < 0.

fromHexString

static Bytes fromHexString(CharSequence str)

Parse a hexadecimal string into a Bytes value.

This method requires that str have an even length.

Parameters:

str - The hexadecimal string to parse, which may or may not start with "0x".

Returns:

The value corresponding to str.

Throws:

IllegalArgumentException - if str does not correspond to a valid hexadecimal representation, or is of an odd length.

fromHexString

static Bytes fromHexString(CharSequence str,
 int destinationSize)

Parse a hexadecimal string into a Bytes value.

This method requires that str have an even length.

Parameters:

str - The hexadecimal string to parse, which may or may not start with "0x".

destinationSize - The size of the returned value, which must be big enough to hold the bytes represented by str. If it is strictly bigger those bytes from str, the returned value will be left padded with zeros.

Returns:

A value of size destinationSize corresponding to str potentially left-padded.

Throws:

IllegalArgumentException - if str does correspond to a valid hexadecimal representation, or is of an odd length.

IllegalArgumentException - if str does not correspond to a valid hexadecimal representation, or is of an odd length, or represents more bytes than destinationSize or destinationSize < 0.

fromBase64String

static Bytes fromBase64String(CharSequence str)

Parse a base 64 string into a Bytes value.

Parameters:

str - The base 64 string to parse.

Returns:

The value corresponding to str.

random

static Bytes random(int size)

Generate random bytes.

Parameters:

size - The number of bytes to generate.

Returns:

A value containing the desired number of random bytes.

random

static Bytes random(int size,
 Random generator)

Generate random bytes.

Parameters:

size - The number of bytes to generate.

generator - The generator for random bytes.

Returns:

A value containing the desired number of random bytes.

repeat

static Bytes repeat(byte b,
 int size)

Generate a bytes object filled with the same byte.

Parameters:

b - the byte to fill the Bytes with

size - the size of the object

Returns:

a value filled with a fixed byte

segment

static Bytes32[] segment(Bytes bytes)

Splits a Bytes object into Bytes32 objects. If the last element is not exactly 32 bytes, it is right padded with zeros.

Parameters:

bytes - the bytes object to segment

Returns:

an array of Bytes32 objects

size

int size()

Provides the number of bytes this value represents.

Returns:

The number of bytes this value represents.

get

byte get(int i)

Retrieve a byte in this value.

Parameters:

i - The index of the byte to fetch within the value (0-indexed).

Returns:

The byte at index i in this value.

Throws:

IndexOutOfBoundsException - if i < 0 or {i >= size()}.

getInt

default int getInt(int i)

Retrieve the 4 bytes starting at the provided index in this value as an integer.

Parameters:

i - The index from which to get the int, which must less than or equal to size() - 4.

Returns:

An integer whose value is the 4 bytes from this value starting at index i.

Throws:

IndexOutOfBoundsException - if i < 0 or i > size() - 4.

getInt

default int getInt(int i,
 ByteOrder order)

Retrieve the 4 bytes starting at the provided index in this value as an integer.

Parameters:

i - The index from which to get the int, which must less than or equal to size() - 4.

order - The byte-order for decoding the integer.

Returns:

An integer whose value is the 4 bytes from this value starting at index i.

Throws:

IndexOutOfBoundsException - if i < 0 or i > size() - 4.

toInt

default int toInt()

The value corresponding to interpreting these bytes as an integer.

Returns:

An value corresponding to this value interpreted as an integer.

Throws:

IllegalArgumentException - if size() > 4.

toInt

default int toInt(ByteOrder order)

The value corresponding to interpreting these bytes as an integer.

Parameters:

order - The byte-order for decoding the integer.

Returns:

An value corresponding to this value interpreted as an integer.

Throws:

IllegalArgumentException - if size() > 4.

isEmpty

default boolean isEmpty()

Whether this value contains no bytes.

Returns:

true if the value contains no bytes

getLong

default long getLong(int i)

Retrieves the 8 bytes starting at the provided index in this value as a long.

Parameters:

i - The index from which to get the long, which must less than or equal to size() - 8.

Returns:

A long whose value is the 8 bytes from this value starting at index i.

Throws:

IndexOutOfBoundsException - if i < 0 or i > size() - 8.

getLong

default long getLong(int i,
 ByteOrder order)

Retrieves the 8 bytes starting at the provided index in this value as a long.

Parameters:

i - The index from which to get the long, which must less than or equal to size() - 8.

order - The byte-order for decoding the integer.

Returns:

A long whose value is the 8 bytes from this value starting at index i.

Throws:

IndexOutOfBoundsException - if i < 0 or i > size() - 8.

toLong

default long toLong()

The value corresponding to interpreting these bytes as a long.

Returns:

An value corresponding to this value interpreted as a long.

Throws:

IllegalArgumentException - if size() > 8.

toLong

default long toLong(ByteOrder order)

The value corresponding to interpreting these bytes as a long.

Parameters:

order - The byte-order for decoding the integer.

Returns:

An value corresponding to this value interpreted as a long.

Throws:

IllegalArgumentException - if size() > 8.

toBigInteger

default BigInteger toBigInteger()

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.

toBigInteger

default BigInteger toBigInteger(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.

toUnsignedBigInteger

default BigInteger toUnsignedBigInteger()

The BigInteger corresponding to interpreting these bytes as an unsigned integer.

Returns:

A positive (or zero) BigInteger corresponding to interpreting these bytes as an unsigned integer.

toUnsignedBigInteger

default BigInteger toUnsignedBigInteger(ByteOrder order)

The BigInteger corresponding to interpreting these bytes as an unsigned integer.

Parameters:

order - The byte-order for decoding the integer.

Returns:

A positive (or zero) BigInteger corresponding to interpreting these bytes as an unsigned integer.

isZero

default boolean isZero()

Whether this value has only zero bytes.

Returns:

true if all the bits of this value are zeros.

hasLeadingZero

default boolean hasLeadingZero()

Whether the bytes start with a zero bit value.

Returns:

true if the first bit equals zero

numberOfLeadingZeros

default int numberOfLeadingZeros()

Provides the number of zero bits preceding the highest-order ("leftmost") one-bit, or size() * 8 if all bits * are zero.

Returns:

The number of zero bits preceding the highest-order ("leftmost") one-bit, or size() * 8 if all bits are zero.

hasLeadingZeroByte

default boolean hasLeadingZeroByte()

Whether the bytes start with a zero byte value.

Returns:

true if the first byte equals zero

numberOfLeadingZeroBytes

default int numberOfLeadingZeroBytes()

Provides the number of leading zero bytes of the value

Returns:

The number of leading zero bytes of the value.

numberOfTrailingZeroBytes

default int numberOfTrailingZeroBytes()

Provides the number of trailing zero bytes of the value.

Returns:

The number of trailing zero bytes of the value.

bitLength

default int bitLength()

Provides the number of bits following and including the highest-order ("leftmost") one-bit, or zero if all bits are zero.

Returns:

The number of bits following and including the highest-order ("leftmost") one-bit, or zero if all bits are zero.

and

default Bytes and(Bytes other)

Return a bit-wise AND of these bytes and the supplied bytes.

If this value and the supplied value are different lengths, then the shorter will be zero-padded to the left.

Parameters:

other - The bytes to perform the operation with.

Returns:

The result of a bit-wise AND.

and

default <T extends MutableBytes> T and(Bytes other,
 T result)

Calculate a bit-wise AND of these bytes and the supplied bytes.

If this value or the supplied value are shorter in length than the output vector, then they will be zero-padded to the left. Likewise, if either this value or the supplied valid is longer in length than the output vector, then they will be truncated to the left.

Type Parameters:

T - The MutableBytes value type.

Parameters:

other - The bytes to perform the operation with.

result - The mutable output vector for the result.

Returns:

The result output vector.

or

default Bytes or(Bytes other)

Return a bit-wise OR of these bytes and the supplied bytes.

If this value and the supplied value are different lengths, then the shorter will be zero-padded to the left.

Parameters:

other - The bytes to perform the operation with.

Returns:

The result of a bit-wise OR.

or

default <T extends MutableBytes> T or(Bytes other,
 T result)

Calculate a bit-wise OR of these bytes and the supplied bytes.

If this value or the supplied value are shorter in length than the output vector, then they will be zero-padded to the left. Likewise, if either this value or the supplied valid is longer in length than the output vector, then they will be truncated to the left.

Type Parameters:

T - The MutableBytes value type.

Parameters:

other - The bytes to perform the operation with.

result - The mutable output vector for the result.

Returns:

The result output vector.

xor

default Bytes xor(Bytes other)

Return a bit-wise XOR of these bytes and the supplied bytes.

If this value and the supplied value are different lengths, then the shorter will be zero-padded to the left.

Parameters:

other - The bytes to perform the operation with.

Returns:

The result of a bit-wise XOR.

xor

default <T extends MutableBytes> T xor(Bytes other,
 T result)

Calculate a bit-wise XOR of these bytes and the supplied bytes.

If this value or the supplied value are shorter in length than the output vector, then they will be zero-padded to the left. Likewise, if either this value or the supplied valid is longer in length than the output vector, then they will be truncated to the left.

Type Parameters:

T - The MutableBytes value type.

Parameters:

other - The bytes to perform the operation with.

result - The mutable output vector for the result.

Returns:

The result output vector.

not

default Bytes not()

Return a bit-wise NOT of these bytes.

Returns:

The result of a bit-wise NOT.

not

default <T extends MutableBytes> T not(T result)

Calculate a bit-wise NOT of these bytes.

If this value is shorter in length than the output vector, then it will be zero-padded to the left. Likewise, if this value is longer in length than the output vector, then it will be truncated to the left.

Type Parameters:

T - The MutableBytes value type.

Parameters:

result - The mutable output vector for the result.

Returns:

The result output vector.

shiftRight

default Bytes shiftRight(int distance)

Shift all bits in this value to the right.

Parameters:

distance - The number of bits to shift by.

Returns:

A value containing the shifted bits.

shiftRight

default <T extends MutableBytes> T shiftRight(int distance,
 T result)

Shift all bits in this value to the right.

If this value is shorter in length than the output vector, then it will be zero-padded to the left. Likewise, if this value is longer in length than the output vector, then it will be truncated to the left (after shifting).

Type Parameters:

T - The MutableBytes value type.

Parameters:

distance - The number of bits to shift by.

result - The mutable output vector for the result.

Returns:

The result output vector.

shiftLeft

default Bytes shiftLeft(int distance)

Shift all bits in this value to the left.

Parameters:

distance - The number of bits to shift by.

Returns:

A value containing the shifted bits.

shiftLeft

default <T extends MutableBytes> T shiftLeft(int distance,
 T result)

Shift all bits in this value to the left.

If this value is shorter in length than the output vector, then it will be zero-padded to the left. Likewise, if this value is longer in length than the output vector, then it will be truncated to the left.

Type Parameters:

T - The MutableBytes value type.

Parameters:

distance - The number of bits to shift by.

result - The mutable output vector for the result.

Returns:

The result output vector.

slice

default Bytes slice(int i)

Create a new value representing (a view of) a slice of the bytes of this value.

Please note that the resulting slice is only a view and as such maintains a link to the underlying full value. So holding a reference to the returned slice may hold more memory than the slide represents. Use copy() on the returned slice if that is not what you want.

Parameters:

i - The start index for the slice.

Returns:

A new value providing a view over the bytes from index i (included) to the end.

Throws:

IndexOutOfBoundsException - if i < 0.

slice

Bytes slice(int i,
 int length)

Create a new value representing (a view of) a slice of the bytes of this value.

Please note that the resulting slice is only a view and as such maintains a link to the underlying full value. So holding a reference to the returned slice may hold more memory than the slide represents. Use copy() on the returned slice if that is not what you want.

Parameters:

i - The start index for the slice.

length - The length of the resulting value.

Returns:

A new value providing a view over the bytes from index i (included) to i + length (excluded).

Throws:

IllegalArgumentException - if length < 0.

IndexOutOfBoundsException - if i < 0 or {i >= size()} or {i + length > size()} .

copy

Bytes copy()

Return a value equivalent to this one but guaranteed to 1) be deeply immutable (i.e. the underlying value will be immutable) and 2) to not retain more bytes than exposed by the value.

Returns:

A value, equals to this one, but deeply immutable and that doesn't retain any "unreachable" bytes. For performance reasons, this is allowed to return this value however if it already fit those constraints.

mutableCopy

MutableBytes mutableCopy()

Return a new mutable value initialized with the content of this value.

Returns:

A mutable copy of this value. This will copy bytes, modifying the returned value will not modify this value.

copyTo

default void copyTo(MutableBytes destination)

Copy the bytes of this value to the provided mutable one, which must have the same size.

Parameters:

destination - The mutable value to which to copy the bytes to, which must have the same size as this value. If you want to copy value where size differs, you should use slice(int) and/or MutableBytes.mutableSlice(int, int) and apply the copy to the result.

Throws:

IllegalArgumentException - if this.size() != destination.size().

copyTo

default void copyTo(MutableBytes destination,
 int destinationOffset)

Copy the bytes of this value to the provided mutable one from a particular offset.

This is a (potentially slightly more efficient) shortcut for copyTo(destination.mutableSlice(destinationOffset, this.size())).

Parameters:

destination - The mutable value to which to copy the bytes to, which must have enough bytes from destinationOffset for the copied value.

destinationOffset - The offset in destination at which the copy starts.

Throws:

IllegalArgumentException - if the destination doesn't have enough room, that is if this.size() > (destination.size() - destinationOffset).

appendTo

default void appendTo(ByteBuffer byteBuffer)

Append the bytes of this value to the ByteBuffer.

Parameters:

byteBuffer - The ByteBuffer to which to append this value.

Throws:

BufferOverflowException - If the writer attempts to write more than the provided buffer can hold.

ReadOnlyBufferException - If the provided buffer is read-only.

appendTo

default void appendTo(io.vertx.core.buffer.Buffer buffer)

Append the bytes of this value to the provided Vert.x Buffer.

Note that since a Vert.x Buffer will grow as necessary, this method never fails.

Parameters:

buffer - The Buffer to which to append this value.

appendHexTo

default <T extends Appendable> T appendHexTo(T appendable)

Append this value as a sequence of hexadecimal characters.

Type Parameters:

T - The appendable type.

Parameters:

appendable - The appendable

Returns:

The appendable.

toFastHex

default String toFastHex(boolean prefix)

commonPrefixLength

default int commonPrefixLength(Bytes other)

Return the number of bytes in common between this set of bytes and another.

Parameters:

other - The bytes to compare to.

Returns:

The number of common bytes.

commonPrefix

default Bytes commonPrefix(Bytes other)

Return a slice over the common prefix between this set of bytes and another.

Parameters:

other - The bytes to compare to.

Returns:

A slice covering the common prefix.

trimLeadingZeros

default Bytes trimLeadingZeros()

Return a slice of representing the same value but without any leading zero bytes.

Returns:

value if its left-most byte is non zero, or a slice that exclude any leading zero bytes.

trimTrailingZeros

default Bytes trimTrailingZeros()

Return a slice of representing the same value but without any trailing zero bytes.

Returns:

value if its right-most byte is non zero, or a slice that exclude any trailing zero bytes.

update

default void update(MessageDigest digest)

Update the provided message digest with the bytes of this value.

Parameters:

digest - The digest to update.

reverse

default Bytes reverse()

Computes the reverse array of bytes of the current bytes.

Returns:

a new Bytes value, containing the bytes in reverse order

toArray

default byte[] toArray()

Extract the bytes of this value into a byte array.

Returns:

A byte array with the same content than this value.

toArray

default byte[] toArray(ByteOrder byteOrder)

Extract the bytes of this value into a byte array.

Parameters:

byteOrder - the byte order to apply : big endian or little endian

Returns:

A byte array with the same content than this value.

toArrayUnsafe

default byte[] toArrayUnsafe()

Get the bytes represented by this value as byte array.

Contrarily to toArray(), this may avoid allocating a new array and directly return the backing array of this value if said value is array backed and doing so is possible. As such, modifications to the returned array may or may not impact this value. As such, this method should be used with care and hence the "unsafe" moniker.

Returns:

A byte array with the same content than this value, which may or may not be the direct backing of this value.

toString

String toString()

Return the hexadecimal string representation of this value.

Overrides:

toString in class Object

Returns:

The hexadecimal representation of this value, starting with "0x".

toHexString

default String toHexString()

Provides this value represented as hexadecimal, starting with "0x".

Returns:

This value represented as hexadecimal, starting with "0x".

toUnprefixedHexString

default String toUnprefixedHexString()

Provides this value represented as hexadecimal, with no prefix

Returns:

This value represented as hexadecimal, with no prefix.

toEllipsisHexString

default String toEllipsisHexString()

toShortHexString

default String toShortHexString()

Provides this value represented as a minimal hexadecimal string (without any leading zero)

Returns:

This value represented as a minimal hexadecimal string (without any leading zero).

toQuantityHexString

default String toQuantityHexString()

Provides this value represented as a minimal hexadecimal string (without any leading zero, except if it's valued zero or empty, in which case it returns 0x0).

Returns:

This value represented as a minimal hexadecimal string (without any leading zero, except if it's valued zero or empty, in which case it returns 0x0).

toBase64String

default String toBase64String()

Provides this value represented as base 64

Returns:

This value represented as base 64.

compareTo

default int compareTo(Bytes b)

Specified by:

compareTo in interface Comparable<Bytes>