Protocol Buffers Java API文档翻译：类ByteString,Class ByteString

• public abstract class ByteString

  extends Object

  implements Iterable < Byte >, Serializable

  只读的字节序列。 子字符串（Substring）是通过共享 对只读的底层字节的引用来实现的，这一点与 String 类似。 同样地，串接功能 ， 其实现方式中也避免了进行（长字符串的）复制，具体做法 就是，利用 RopeByteString 来构造 一个由多个片段组成的树。

  与 String 相同的是， ByteString 的内容从来都不会改变，即使 是发生数据冲突或者客户代码 对 API 的误用也不会发生变更。

  参考 ：

  序列 化之后的形式

方法详情

copyFrom

• • • public static ByteString copyFrom(byte[] bytes,

                        int offset,

                        int size)

      将指定的那些字节复制到一个ByteString中去。

      参数 ：

      bytes - 源数组

      offset - 源数组中的起始偏移

      size - 要复制的字节的数个

      返回 ：

      新的 ByteString

copyFrom

• • • public static ByteString copyFrom(byte[] bytes)

      将指定的那些字节复制到一个ByteString中去。

      参数 ：

      bytes  - 要复制的那些字节

      返回 ：

      新的 ByteString

copyFrom

• • • public static ByteString copyFrom(ByteBuffer bytes,

                        int size)

      将一个 java.nio.ByteBuffer 中接下来的 size 个字节复制到一个 ByteString 中去。

      参数 ：

      bytes - 源缓冲区

      size - 要复制的字节个数

      返回 ：

      新的 ByteString

copyFrom

• • • public static ByteString copyFrom(ByteBuffer bytes)

      将一个 java.nio.ByteBuffer 中剩余的那些字节都复制到一个 ByteString 中去。

      参数 ：

      bytes  - 源缓冲区

      返回 ：

      新的 ByteString

copyFrom

• • • public static ByteString copyFrom(String text,

      String charsetName)

                                 throws UnsupportedEncodingException

      使用指定的字符集来将 text 编码为一个字节序列，然后将结果以一个 ByteString 返回。

      参数 ：

      text - 源字符串

      charsetName - 要使用的字符编码

      返回 ：

      新的 ByteString

      抛出异常：

      UnsupportedEncodingException  - 未找到指定 的字符编码

copyFromUtf8

• • • public static ByteString copyFromUtf8(String text)

      将 text 编码为一个UTF-8 字节序列，然后将结果以一个 ByteString 返回。

      参数 ：

      text  - 源字符串

      返回 ：

      新的 ByteString

readFrom

• • • public static ByteString readFrom(InputStream streamToDrain)

                                 throws IOException

      将指定流中全部的字节读入到一个 ByteString 中，必要的情况下会阻塞，直到读取了全部字节并达到流的结尾。性能方面的注意事项：所返回的 ByteString ，是由从流中数据读取的字节数组（“块”）所组成的一个只读的树。第一个块狠小，随后，每个块的尺寸都会是前一个块的两倍，直到达到8K 的尺寸。如果调用者已经知道了那个流的准确尺寸，并且想要避免所有不必要的复制和内存分配，那么，请考虑使用此方法的两个参数的版本，即将在下方说明。

      参数 ：

      streamToDrain  - 源数据流， 会被整个读入，但不会关闭。

      返回 ：

      一个新的 ByteString ， 由各种不同尺寸的数据块组成，具体情况取决 于底层 流的行为。

      抛出异常 ：

      IOException  - 如果 在从底层流读取数据时出现问题，则会抛出 IOException 。

readFrom

• • • public static ByteString readFrom(InputStream streamToDrain,

                        int chunkSize)

                                 throws IOException

      将指定流中全部的字节读入到一个 ByteString 中，必要的情况下会阻塞，直到读取了全部字节并达到流的结尾。性能方面的注意事项：所返回的 ByteString ，是由从流中数据读取的字节数组（“块”）所组成的一个只读的树。chunkSize参数指定了这些字节数组的尺寸。特别地，如果chunkSize恰好等于流的长度，则，就能够避免进行不必要的内存分配及数据复制。否则，那些数据块都会具有指定的尺寸，除了最后一块是例外，最后一块，会改变大小(通过重新分配内存及复制数据的手段)以容纳数据流中剩余的字节。

      参数 ：

      streamToDrain - 源数据流，它会被完全读入，但不会被关闭。

      chunkSize - 在读取数据流的过程中所使用的块的大小。

      返回 ：

      一个新的 ByteString ，由指定尺寸的块组成。

      抛出异常 ：

      IOException  - 如果 在从底层流读取数据时出现问题，则会抛出 IOException 。

readFrom

• • • public static ByteString readFrom(InputStream streamToDrain,

                        int minChunkSize,

                        int maxChunkSize)

                                 throws IOException

      抛出异常 ：

      IOException

copyTo

• • • public void copyTo(byte[] target,

                int offset)

      将字节内容复制到一个缓冲区中以指定偏移开始的地方。

      参数 ：

      target - 要向其中复制字节的目标缓冲区

      offset - 目标缓冲区中的偏移

      抛出异常 ：

      IndexOutOfBoundsException  - 偏移 值为负数，或者太大，则抛出此异常 。

copyTo

• • • public void copyTo(byte[] target,

                int sourceOffset,

                int targetOffset,

                int numberToCopy)

      将多个字节复制到一个缓冲区中。

      参数 ：

      target - 要向其中复制的目标缓冲区

      sourceOffset - 这个源字节字符串中的偏移

      targetOffset - 目标缓冲区中的偏移

      numberToCopy - 要复制的字节个数

      抛出异常 ：

      IndexOutOfBoundsException  - 某个偏移 或尺寸为负数，或者太大，则抛出此异常。

copyTo

• • • public abstract void copyTo(ByteBuffer target)

      将字节内容复制到一个ByteBuffer 中去。

      参数 ：

      target  - 要向其中复制字节的那个ByteBuffer。

      抛出异常 ：

      ReadOnlyBufferException  - 如果target 是只读的，则抛出此异常。

      BufferOverflowException  - 如果target 的可用（remaining()）空间不够大，无法容纳这些数据，则抛出此异常。

toByteArray

writeTo

• • • public abstract void writeTo(OutputStream out)

                            throws IOException

      将这个字节字符串中全部的内容写入到指定的输出流参数中去。

      参数 ：

      out  - 要向其中写入数据的输出流。

      抛出异常 ：

      IOException  - 如果 发生输入/输出错误，则抛出此异常。

asReadOnlyByteBuffer

• • • public abstract ByteBuffer asReadOnlyByteBuffer()

      构造一个只读的 java.nio.ByteBuffer ，其内容与这个字节字符串相同。如果可能的话，该结果会与这个字节字符串共用同一个底层数组。

      返回 ：

      所包装的字节数组

newInput

• • • public abstract InputStream newInput()

      创建一个 InputStream ，它可被用来读取此字节字符串中的那些字节。

      此方法返回的 InputStream ，可确保是完全非阻塞的。 InputStream.available() 方法返回这个流中剩余字节的个数。 InputStream.read(byte[]) 、 InputStream.read(byte[],int,int) 和 InputStream.skip(long) 方法，会读取/跳过尽可能多的字节。

      所返回的 InputStream 中的那些方法，可能并 不是 线程安全的。

      返回 ：

      一个输入流，它会返回此字节字符串中的所有字节。

贾晓晨