ByteStreams
Date: 2016-05-24

com.google.common.io

## Class ByteStreams

- java.lang.Object
- - com.google.common.io.ByteStreams

-     @Beta
      public final class ByteStreams
      extends java.lang.Object

  Provides utility methods for working with byte arrays and I/O streams.
  Since:
    1.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static long` | `copy(java.io.InputStream from, java.io.OutputStream to)` Copies all bytes from the input stream to the output stream.
    `static long` | `copy(java.nio.channels.ReadableByteChannel from, java.nio.channels.WritableByteChannel to)` Copies all bytes from the readable channel to the writable channel.
    `static java.io.InputStream` | `limit(java.io.InputStream in, long limit)` Wraps a `InputStream`, limiting the number of bytes which can be read.
    `static ByteArrayDataInput` | `newDataInput(byte[] bytes)` Returns a new `ByteArrayDataInput` instance to read from the `bytes` array from the beginning.
    `static ByteArrayDataInput` | `newDataInput(byte[] bytes, int start)` Returns a new `ByteArrayDataInput` instance to read from the `bytes` array, starting at the given position.
    `static ByteArrayDataInput` | `newDataInput(java.io.ByteArrayInputStream byteArrayInputStream)` Returns a new `ByteArrayDataInput` instance to read from the given `ByteArrayInputStream`.
    `static ByteArrayDataOutput` | `newDataOutput()` Returns a new `ByteArrayDataOutput` instance with a default size.
    `static ByteArrayDataOutput` | `newDataOutput(java.io.ByteArrayOutputStream byteArrayOutputSteam)` Returns a new `ByteArrayDataOutput` instance which writes to the given `ByteArrayOutputStream`.
    `static ByteArrayDataOutput` | `newDataOutput(int size)` Returns a new `ByteArrayDataOutput` instance sized to hold `size` bytes before resizing.
    `static java.io.OutputStream` | `nullOutputStream()` Returns an `OutputStream` that simply discards written bytes.
    `static int` | `read(java.io.InputStream in, byte[] b, int off, int len)` Reads some bytes from an input stream and stores them into the buffer array `b`.
    `static <T> T` | `readBytes(java.io.InputStream input, ByteProcessor<T> processor)` Process the bytes of the given input stream using the given processor.
    `static void` | `readFully(java.io.InputStream in, byte[] b)` Attempts to read enough bytes from the stream to fill the given byte array, with the same behavior as `DataInput.readFully(byte[])`.
    `static void` | `readFully(java.io.InputStream in, byte[] b, int off, int len)` Attempts to read `len` bytes from the stream into the given array starting at `off`, with the same behavior as `DataInput.readFully(byte[], int, int)`.
    `static void` | `skipFully(java.io.InputStream in, long n)` Discards `n` bytes of data from the input stream.
    `static byte[]` | `toByteArray(java.io.InputStream in)` Reads all bytes from an input stream into a byte array.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### copy

          public static long copy(java.io.InputStream from,
                  java.io.OutputStream to)
                           throws java.io.IOException

      Copies all bytes from the input stream to the output stream. Does not close or flush either stream.
      Parameters:
        `from` - the input stream to read from
        `to` - the output stream to write to
      Returns:
        the number of bytes copied
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### copy

          public static long copy(java.nio.channels.ReadableByteChannel from,
                  java.nio.channels.WritableByteChannel to)
                           throws java.io.IOException

      Copies all bytes from the readable channel to the writable channel. Does not close or flush either channel.
      Parameters:
        `from` - the readable channel to read from
        `to` - the writable channel to write to
      Returns:
        the number of bytes copied
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### toByteArray

          public static byte[] toByteArray(java.io.InputStream in)
                                    throws java.io.IOException

      Reads all bytes from an input stream into a byte array. Does not close the stream.
      Parameters:
        `in` - the input stream to read from
      Returns:
        a byte array containing all the bytes from the stream
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### newDataInput

          public static ByteArrayDataInput newDataInput(byte[] bytes)

      Returns a new `ByteArrayDataInput` instance to read from the `bytes` array from the beginning.

    - #### newDataInput

          public static ByteArrayDataInput newDataInput(byte[] bytes,
                                        int start)

      Returns a new `ByteArrayDataInput` instance to read from the `bytes` array, starting at the given position.
      Throws:
        `java.lang.IndexOutOfBoundsException` - if `start` is negative or greater than the length of the array

    - #### newDataInput

          public static ByteArrayDataInput newDataInput(java.io.ByteArrayInputStream byteArrayInputStream)

      Returns a new `ByteArrayDataInput` instance to read from the given `ByteArrayInputStream`. The given input stream is not reset before being read from by the returned `ByteArrayDataInput`.
      Since:
        17.0

    - #### newDataOutput

          public static ByteArrayDataOutput newDataOutput()

      Returns a new `ByteArrayDataOutput` instance with a default size.

    - #### newDataOutput

          public static ByteArrayDataOutput newDataOutput(int size)

      Returns a new `ByteArrayDataOutput` instance sized to hold `size` bytes before resizing.
      Throws:
        `java.lang.IllegalArgumentException` - if `size` is negative

    - #### newDataOutput

          public static ByteArrayDataOutput newDataOutput(java.io.ByteArrayOutputStream byteArrayOutputSteam)

      Returns a new `ByteArrayDataOutput` instance which writes to the given `ByteArrayOutputStream`. The given output stream is not reset before being written to by the returned `ByteArrayDataOutput` and new data will be appended to any existing content.

      Note that if the given output stream was not empty or is modified after the `ByteArrayDataOutput` is created, the contract for `ByteArrayDataOutput.toByteArray()` will not be honored (the bytes returned in the byte array may not be exactly what was written via calls to `ByteArrayDataOutput`).

      Since:
        17.0

    - #### nullOutputStream

          public static java.io.OutputStream nullOutputStream()

      Returns an `OutputStream` that simply discards written bytes.
      Since:
        14.0 (since 1.0 as com.google.common.io.NullOutputStream)

    - #### limit

          public static java.io.InputStream limit(java.io.InputStream in,
                                  long limit)

      Wraps a `InputStream`, limiting the number of bytes which can be read.
      Parameters:
        `in` - the input stream to be wrapped
        `limit` - the maximum number of bytes to be read
      Returns:
        a length-limited `InputStream`
      Since:
        14.0 (since 1.0 as com.google.common.io.LimitInputStream)

    - #### readFully

          public static void readFully(java.io.InputStream in,
                       byte[] b)
                                throws java.io.IOException

      Attempts to read enough bytes from the stream to fill the given byte array, with the same behavior as `DataInput.readFully(byte[])`. Does not close the stream.
      Parameters:
        `in` - the input stream to read from.
        `b` - the buffer into which the data is read.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading all the bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### readFully

          public static void readFully(java.io.InputStream in,
                       byte[] b,
                       int off,
                       int len)
                                throws java.io.IOException

      Attempts to read `len` bytes from the stream into the given array starting at `off`, with the same behavior as `DataInput.readFully(byte[], int, int)`. Does not close the stream.
      Parameters:
        `in` - the input stream to read from.
        `b` - the buffer into which the data is read.
        `off` - an int specifying the offset into the data.
        `len` - an int specifying the number of bytes to read.
      Throws:
        `java.io.EOFException` - if this stream reaches the end before reading all the bytes.
        `java.io.IOException` - if an I/O error occurs.

    - #### skipFully

          public static void skipFully(java.io.InputStream in,
                       long n)
                                throws java.io.IOException

      Discards `n` bytes of data from the input stream. This method will block until the full amount has been skipped. Does not close the stream.
      Parameters:
        `in` - the input stream to read from
        `n` - the number of bytes to skip
      Throws:
        `java.io.EOFException` - if this stream reaches the end before skipping all the bytes
        `java.io.IOException` - if an I/O error occurs, or the stream does not support skipping

    - #### readBytes

          public static <T> T readBytes(java.io.InputStream input,
                        ByteProcessor<T> processor)
                             throws java.io.IOException

      Process the bytes of the given input stream using the given processor.
      Parameters:
        `input` - the input stream to process
        `processor` - the object to which to pass the bytes of the stream
      Returns:
        the result of the byte processor
      Throws:
        `java.io.IOException` - if an I/O error occurs
      Since:
        14.0

    - #### read

          public static int read(java.io.InputStream in,
                 byte[] b,
                 int off,
                 int len)
                          throws java.io.IOException

      Reads some bytes from an input stream and stores them into the buffer array `b`. This method blocks until `len` bytes of input data have been read into the array, or end of file is detected. The number of bytes read is returned, possibly zero. Does not close the stream.

      A caller can detect EOF if the number of bytes read is less than `len`. All subsequent calls on the same stream will return zero.

      If `b` is null, a `NullPointerException` is thrown. If `off` is negative, or `len` is negative, or `off+len` is greater than the length of the array `b`, then an `IndexOutOfBoundsException` is thrown. If `len` is zero, then no bytes are read. Otherwise, the first byte read is stored into element `b[off]`, the next one into `b[off+1]`, and so on. The number of bytes read is, at most, equal to `len`.

      Parameters:
        `in` - the input stream to read from
        `b` - the buffer into which the data is read
        `off` - an int specifying the offset into the data
        `len` - an int specifying the number of bytes to read
      Returns:
        the number of bytes read
      Throws:
        `java.io.IOException` - if an I/O error occurs