ImmutableByteSequence (ONOS Java API (2.0.0))

java.lang.Object
- org.onlab.util.ImmutableByteSequence

```
public final class ImmutableByteSequence
extends 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 and Description

static class ImmutableByteSequence.ByteSequenceTrimException
Signals that a byte sequence cannot be trimmed.

Nested Classes
Modifier and Type	Class and 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 and Description
`byte[]`	`asArray()` Creates a new byte array view of this sequence.
`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(ByteBuffer original)` Creates a new immutable byte sequence copying bytes from the given ByteBuffer `ByteBuffer`.
`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.
`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.

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(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 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:
    
    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
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class 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 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 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

Class ImmutableByteSequence

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

copyFrom

copyFrom

copyFrom

copyFrom

copyFrom

copyFrom

copyFrom

ofZeros

ofOnes

prefixZeros

prefixOnes

asReadOnlyBuffer

size

asArray

bitwiseAnd

bitwiseOr

bitwiseXor

hashCode

equals

msbIndex

toString

fit