io.netty.util

Class ByteString

java.lang.Object

io.netty.util.ByteString

Direct Known Subclasses:

AsciiString

public class ByteString
extends Object

The primary use case for this class is to function as an immutable array of bytes. For performance reasons this class supports sharing memory with external arrays, and also direct access to the underlying memory via array(). Care must be taken when directly accessing the memory as that may invalidate assumptions that this object is immutable.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static interface	ByteString.ByteStringFactory Allows sub classes to take advantage of ByteString operations which need to generate new ByteString objects.

Field Summary

Fields

Modifier and Type	Field and Description
static ByteString	EMPTY_STRING
protected static int	HASH_CODE_PRIME
protected byte[]	value If this value is modified outside the constructor then call arrayChanged().

Constructor Summary

Constructors

Constructor and Description
ByteString(byte[] value) Initialize this byte string based upon a byte array.
ByteString(byte[] value, boolean copy) Initialize this byte string based upon a byte array.
ByteString(byte[] value, int start, int length, boolean copy) Construct a new BinaryString object from a byte[] array.
ByteString(ByteBuffer value) Create a copy of the underlying storage from value.
ByteString(ByteBuffer value, boolean copy) Initialize a ByteString based upon the underlying storage from value.
ByteString(ByteBuffer value, int start, int length, boolean copy) Initialize a ByteString based upon the underlying storage from value.
ByteString(ByteString value, boolean copy) Create a new object which is equal to value.
ByteString(char[] value, Charset charset) Create a copy of value into a ByteString using the encoding type of charset.
ByteString(char[] value, Charset charset, int start, int length) Create a copy of value into a ByteString using the encoding type of charset.
ByteString(CharSequence value, Charset charset) Create a copy of value into a ByteString using the encoding type of charset.
ByteString(CharSequence value, Charset charset, int start, int length) Create a copy of value into a ByteString using the encoding type of charset.

Method Summary

Methods

Modifier and Type	Method and Description
byte[]	array() This gives direct access to the underlying storage array.
void	arrayChanged() During normal use cases the ByteString should be immutable, but if the underlying array is shared, and changes then this needs to be called.
int	arrayOffset() The offset into array() for which data for this ByteString begins.
byte	byteAt(int index)
void	copy(int srcIdx, byte[] dst, int dstIdx, int length) Copies the content of this string to a byte array.
boolean	equals(Object obj)
int	forEachByte(ByteProcessor visitor) Iterates over the readable bytes of this buffer with the specified processor in ascending order.
int	forEachByte(int index, int length, ByteProcessor visitor) Iterates over the specified area of this buffer with the specified processor in ascending order.
int	forEachByteDesc(ByteProcessor visitor) Iterates over the readable bytes of this buffer with the specified processor in descending order.
int	forEachByteDesc(int index, int length, ByteProcessor visitor) Iterates over the specified area of this buffer with the specified processor in descending order.
static ByteString	fromAscii(CharSequence value) Create a new ByteString assuming ASCII encoding of value.
int	hashCode()
boolean	isEmpty()
boolean	isEntireArrayUsed() Determine if the storage represented by array() is entirely used.
int	length()
double	parseAsciiDouble()
double	parseAsciiDouble(int start, int end)
float	parseAsciiFloat()
float	parseAsciiFloat(int start, int end)
int	parseAsciiInt()
int	parseAsciiInt(int radix)
int	parseAsciiInt(int start, int end)
int	parseAsciiInt(int start, int end, int radix)
long	parseAsciiLong()
long	parseAsciiLong(int radix)
long	parseAsciiLong(int start, int end)
long	parseAsciiLong(int start, int end, int radix)
short	parseAsciiShort()
short	parseAsciiShort(int radix)
short	parseAsciiShort(int start, int end)
short	parseAsciiShort(int start, int end, int radix)
char	parseChar()
char	parseChar(int start)
ByteString	subSequence(int start) Copies a range of characters into a new string.
ByteString	subSequence(int start, int end) Copies a range of characters into a new string.
ByteString	subSequence(int start, int end, boolean copy) Either copy or share a subset of underlying sub-sequence of bytes.
protected ByteString	subSequence(int start, int end, boolean copy, ByteString.ByteStringFactory factory) Either copy or share a subset of underlying sub-sequence of bytes.
byte[]	toByteArray() Converts this string to a byte array.
byte[]	toByteArray(int start, int end) Converts a subset of this string to a byte array.
String	toString() Translates the entire byte string to a String.
String	toString(Charset charset) Translates the entire byte string to a String using the charset encoding.
String	toString(Charset charset, int start, int end) Translates the [start, end) range of this byte string to a String using the charset encoding.
String	toString(int start, int end) Translates the [start, end) range of this byte string to a String.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_STRING

