Package org.onlab.util

Class 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.

    • 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