com.dyuproject.protostuff
Class ByteString

java.lang.Object
  com.dyuproject.protostuff.ByteString

public final class ByteString
extends java.lang.Object

Immutable array of bytes.

Author:

crazybob@google.com Bob Lee, kenton@google.com Kenton Varda, David Yu

Field Summary

static ByteString	EMPTY Empty ByteString.
static byte[]	EMPTY_BYTE_ARRAY Empty byte array.
static java.lang.String	EMPTY_STRING Empty String.

Method Summary

java.nio.ByteBuffer	asReadOnlyByteBuffer() Constructs a new read-only java.nio.ByteBuffer with the same backing byte array.
static byte[]	byteArrayDefaultValue(java.lang.String bytes) Helper called by generated code to construct default values for byte array fields.
byte	byteAt(int index) Gets the byte at the given index.
static ByteString	bytesDefaultValue(java.lang.String bytes) Helper called by generated code to construct default values for bytes fields.
static ByteString	copyFrom(byte[] bytes) Copies the given bytes into a ByteString.
static ByteString	copyFrom(byte[] bytes, int offset, int size) Copies the given bytes into a ByteString.
static ByteString	copyFrom(java.lang.String text, java.lang.String charsetName) Encodes text into a sequence of bytes using the named charset and returns the result as a ByteString.
static ByteString	copyFromUtf8(java.lang.String text) Encodes text into a sequence of UTF-8 bytes and returns the result as a ByteString.
void	copyTo(byte[] target, int offset) Copies bytes into a buffer at the given offset.
void	copyTo(byte[] target, int sourceOffset, int targetOffset, int size) Copies bytes into a buffer.
boolean	equals(byte[] data) Returns true if the contents of the internal array and the provided array match.
boolean	equals(byte[] data, int offset, int len) Returns true if the contents of the internal array and the provided array match.
static boolean	equals(ByteString bs, ByteString other, boolean checkHash) Returns true if the contents of both match.
boolean	equals(java.lang.Object o)
int	hashCode()
boolean	isEmpty() Returns true if the size is 0, false otherwise.
int	size() Gets the number of bytes.
static java.lang.String	stringDefaultValue(java.lang.String bytes) Helper called by generated code to construct default values for string fields.
byte[]	toByteArray() Copies bytes to a byte[].
java.lang.String	toString()
java.lang.String	toStringUtf8() Constructs a new String by decoding the bytes as UTF-8.
static void	writeTo(java.io.DataOutput out, ByteString bs) Writes the bytes to the DataOutput.
static void	writeTo(Output output, ByteString bs, int fieldNumber, boolean repeated) Writes the bytes to the Output.
static void	writeTo(java.io.OutputStream out, ByteString bs) Writes the bytes to the OutputStream.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_STRING

public static final java.lang.String EMPTY_STRING

Empty String.

See Also:

Constant Field Values

EMPTY_BYTE_ARRAY

public static final byte[] EMPTY_BYTE_ARRAY

Empty byte array.

EMPTY

public static final ByteString EMPTY

Empty ByteString.

Method Detail

writeTo

public static void writeTo(java.io.OutputStream out,
                           ByteString bs)
                    throws java.io.IOException

Writes the bytes to the OutputStream.

Throws:

java.io.IOException

writeTo

public static void writeTo(java.io.DataOutput out,
                           ByteString bs)
                    throws java.io.IOException

Writes the bytes to the DataOutput.

Throws:

java.io.IOException

writeTo

public static void writeTo(Output output,
                           ByteString bs,
                           int fieldNumber,
                           boolean repeated)
                    throws java.io.IOException

Writes the bytes to the Output.

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

byteAt

public byte byteAt(int index)

Gets the byte at the given index.

Throws:

java.lang.ArrayIndexOutOfBoundsException - index is < 0 or >= size

size

public int size()

Gets the number of bytes.

isEmpty

public boolean isEmpty()

Returns true if the size is 0, false otherwise.

copyFrom

public static ByteString copyFrom(byte[] bytes,
                                  int offset,
                                  int size)

Copies the given bytes into a ByteString.

copyFrom

public static ByteString copyFrom(byte[] bytes)

Copies the given bytes into a ByteString.

copyFrom

public static ByteString copyFrom(java.lang.String text,
                                  java.lang.String charsetName)

Encodes text into a sequence of bytes using the named charset and returns the result as a ByteString.

copyFromUtf8

public static ByteString copyFromUtf8(java.lang.String text)

Encodes text into a sequence of UTF-8 bytes and returns the result as a ByteString.

copyTo

public void copyTo(byte[] target,
                   int offset)

Copies bytes into a buffer at the given offset.

Parameters:

target - buffer to copy into

offset - in the target buffer

copyTo

public void copyTo(byte[] target,
                   int sourceOffset,
                   int targetOffset,
                   int size)

Copies bytes into a buffer.

Parameters:

target - buffer to copy into

sourceOffset - offset within these bytes

targetOffset - offset within the target buffer

size - number of bytes to copy

toByteArray

public byte[] toByteArray()

Copies bytes to a byte[].

asReadOnlyByteBuffer

public java.nio.ByteBuffer asReadOnlyByteBuffer()

Constructs a new read-only java.nio.ByteBuffer with the same backing byte array.

toStringUtf8

public java.lang.String toStringUtf8()

Constructs a new String by decoding the bytes as UTF-8.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

equals

public static boolean equals(ByteString bs,
                             ByteString other,
                             boolean checkHash)

Returns true if the contents of both match.

equals

public boolean equals(byte[] data)

Returns true if the contents of the internal array and the provided array match.

equals

public boolean equals(byte[] data,
                      int offset,
                      int len)

Returns true if the contents of the internal array and the provided array match.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

stringDefaultValue

public static java.lang.String stringDefaultValue(java.lang.String bytes)

Helper called by generated code to construct default values for string fields.

The protocol compiler does not actually contain a UTF-8 decoder -- it just pushes UTF-8-encoded text around without touching it. The one place where this presents a problem is when generating Java string literals. Unicode characters in the string literal would normally need to be encoded using a Unicode escape sequence, which would require decoding them. To get around this, protoc instead embeds the UTF-8 bytes into the generated code and leaves it to the runtime library to decode them.

It gets worse, though. If protoc just generated a byte array, like: new byte[] {0x12, 0x34, 0x56, 0x78} Java actually generates *code* which allocates an array and then fills in each value. This is much less efficient than just embedding the bytes directly into the bytecode. To get around this, we need another work-around. String literals are embedded directly, so protoc actually generates a string literal corresponding to the bytes. The easiest way to do this is to use the ISO-8859-1 character set, which corresponds to the first 256 characters of the Unicode range. Protoc can then use good old CEscape to generate the string.

So we have a string literal which represents a set of bytes which represents another string. This function -- stringDefaultValue -- converts from the generated string to the string we actually want. The generated code calls this automatically.

bytesDefaultValue

public static ByteString bytesDefaultValue(java.lang.String bytes)

Helper called by generated code to construct default values for bytes fields.

This is a lot like stringDefaultValue(java.lang.String), but for bytes fields. In this case we only need the second of the two hacks -- allowing us to embed raw bytes as a string literal with ISO-8859-1 encoding.

byteArrayDefaultValue

public static byte[] byteArrayDefaultValue(java.lang.String bytes)

Helper called by generated code to construct default values for byte array fields.

This is a lot like stringDefaultValue(java.lang.String), but for bytes fields. In this case we only need the second of the two hacks -- allowing us to embed raw bytes as a string literal with ISO-8859-1 encoding.