public static final ByteString EMPTY_STRING

HASH_CODE_PRIME

protected static final int HASH_CODE_PRIME

See Also:

Constant Field Values

value

protected final byte[] value

If this value is modified outside the constructor then call arrayChanged().

Constructor Detail

ByteString

public ByteString(byte[] value)

Initialize this byte string based upon a byte array. A copy will be made.

ByteString

public ByteString(byte[] value,
          boolean copy)

Initialize this byte string based upon a byte array. copy determines if a copy is made or the array is shared.

ByteString

public ByteString(byte[] value,
          int start,
          int length,
          boolean copy)

Construct a new BinaryString object from a byte[] array.

Parameters:

copy - true then a copy of the memory will be made. false the underlying memory will be shared.

ByteString

public ByteString(ByteString value,
          boolean copy)

Create a new object which is equal to value.

Parameters:

value - The object to replicate.

copy - true mean the underlying storage will be copied. false means the underlying storage will be shared.

ByteString

public ByteString(ByteBuffer value)

Create a copy of the underlying storage from value. The copy will start at Buffer.position() and copy Buffer.remaining() bytes.

ByteString

public ByteString(ByteBuffer value,
          boolean copy)

Initialize a ByteString based upon the underlying storage from value. There is a potential to share the underlying array storage if ByteBuffer.hasArray() is true. if copy is true a copy will be made of the memory. if copy is false the underlying storage will be shared, if possible.

ByteString

public ByteString(ByteBuffer value,
          int start,
          int length,
          boolean copy)

Initialize a ByteString based upon the underlying storage from value. There is a potential to share the underlying array storage if ByteBuffer.hasArray() is true. if copy is true a copy will be made of the memory. if copy is false the underlying storage will be shared, if possible.

ByteString

public ByteString(char[] value,
          Charset charset)

Create a copy of value into a ByteString using the encoding type of charset.

ByteString

public ByteString(char[] value,
          Charset charset,
          int start,
          int length)

Create a copy of value into a ByteString using the encoding type of charset. The copy will start at index start and copy length bytes.

ByteString

public ByteString(CharSequence value,
          Charset charset)

Create a copy of value into a ByteString using the encoding type of charset.

ByteString

public ByteString(CharSequence value,
          Charset charset,
          int start,
          int length)

Create a copy of value into a ByteString using the encoding type of charset. The copy will start at index start and copy length bytes.

Method Detail

fromAscii

public static final ByteString fromAscii(CharSequence value)

Create a new ByteString assuming ASCII encoding of value.

Parameters:

value - value to translate assuming ASCII encoding.

forEachByte

public final int forEachByte(ByteProcessor visitor)
                      throws Exception

Iterates over the readable bytes of this buffer with the specified processor in ascending order.

Returns:

-1 if the processor iterated to or beyond the end of the readable bytes. The last-visited index If the ByteProcessor.process(byte) returned false.

Throws:

Exception

forEachByte

public final int forEachByte(int index,
              int length,
              ByteProcessor visitor)
                      throws Exception

Iterates over the specified area of this buffer with the specified processor in ascending order. (i.e. index, (index + 1), .. (index + length - 1)).

Returns:

-1 if the processor iterated to or beyond the end of the specified area. The last-visited index If the ByteProcessor.process(byte) returned false.

Throws:

Exception

forEachByteDesc

public final int forEachByteDesc(ByteProcessor visitor)
                          throws Exception

Iterates over the readable bytes of this buffer with the specified processor in descending order.

Returns:

-1 if the processor iterated to or beyond the beginning of the readable bytes. The last-visited index If the ByteProcessor.process(byte) returned false.

Throws:

Exception

forEachByteDesc

public final int forEachByteDesc(int index,
                  int length,
                  ByteProcessor visitor)
                          throws Exception

Iterates over the specified area of this buffer with the specified processor in descending order. (i.e. (index + length - 1), (index + length - 2), ... index).

Returns:

-1 if the processor iterated to or beyond the beginning of the specified area. The last-visited index If the ByteProcessor.process(byte) returned false.

Throws:

Exception

byteAt

public final byte byteAt(int index)

isEmpty

public final boolean isEmpty()

length

public final int length()

arrayChanged

public void arrayChanged()

