Class ImmutableByteSequence
- java.lang.Object
-
- org.onlab.util.ImmutableByteSequence
-
public final class ImmutableByteSequence extends Object
Immutable sequence of bytes, assumed to represent a value inBIG_ENDIAN
order.Sequences can be created copying from an already existing representation of a sequence of bytes, such as
ByteBuffer
orbyte[]
; or by copying bytes from a primitive data type, such aslong
,int
orshort
. 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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description byte[]
asArray()
Creates a new byte array view of this sequence.ByteBuffer
asReadOnlyBuffer()
Returns a view of this sequence as a read-onlyByteBuffer
.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(ByteBuffer original)
Creates a new immutable byte sequence copying bytes from the given ByteBufferByteBuffer
.boolean
equals(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.String
toString()
Returns a hexadecimal representation of this byte sequence, e.g.
-
-
-
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 valuefromIdx
- starting indextoIdx
- ending index- Returns:
- a new immutable byte sequence
-
copyFrom
public static ImmutableByteSequence copyFrom(ByteBuffer original)
Creates a new immutable byte sequence copying bytes from the given ByteBufferByteBuffer
. 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 bytesprefixBits
- 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 bytesprefixBits
- number of bits in prefix- Returns:
- new immutable byte sequence
-
asReadOnlyBuffer
public ByteBuffer asReadOnlyBuffer()
Returns a view of this sequence as a read-onlyByteBuffer
.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:
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:
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:
IllegalArgumentException
- if other sequence is null or its size is different than this sequence size
-
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 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.
-
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 whenbitWidth > 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
-
-