Package org.onlab.util

Class ImmutableByteSequence

java.lang.Object

org.onlab.util.ImmutableByteSequence

public final class ImmutableByteSequence
extends java.lang.Object

Immutable sequence of bytes, assumed to represent a value in BIG_ENDIAN order.

Sequences can be created copying from an already existing representation of a sequence of bytes, such as ByteBuffer or byte[]; or by copying bytes from a primitive data type, such as long, int or short. In the first case, bytes are assumed to be already given in big-endian order, while in the second case big-endianness is enforced by this class.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ImmutableByteSequence.ByteSequenceTrimException	Signals that a byte sequence cannot be trimmed.

Method Summary

Modifier and Type	Method	Description
byte[]	asArray()	Creates a new byte array view of this sequence.
java.nio.ByteBuffer	asReadOnlyBuffer()	Returns a view of this sequence as a read-only ByteBuffer.
ImmutableByteSequence	bitwiseAnd(ImmutableByteSequence other)	Returns a new byte sequence corresponding to the result of a bitwise AND operation between this sequence and the given other, i.e.
ImmutableByteSequence	bitwiseOr(ImmutableByteSequence other)	Returns a new byte sequence corresponding to the result of a bitwise OR operation between this sequence and the given other, i.e.
ImmutableByteSequence	bitwiseXor(ImmutableByteSequence other)	Returns a new byte sequence corresponding to the result of a bitwise XOR operation between this sequence and the given other, i.e.
static ImmutableByteSequence	copyFrom(byte original)	Creates a new byte sequence of 1 byte containing the given value.
static ImmutableByteSequence	copyFrom(byte[] original)	Creates a new immutable byte sequence with the same content and order of the passed byte array.
static ImmutableByteSequence	copyFrom(byte[] original, int fromIdx, int toIdx)	Creates a new immutable byte sequence with the same content and order of the passed byte array, from/to the given indexes (inclusive).
static ImmutableByteSequence	copyFrom(int original)	Creates a new byte sequence of 4 bytes containing the given int value.
static ImmutableByteSequence	copyFrom(long original)	Creates a new byte sequence of 8 bytes containing the given long value.
static ImmutableByteSequence	copyFrom(short original)	Creates a new byte sequence of 2 bytes containing the given short value.
static ImmutableByteSequence	copyFrom(java.nio.ByteBuffer original)	Creates a new immutable byte sequence copying bytes from the given ByteBuffer ByteBuffer.
boolean	equals(java.lang.Object obj)
ImmutableByteSequence	fit(int bitWidth)	Trims or expands a copy of this byte sequence so to fit the given bit-width.
int	hashCode()
int	msbIndex()	Returns the index of the most significant bit (MSB), assuming a bit numbering scheme of type "LSB 0", i.e.
static ImmutableByteSequence	ofOnes(int size)	Creates a new byte sequence of the given size where all bits are 1.
static ImmutableByteSequence	ofZeros(int size)	Creates a new byte sequence of the given size where all bits are 0.
static ImmutableByteSequence	prefixOnes(int size, long prefixBits)	Creates a new byte sequence that is prefixed with specified number of ones.
static ImmutableByteSequence	prefixZeros(int size, long prefixBits)	Creates a new byte sequence that is prefixed with specified number of zeros.
int	size()	Gets the number of bytes in this sequence.
java.lang.String	toString()	Returns a hexadecimal representation of this byte sequence, e.g.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

copyFrom

public static ImmutableByteSequence copyFrom(byte[] original)

Creates a new immutable byte sequence with the same content and order of the passed byte array.

Parameters:

original - a byte array value

Returns:

a new immutable byte sequence

copyFrom

public static ImmutableByteSequence copyFrom(byte[] original,
                                             int fromIdx,
                                             int toIdx)

Creates a new immutable byte sequence with the same content and order of the passed byte array, from/to the given indexes (inclusive).

Parameters:

original - a byte array value

fromIdx - starting index

toIdx - ending index

Returns:

a new immutable byte sequence

copyFrom

public static ImmutableByteSequence copyFrom(java.nio.ByteBuffer original)

Creates a new immutable byte sequence copying bytes from the given ByteBuffer ByteBuffer. If the byte buffer order is not big-endian bytes will be copied in reverse order.

Parameters:

original - a byte buffer

Returns:

a new byte buffer object

copyFrom

public static ImmutableByteSequence copyFrom(long original)

Creates a new byte sequence of 8 bytes containing the given long value.

Parameters:

original - a long value

Returns:

a new immutable byte sequence

copyFrom

public static ImmutableByteSequence copyFrom(int original)

Creates a new byte sequence of 4 bytes containing the given int value.

Parameters:

original - an int value

Returns:

a new immutable byte sequence

copyFrom

