oracle.oud.types

Interface ByteSequence

All Superinterfaces:

java.lang.Comparable<ByteSequence>

All Known Implementing Classes:

ByteString, ByteStringBuilder

public interface ByteSequence
extends java.lang.Comparable<ByteSequence>

A ByteSequence is a readable sequence of byte values. This interface provides uniform, read-only access to many different kinds of byte sequences.

Method Summary

Methods

Modifier and Type	Method and 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[] b, int offset, int length) Compares this byte sequence with the specified byte array sub-sequence for order.
int	compareTo(ByteSequence o) Compares this byte sequence with the specified byte sequence for order.
byte[]	copyTo(byte[] b) Copies the contents of this byte sequence to the provided byte array.
byte[]	copyTo(byte[] b, int offset) Copies the contents of this byte sequence to the specified location in the provided byte array.
ByteStringBuilder	copyTo(ByteStringBuilder builder) Appends the entire contents of this byte sequence to the provided ByteStringBuilder.
java.io.OutputStream	copyTo(java.io.OutputStream stream) Copies the entire contents of this byte sequence to the provided OutputStream.
boolean	equals(byte[] b, int offset, int length) Indicates whether the provided byte array sub-sequence is equal to this byte sequence.
boolean	equals(java.lang.Object o) Indicates whether the provided object is equal to this byte sequence.
int	hashCode() Returns a hash code for this byte sequence.
int	length() Returns the length of this byte sequence.
ByteSequence	subSequence(int start, int end) Returns a new byte sequence that is a subsequence of this byte sequence.
byte[]	toByteArray() Returns a byte array containing the bytes in this sequence in the same order as this sequence.
ByteString	toByteString() Returns the ByteString representation of this byte sequence.
java.lang.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)
            throws java.lang.IndexOutOfBoundsException

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:

java.lang.IndexOutOfBoundsException - If the index argument is negative or not less than length().

compareTo

int compareTo(byte[] b,
            int offset,
            int length)
              throws java.lang.IndexOutOfBoundsException

Compares this byte sequence with the specified byte array sub-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 byte array sub-sequence.

Parameters:

b - The byte array to compare.

offset - The offset of the sub-sequence in the byte array to be compared; must be non-negative and no larger than b.length .

length - The length of the sub-sequence in the byte array to be compared; must be non-negative and no larger than b.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 sub-sequence.

Throws:

java.lang.IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than b.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 java.lang.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[] b)

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(b)
 

Behaves in exactly the same way as the invocation:

 src.copyTo(b, 0);
 

Parameters:

b - The byte array to which bytes are to be copied.

Returns:

The byte array.

copyTo

byte[] copyTo(byte[] b,
            int offset)
              throws java.lang.IndexOutOfBoundsException

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(b, offset)
 

Behaves in exactly the same way as the invocation:

 int len = Math.min(src.length(), b.length - offset);
 for (int i = 0; i < len; i++)
   b[offset + i] = src.get(i);
 

Except that it is potentially much more efficient.

Parameters:

b - 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 b.length.

Returns:

The byte array.

Throws:

java.lang.IndexOutOfBoundsException - If offset is negative.

copyTo

ByteStringBuilder copyTo(ByteStringBuilder builder)

Appends the entire contents of this byte sequence to the provided ByteStringBuilder.

Parameters:

builder - The builder to copy to.

Returns:

The builder.

copyTo

java.io.OutputStream copyTo(java.io.OutputStream stream)
                            throws java.io.IOException

Copies the entire contents of this byte sequence to the provided OutputStream.

Parameters:

stream - The OutputStream to copy to.

Returns:

The OutputStream.

Throws:

java.io.IOException - If an error occurs while writing to the OutputStream.

equals

boolean equals(byte[] b,
             int offset,
             int length)
               throws java.lang.IndexOutOfBoundsException

Indicates whether the provided byte array sub-sequence is equal to this byte sequence. In order for it to be considered equal, the provided byte array sub-sequence must contain the same bytes in the same order.

Parameters:

b - The byte array for which to make the determination.

offset - The offset of the sub-sequence in the byte array to be compared; must be non-negative and no larger than b.length .

length - The length of the sub-sequence in the byte array to be compared; must be non-negative and no larger than b.length - offset.

Returns:

true if the content of the provided byte array sub-sequence is equal to that of this byte sequence, or false if not.

Throws:

java.lang.IndexOutOfBoundsException - If offset is negative or if length is negative or if offset + length is greater than b.length.

equals

boolean equals(java.lang.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 java.lang.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 java.lang.Object

Returns:

A hash code for this byte sequence.

length

int length()

Returns the length of this byte sequence.

Returns:

The length of this byte sequence.

subSequence

ByteSequence subSequence(int start,
                       int end)
                         throws java.lang.IndexOutOfBoundsException

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 byte value at index end - 1. The length (in bytes) of the returned sequence is end - start, so if start == end then an empty sequence is returned.

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

Parameters:

start - The start index, inclusive.

end - The end index, exclusive.

Returns:

The newly created byte subsequence.

Throws:

java.lang.IndexOutOfBoundsException - If start or end are negative, if end is greater than length(), or if start is greater than end.

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.

toString

java.lang.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 java.lang.Object

Returns:

The string representation of this byte sequence.