0,0 → 1,403 |
// Protocol Buffers - Google's data interchange format |
// Copyright 2008 Google Inc. All rights reserved. |
// http://code.google.com/p/protobuf/ |
// |
// Redistribution and use in source and binary forms, with or without |
// modification, are permitted provided that the following conditions are |
// met: |
// |
// * Redistributions of source code must retain the above copyright |
// notice, this list of conditions and the following disclaimer. |
// * Redistributions in binary form must reproduce the above |
// copyright notice, this list of conditions and the following disclaimer |
// in the documentation and/or other materials provided with the |
// distribution. |
// * Neither the name of Google Inc. nor the names of its |
// contributors may be used to endorse or promote products derived from |
// this software without specific prior written permission. |
// |
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
package com.google.protobuf; |
|
import java.io.InputStream; |
import java.io.ByteArrayInputStream; |
import java.io.ByteArrayOutputStream; |
import java.io.FilterOutputStream; |
import java.io.UnsupportedEncodingException; |
import java.nio.ByteBuffer; |
import java.util.List; |
|
/** |
* Immutable array of bytes. |
* |
* @author crazybob@google.com Bob Lee |
* @author kenton@google.com Kenton Varda |
*/ |
public final class ByteString { |
private final byte[] bytes; |
|
private ByteString(final byte[] bytes) { |
this.bytes = bytes; |
} |
|
/** |
* Gets the byte at the given index. |
* |
* @throws ArrayIndexOutOfBoundsException {@code index} is < 0 or >= size |
*/ |
public byte byteAt(final int index) { |
return bytes[index]; |
} |
|
/** |
* Gets the number of bytes. |
*/ |
public int size() { |
return bytes.length; |
} |
|
/** |
* Returns {@code true} if the size is {@code 0}, {@code false} otherwise. |
*/ |
public boolean isEmpty() { |
return bytes.length == 0; |
} |
|
// ================================================================= |
// byte[] -> ByteString |
|
/** |
* Empty ByteString. |
*/ |
public static final ByteString EMPTY = new ByteString(new byte[0]); |
|
/** |
* Copies the given bytes into a {@code ByteString}. |
*/ |
public static ByteString copyFrom(final byte[] bytes, final int offset, |
final int size) { |
final byte[] copy = new byte[size]; |
System.arraycopy(bytes, offset, copy, 0, size); |
return new ByteString(copy); |
} |
|
/** |
* Copies the given bytes into a {@code ByteString}. |
*/ |
public static ByteString copyFrom(final byte[] bytes) { |
return copyFrom(bytes, 0, bytes.length); |
} |
|
/** |
* Copies {@code size} bytes from a {@code java.nio.ByteBuffer} into |
* a {@code ByteString}. |
*/ |
public static ByteString copyFrom(final ByteBuffer bytes, final int size) { |
final byte[] copy = new byte[size]; |
bytes.get(copy); |
return new ByteString(copy); |
} |
|
/** |
* Copies the remaining bytes from a {@code java.nio.ByteBuffer} into |
* a {@code ByteString}. |
*/ |
public static ByteString copyFrom(final ByteBuffer bytes) { |
return copyFrom(bytes, bytes.remaining()); |
} |
|
/** |
* Encodes {@code text} into a sequence of bytes using the named charset |
* and returns the result as a {@code ByteString}. |
*/ |
public static ByteString copyFrom(final String text, final String charsetName) |
throws UnsupportedEncodingException { |
return new ByteString(text.getBytes(charsetName)); |
} |
|
/** |
* Encodes {@code text} into a sequence of UTF-8 bytes and returns the |
* result as a {@code ByteString}. |
*/ |
public static ByteString copyFromUtf8(final String text) { |
try { |
return new ByteString(text.getBytes("UTF-8")); |
} catch (UnsupportedEncodingException e) { |
throw new RuntimeException("UTF-8 not supported?", e); |
} |
} |
|
/** |
* Concatenates all byte strings in the list and returns the result. |
* |
* <p>The returned {@code ByteString} is not necessarily a unique object. |
* If the list is empty, the returned object is the singleton empty |
* {@code ByteString}. If the list has only one element, that |
* {@code ByteString} will be returned without copying. |
*/ |
public static ByteString copyFrom(List<ByteString> list) { |
if (list.size() == 0) { |
return EMPTY; |
} else if (list.size() == 1) { |
return list.get(0); |
} |
|
int size = 0; |
for (ByteString str : list) { |
size += str.size(); |
} |
byte[] bytes = new byte[size]; |
int pos = 0; |
for (ByteString str : list) { |
System.arraycopy(str.bytes, 0, bytes, pos, str.size()); |
pos += str.size(); |
} |
return new ByteString(bytes); |
} |
|
// ================================================================= |
// ByteString -> byte[] |
|
/** |
* Copies bytes into a buffer at the given offset. |
* |
* @param target buffer to copy into |
* @param offset in the target buffer |
*/ |
public void copyTo(final byte[] target, final int offset) { |
System.arraycopy(bytes, 0, target, offset, bytes.length); |
} |
|
/** |
* Copies bytes into a buffer. |
* |
* @param target buffer to copy into |
* @param sourceOffset offset within these bytes |
* @param targetOffset offset within the target buffer |
* @param size number of bytes to copy |
*/ |
public void copyTo(final byte[] target, final int sourceOffset, |
final int targetOffset, |
final int size) { |
System.arraycopy(bytes, sourceOffset, target, targetOffset, size); |
} |
|
/** |
* Copies bytes into a ByteBuffer. |
* |
* @param target ByteBuffer to copy into. |
* @throws ReadOnlyBufferException if the {@code target} is read-only |
* @throws BufferOverflowException if the {@code target}'s remaining() |
* space is not large enough to hold the data. |
*/ |
public void copyTo(ByteBuffer target) { |
target.put(bytes, 0, bytes.length); |
} |
|
/** |
* Copies bytes to a {@code byte[]}. |
*/ |
public byte[] toByteArray() { |
final int size = bytes.length; |
final byte[] copy = new byte[size]; |
System.arraycopy(bytes, 0, copy, 0, size); |
return copy; |
} |
|
/** |
* Constructs a new read-only {@code java.nio.ByteBuffer} with the |
* same backing byte array. |
*/ |
public ByteBuffer asReadOnlyByteBuffer() { |
final ByteBuffer byteBuffer = ByteBuffer.wrap(bytes); |
return byteBuffer.asReadOnlyBuffer(); |
} |
|
/** |
* Constructs a new {@code String} by decoding the bytes using the |
* specified charset. |
*/ |
public String toString(final String charsetName) |
throws UnsupportedEncodingException { |
return new String(bytes, charsetName); |
} |
|
/** |
* Constructs a new {@code String} by decoding the bytes as UTF-8. |
*/ |
public String toStringUtf8() { |
try { |
return new String(bytes, "UTF-8"); |
} catch (UnsupportedEncodingException e) { |
throw new RuntimeException("UTF-8 not supported?", e); |
} |
} |
|
// ================================================================= |
// equals() and hashCode() |
|
@Override |
public boolean equals(final Object o) { |
if (o == this) { |
return true; |
} |
|
if (!(o instanceof ByteString)) { |
return false; |
} |
|
final ByteString other = (ByteString) o; |
final int size = bytes.length; |
if (size != other.bytes.length) { |
return false; |
} |
|
final byte[] thisBytes = bytes; |
final byte[] otherBytes = other.bytes; |
for (int i = 0; i < size; i++) { |
if (thisBytes[i] != otherBytes[i]) { |
return false; |
} |
} |
|
return true; |
} |
|
private volatile int hash = 0; |
|
@Override |
public int hashCode() { |
int h = hash; |
|
if (h == 0) { |
final byte[] thisBytes = bytes; |
final int size = bytes.length; |
|
h = size; |
for (int i = 0; i < size; i++) { |
h = h * 31 + thisBytes[i]; |
} |
if (h == 0) { |
h = 1; |
} |
|
hash = h; |
} |
|
return h; |
} |
|
// ================================================================= |
// Input stream |
|
/** |
* Creates an {@code InputStream} which can be used to read the bytes. |
*/ |
public InputStream newInput() { |
return new ByteArrayInputStream(bytes); |
} |
|
/** |
* Creates a {@link CodedInputStream} which can be used to read the bytes. |
* Using this is more efficient than creating a {@link CodedInputStream} |
* wrapping the result of {@link #newInput()}. |
*/ |
public CodedInputStream newCodedInput() { |
// We trust CodedInputStream not to modify the bytes, or to give anyone |
// else access to them. |
return CodedInputStream.newInstance(bytes); |
} |
|
// ================================================================= |
// Output stream |
|
/** |
* Creates a new {@link Output} with the given initial capacity. |
*/ |
public static Output newOutput(final int initialCapacity) { |
return new Output(new ByteArrayOutputStream(initialCapacity)); |
} |
|
/** |
* Creates a new {@link Output}. |
*/ |
public static Output newOutput() { |
return newOutput(32); |
} |
|
/** |
* Outputs to a {@code ByteString} instance. Call {@link #toByteString()} to |
* create the {@code ByteString} instance. |
*/ |
public static final class Output extends FilterOutputStream { |
private final ByteArrayOutputStream bout; |
|
/** |
* Constructs a new output with the given initial capacity. |
*/ |
private Output(final ByteArrayOutputStream bout) { |
super(bout); |
this.bout = bout; |
} |
|
/** |
* Creates a {@code ByteString} instance from this {@code Output}. |
*/ |
public ByteString toByteString() { |
final byte[] byteArray = bout.toByteArray(); |
return new ByteString(byteArray); |
} |
} |
|
/** |
* Constructs a new ByteString builder, which allows you to efficiently |
* construct a {@code ByteString} by writing to a {@link CodedOutputStream}. |
* Using this is much more efficient than calling {@code newOutput()} and |
* wrapping that in a {@code CodedOutputStream}. |
* |
* <p>This is package-private because it's a somewhat confusing interface. |
* Users can call {@link Message#toByteString()} instead of calling this |
* directly. |
* |
* @param size The target byte size of the {@code ByteString}. You must |
* write exactly this many bytes before building the result. |
*/ |
static CodedBuilder newCodedBuilder(final int size) { |
return new CodedBuilder(size); |
} |
|
/** See {@link ByteString#newCodedBuilder(int)}. */ |
static final class CodedBuilder { |
private final CodedOutputStream output; |
private final byte[] buffer; |
|
private CodedBuilder(final int size) { |
buffer = new byte[size]; |
output = CodedOutputStream.newInstance(buffer); |
} |
|
public ByteString build() { |
output.checkNoSpaceLeft(); |
|
// We can be confident that the CodedOutputStream will not modify the |
// underlying bytes anymore because it already wrote all of them. So, |
// no need to make a copy. |
return new ByteString(buffer); |
} |
|
public CodedOutputStream getCodedOutput() { |
return output; |
} |
} |
} |