public static ImmutableByteSequence copyFrom(short original)

Creates a new byte sequence of 2 bytes containing the given short value.

Parameters:

original - a short value

Returns:

a new immutable byte sequence

copyFrom

public static ImmutableByteSequence copyFrom(byte original)

Creates a new byte sequence of 1 byte containing the given value.

Parameters:

original - a byte value

Returns:

a new immutable byte sequence

ofZeros

public static ImmutableByteSequence ofZeros(int size)

Creates a new byte sequence of the given size where all bits are 0.

Parameters:

size - number of bytes

Returns:

a new immutable byte sequence

ofOnes

public static ImmutableByteSequence ofOnes(int size)

Creates a new byte sequence of the given size where all bits are 1.

Parameters:

size - number of bytes

Returns:

a new immutable byte sequence

prefixZeros

public static ImmutableByteSequence prefixZeros(int size,
                                                long prefixBits)

Creates a new byte sequence that is prefixed with specified number of zeros.

Parameters:

size - number of total bytes

prefixBits - number of bits in prefix

Returns:

new immutable byte sequence

prefixOnes

public static ImmutableByteSequence prefixOnes(int size,
                                               long prefixBits)

Creates a new byte sequence that is prefixed with specified number of ones.

Parameters:

size - number of total bytes

prefixBits - number of bits in prefix

Returns:

new immutable byte sequence

asReadOnlyBuffer

public java.nio.ByteBuffer asReadOnlyBuffer()

Returns a view of this sequence as a read-only ByteBuffer.

The returned buffer will have position 0, while limit and capacity will be set to this sequence size(). The buffer order will be big-endian.

Returns:

a read-only byte buffer

size

public int size()

Gets the number of bytes in this sequence.

Returns:

an integer value

asArray

public byte[] asArray()

Creates a new byte array view of this sequence.

Returns:

a new byte array

bitwiseAnd

public ImmutableByteSequence bitwiseAnd(ImmutableByteSequence other)

Returns a new byte sequence corresponding to the result of a bitwise AND operation between this sequence and the given other, i.e. this & other.

Parameters:

other - other byte sequence

Returns:

new byte sequence

Throws:

java.lang.IllegalArgumentException - if other sequence is null or its size is different than this sequence size

bitwiseOr

public ImmutableByteSequence bitwiseOr(ImmutableByteSequence other)

Returns a new byte sequence corresponding to the result of a bitwise OR operation between this sequence and the given other, i.e. this | other.

Parameters:

other - other byte sequence

Returns:

new byte sequence

Throws:

java.lang.IllegalArgumentException - if other sequence is null or its size is different than this sequence size

bitwiseXor

public ImmutableByteSequence bitwiseXor(ImmutableByteSequence other)

Returns a new byte sequence corresponding to the result of a bitwise XOR operation between this sequence and the given other, i.e. this ^ other.

Parameters:

other - other byte sequence

Returns:

new byte sequence

Throws:

java.lang.IllegalArgumentException - if other sequence is null or its size is different than this sequence size

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

msbIndex

public int msbIndex()

Returns the index of the most significant bit (MSB), assuming a bit numbering scheme of type "LSB 0", i.e. the bit numbering starts at zero for the least significant bit (LSB). The MSB index of a byte sequence of zeros will be -1.

As an example, the following conditions always hold true: ImmutableByteSequence.copyFrom(0).msbIndex() == -1 ImmutableByteSequence.copyFrom(1).msbIndex() == 0 ImmutableByteSequence.copyFrom(2).msbIndex() == 1 ImmutableByteSequence.copyFrom(3).msbIndex() == 1 ImmutableByteSequence.copyFrom(4).msbIndex() == 2 ImmutableByteSequence.copyFrom(512).msbIndex() == 9

Returns:

index of the MSB, -1 if the sequence has all bytes set to 0

toString

public java.lang.String toString()

Returns a hexadecimal representation of this byte sequence, e.g. 0xbeef. The length of the returned string is not representative of the length of the byte sequence, as all padding zeros are removed.

Overrides:

toString in class java.lang.Object

Returns:

hexadecimal representation

fit

public ImmutableByteSequence fit(int bitWidth)
                          throws ImmutableByteSequence.ByteSequenceTrimException

Trims or expands a copy of this byte sequence so to fit the given bit-width. When trimming, the operations is deemed to be safe only if the trimmed bits are zero, i.e. it is safe to trim only when bitWidth > msbIndex(), otherwise an exception will be thrown. When expanding, the sequence will be padded with zeros. The returned byte sequence will have minimum size to contain the given bit-width.

Parameters:

bitWidth - a non-zero positive integer

Returns:

a new byte sequence

Throws:

ImmutableByteSequence.ByteSequenceTrimException - if the byte sequence cannot be fitted