During normal use cases the ByteString should be immutable, but if the underlying array is shared, and changes then this needs to be called.

array

public final byte[] array()

This gives direct access to the underlying storage array. The toByteArray() should be preferred over this method. If the return value is changed then arrayChanged() must be called.

See Also:

arrayOffset(), isEntireArrayUsed()

arrayOffset

public final int arrayOffset()

The offset into array() for which data for this ByteString begins.

See Also:

array(), isEntireArrayUsed()

isEntireArrayUsed

public final boolean isEntireArrayUsed()

Determine if the storage represented by array() is entirely used.

See Also:

array()

toByteArray

public final byte[] toByteArray()

Converts this string to a byte array.

toByteArray

public final byte[] toByteArray(int start,
                 int end)

Converts a subset of this string to a byte array. The subset is defined by the range [start, end).

copy

public final void copy(int srcIdx,
        byte[] dst,
        int dstIdx,
        int length)

Copies the content of this string to a byte array.

Parameters:

srcIdx - the starting offset of characters to copy.

dst - the destination byte array.

dstIdx - the starting offset in the destination byte array.

length - the number of characters to copy.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

subSequence

public ByteString subSequence(int start)

Copies a range of characters into a new string.

Parameters:

start - the offset of the first character (inclusive).

Returns:

a new string containing the characters from start to the end of the string.

Throws:

IndexOutOfBoundsException - if start < 0 or start > length().

subSequence

public ByteString subSequence(int start,
                     int end)

Copies a range of characters into a new string.

Parameters:

start - the offset of the first character (inclusive).

end - The index to stop at (exclusive).

Returns:

a new string containing the characters from start to the end of the string.

Throws:

IndexOutOfBoundsException - if start < 0 or start > length().

subSequence

public ByteString subSequence(int start,
                     int end,
                     boolean copy)

Either copy or share a subset of underlying sub-sequence of bytes.

Parameters:

start - the offset of the first character (inclusive).

end - The index to stop at (exclusive).

copy - If true then a copy of the underlying storage will be made. If false then the underlying storage will be shared.

Returns:

a new string containing the characters from start to the end of the string.

Throws:

IndexOutOfBoundsException - if start < 0 or start > length().

subSequence

protected ByteString subSequence(int start,
                     int end,
                     boolean copy,
                     ByteString.ByteStringFactory factory)

Either copy or share a subset of underlying sub-sequence of bytes.

Parameters:

start - the offset of the first character (inclusive).

end - The index to stop at (exclusive).

copy - If true then a copy of the underlying storage will be made. If false then the underlying storage will be shared.

factory - The factory used to generate a new ByteString object.

Returns:

a new string containing the characters from start to the end of the string.

Throws:

IndexOutOfBoundsException - if start < 0 or start > length().

parseAsciiInt

public final int parseAsciiInt()

parseAsciiInt

public final int parseAsciiInt(int radix)

parseAsciiInt

public final int parseAsciiInt(int start,
                int end)

parseAsciiInt

public final int parseAsciiInt(int start,
                int end,
                int radix)

parseAsciiLong

public final long parseAsciiLong()

parseAsciiLong

public final long parseAsciiLong(int radix)

parseAsciiLong

public final long parseAsciiLong(int start,
                  int end)

parseAsciiLong

public final long parseAsciiLong(int start,
                  int end,
                  int radix)

parseChar

public final char parseChar()

parseChar

public char parseChar(int start)

parseAsciiShort

public final short parseAsciiShort()

parseAsciiShort

public final short parseAsciiShort(int radix)

parseAsciiShort

public final short parseAsciiShort(int start,
                    int end)

parseAsciiShort

public final short parseAsciiShort(int start,
                    int end,
                    int radix)

parseAsciiFloat

public final float parseAsciiFloat()

parseAsciiFloat

public final float parseAsciiFloat(int start,
                    int end)

parseAsciiDouble

public final double parseAsciiDouble()

parseAsciiDouble

public final double parseAsciiDouble(int start,
                      int end)

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString()

Translates the entire byte string to a String.

Overrides:

toString in class Object

See Also:

#toString(int, int)}

toString

public final String toString(Charset charset)

Translates the entire byte string to a String using the charset encoding.

See Also:

#toString(Charset, int, int)}

toString

public final String toString(int start,
              int end)

Translates the [start, end) range of this byte string to a String.

See Also:

#toString(Charset, int, int)}

toString

public String toString(Charset charset,
              int start,
              int end)

Translates the [start, end) range of this byte string to a String using the charset encoding.