Interface ByteSequence

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      ByteSequenceReader asReader()
      Returns a ByteSequenceReader which can be used to incrementally read and decode data from this byte sequence.
      byte byteAt​(int index)
      Returns the byte value at the specified index.
      int compareTo​(byte[] bytes, int offset, int length)
      Compares this byte sequence with the specified byte array subsequence for order.
      int compareTo​(ByteSequence o)
      Compares this byte sequence with the specified byte sequence for order.
      byte[] copyTo​(byte[] bytes)
      Copies the contents of this byte sequence to the provided byte array.
      byte[] copyTo​(byte[] bytes, int offset)
      Copies the contents of this byte sequence to the specified location in the provided byte array.
      OutputStream copyTo​(OutputStream stream)
      Copies the entire contents of this byte sequence to the provided OutputStream.
      ByteBuffer copyTo​(ByteBuffer buffer)
      Appends the content of this byte sequence to the provided ByteBuffer starting at it's current position.
      boolean copyTo​(CharBuffer charBuffer, CharsetDecoder decoder)
      Appends the content of this byte sequence decoded using provided charset decoder to the provided CharBuffer starting at it's current position.
      ByteStringBuilder copyTo​(ByteStringBuilder builder)
      Appends the entire contents of this byte sequence to the provided ByteStringBuilder.
      boolean equals​(byte[] bytes, int offset, int length)
      Indicates whether the provided byte array subsequence is equal to this byte sequence.
      boolean equals​(Object o)
      Indicates whether the provided object is equal to this byte sequence.
      int hashCode()
      Returns a hash code for this byte sequence.
      int intAt​(int index)
      Returns the big-endian int value at the specified index.
      boolean isEmpty()
      Returns true if this byte sequence has a length of zero.
      int length()
      Returns the length of this byte sequence.
      long longAt​(int index)
      Returns the big-endian long value at the specified index.
      short shortAt​(int index)
      Returns the big-endian short value at the specified index.
      boolean startsWith​(ByteSequence prefix)
      Tests if this ByteSequence starts with the specified prefix.
      ByteSequence subSequence​(int start)
      Returns a new byte sequence that is a subsequence of this byte sequence.
      ByteSequence subSequence​(int start, int size)
      Returns a new byte sequence that is a subsequence of this byte sequence.
      String toBase64String()
      Returns the Base64 encoded string representation of this byte string.
      byte[] toByteArray()
      Returns a byte array containing the bytes in this sequence in the same order as this sequence.
      ByteBuffer toByteBuffer()
      Returns the read-only ByteBuffer representation of this byte sequence.
      ByteString toByteString()
      Returns the ByteString representation of this byte sequence.
      String toString()
      Returns the UTF-8 decoded string representation of this byte sequence.
    • Method Detail

      • asReader

        ByteSequenceReader asReader()
        Returns a ByteSequenceReader which can be used to incrementally read and decode data from this byte sequence.

        NOTE: any concurrent changes to the underlying byte sequence (if mutable) may cause subsequent reads to overrun and fail.

        Returns:
        The ByteSequenceReader which can be used to incrementally read and decode data from this byte sequence.
      • byteAt

        byte byteAt​(int index)
        Returns the byte value at the specified index.

        An index ranges from zero to length() - 1. The first byte value of the sequence is at index zero, the next at index one, and so on, as for array indexing.

        Parameters:
        index - The index of the byte to be returned.
        Returns:
        The byte value at the specified index.
        Throws:
        IndexOutOfBoundsException - If the index argument is negative or not less than length().
      • shortAt

        short shortAt​(int index)
        Returns the big-endian short value at the specified index.
        Parameters:
        index - The index of the short to be returned.
        Returns:
        The short value at the specified index.
        Throws:
        IndexOutOfBoundsException - If the index argument is negative or not less than length() - 2.
      • intAt

        int intAt​(int index)
        Returns the big-endian int value at the specified index.
        Parameters:
        index - The index of the int to be returned.
        Returns:
        The int value at the specified index.
        Throws:
        IndexOutOfBoundsException - If the index argument is negative or not less than length() - 4.
      • longAt

        long longAt​(int index)
        Returns the big-endian long value at the specified index.
        Parameters:
        index - The index of the long to be returned.
        Returns:
        The long value at the specified index.
        Throws:
        IndexOutOfBoundsException - If the index argument is negative or not less than length() - 8.
      • compareTo

        int compareTo​(byte[] bytes,
                      int offset,
                      int length)
        Compares this byte sequence with the specified byte array subsequence for order. Returns a negative integer, zero, or a positive integer depending on whether this byte sequence is less than, equal to, or greater than the specified byte array subsequence.
        Parameters:
        bytes - The byte array to compare.
        offset - The offset of the subsequence in the byte array to be compared; must be non-negative and no larger than bytes.length .
        length - The length of the subsequence in the byte array to be compared; must be non-negative and no larger than bytes.length - offset.
        Returns:
        A negative integer, zero, or a positive integer depending on whether this byte sequence is less than, equal to, or greater than the specified byte array subsequence.
        Throws:
        IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than bytes.length.
      • compareTo

        int compareTo​(ByteSequence o)
        Compares this byte sequence with the specified byte sequence for order. Returns a negative integer, zero, or a positive integer depending on whether this byte sequence is less than, equal to, or greater than the specified object.
        Specified by:
        compareTo in interface Comparable<ByteSequence>
        Parameters:
        o - The byte sequence to be compared.
        Returns:
        A negative integer, zero, or a positive integer depending on whether this byte sequence is less than, equal to, or greater than the specified object.
      • copyTo

        byte[] copyTo​(byte[] bytes)
        Copies the contents of this byte sequence to the provided byte array.

        Copying will stop when either the entire content of this sequence has been copied or if the end of the provided byte array has been reached.

        An invocation of the form:

         src.copyTo(bytes)
         
        Behaves in exactly the same way as the invocation:
         src.copyTo(bytes, 0);
         
        Parameters:
        bytes - The byte array to which bytes are to be copied.
        Returns:
        The byte array.
      • copyTo

        byte[] copyTo​(byte[] bytes,
                      int offset)
        Copies the contents of this byte sequence to the specified location in the provided byte array.

        Copying will stop when either the entire content of this sequence has been copied or if the end of the provided byte array has been reached.

        An invocation of the form:

         src.copyTo(bytes, offset)
         
        Behaves in exactly the same way as the invocation:
         int len = Math.min(src.length(), bytes.length - offset);
         for (int i = 0; i < len; i++)
             bytes[offset + i] = src.get(i);
         
        Except that it is potentially much more efficient.
        Parameters:
        bytes - The byte array to which bytes are to be copied.
        offset - The offset within the array of the first byte to be written; must be non-negative and no larger than bytes.length.
        Returns:
        The byte array.
        Throws:
        IndexOutOfBoundsException - If offset is negative.
      • copyTo

        ByteBuffer copyTo​(ByteBuffer buffer)
        Appends the content of this byte sequence to the provided ByteBuffer starting at it's current position. The position of the buffer is then incremented by the length of this sequence.
        Parameters:
        buffer - The buffer to copy to. It must be large enough to receive all bytes.
        Returns:
        The buffer.
        Throws:
        BufferOverflowException - If there is insufficient space in the provided buffer
      • copyTo

        boolean copyTo​(CharBuffer charBuffer,
                       CharsetDecoder decoder)
        Appends the content of this byte sequence decoded using provided charset decoder to the provided CharBuffer starting at it's current position. The position of charBuffer is then incremented by the length of this sequence.
        Parameters:
        charBuffer - The buffer to copy to, if decoding is successful. It must be large enough to receive all decoded characters.
        decoder - The charset decoder to use for decoding.
        Returns:
        true if byte string was successfully decoded and charBuffer is large enough to receive the resulting string, false otherwise
      • copyTo

        OutputStream copyTo​(OutputStream stream)
                     throws IOException
        Copies the entire contents of this byte sequence to the provided OutputStream.
        Parameters:
        stream - The OutputStream to copy to.
        Returns:
        The OutputStream.
        Throws:
        IOException - If an error occurs while writing to the OutputStream.
      • equals

        boolean equals​(byte[] bytes,
                       int offset,
                       int length)
        Indicates whether the provided byte array subsequence is equal to this byte sequence. In order for it to be considered equal, the provided byte array subsequence must contain the same bytes in the same order.
        Parameters:
        bytes - The byte array for which to make the determination.
        offset - The offset of the subsequence in the byte array to be compared; must be non-negative and no larger than bytes.length .
        length - The length of the subsequence in the byte array to be compared; must be non-negative and no larger than bytes.length - offset.
        Returns:
        true if the content of the provided byte array subsequence is equal to that of this byte sequence, or false if not.
        Throws:
        IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than bytes.length.
      • equals

        boolean equals​(Object o)
        Indicates whether the provided object is equal to this byte sequence. In order for it to be considered equal, the provided object must be a byte sequence containing the same bytes in the same order.
        Overrides:
        equals in class Object
        Parameters:
        o - The object for which to make the determination.
        Returns:
        true if the provided object is a byte sequence whose content is equal to that of this byte sequence, or false if not.
      • hashCode

        int hashCode()
        Returns a hash code for this byte sequence. It will be the sum of all of the bytes contained in the byte sequence.
        Overrides:
        hashCode in class Object
        Returns:
        A hash code for this byte sequence.
      • isEmpty

        boolean isEmpty()
        Returns true if this byte sequence has a length of zero.
        Returns:
        true if this byte sequence has a length of zero.
      • length

        int length()
        Returns the length of this byte sequence.
        Returns:
        The length of this byte sequence.
      • subSequence

        ByteSequence subSequence​(int start)
        Returns a new byte sequence that is a subsequence of this byte sequence.

        The subsequence starts with the byte value at the specified start index and ends with the last byte value. The length (in bytes) of the returned sequence is length() - start, so if start == length() then an empty sequence is returned.

        NOTE: changes to the underlying byte sequence (if mutable) may render the returned subsequence invalid.

        Parameters:
        start - The start index, inclusive.
        Returns:
        The newly created byte subsequence.
        Throws:
        IndexOutOfBoundsException - If start is negative, if start is greater than length()
      • subSequence

        ByteSequence subSequence​(int start,
                                 int size)
        Returns a new byte sequence that is a subsequence of this byte sequence.

        The subsequence starts with the byte value at the specified start index and is length long.

        NOTE: changes to the underlying byte sequence (if mutable) may render the returned subsequence invalid.

        Parameters:
        start - The start index, inclusive.
        size - The length of subsequence.
        Returns:
        The newly created byte subsequence.
        Throws:
        IndexOutOfBoundsException - If start is negative, if size is negative, if start + size is greater than length().
      • startsWith

        boolean startsWith​(ByteSequence prefix)
        Tests if this ByteSequence starts with the specified prefix.
        Parameters:
        prefix - The prefix.
        Returns:
        true if the byte sequence represented by the argument is a prefix of the byte sequence represented by this ByteSequence; false otherwise. Note also that true will be returned if the argument is an empty sequence or is equal to this ByteSequence object as determined by the equals(Object) method.
      • toBase64String

        String toBase64String()
        Returns the Base64 encoded string representation of this byte string.
        Returns:
        The Base64 encoded string representation of this byte string.
        See Also:
        ByteString.valueOfBase64(String)
      • toByteArray

        byte[] toByteArray()
        Returns a byte array containing the bytes in this sequence in the same order as this sequence. The length of the byte array will be the length of this sequence.

        An invocation of the form:

         src.toByteArray()
         
        Behaves in exactly the same way as the invocation:
         src.copyTo(new byte[src.length()]);
         
        Returns:
        A byte array consisting of exactly this sequence of bytes.
      • toByteString

        ByteString toByteString()
        Returns the ByteString representation of this byte sequence.
        Returns:
        The ByteString representation of this byte sequence.
      • toByteBuffer

        ByteBuffer toByteBuffer()
        Returns the read-only ByteBuffer representation of this byte sequence.
        Returns:
        The read-only ByteBuffer representation of this byte sequence.
      • toString

        String toString()
        Returns the UTF-8 decoded string representation of this byte sequence. If UTF-8 decoding fails, the platform's default encoding will be used.
        Overrides:
        toString in class Object
        Returns:
        The string representation of this byte sequence.