org.apache.commons.io.input.buffer

## Class CircularByteBuffer

- java.lang.Object
- - org.apache.commons.io.input.buffer.CircularByteBuffer

-     public class CircularByteBuffer
      extends Object

  A buffer, which doesn't need reallocation of byte arrays, because it reuses a single byte array. This works particularly well, if reading from the buffer takes place at the same time than writing to. Such is the case, for example, when using the buffer within a filtering input stream, like the `CircularBufferInputStream`.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CircularByteBuffer()` Creates a new instance with a reasonable default buffer size (`IOUtils.DEFAULT_BUFFER_SIZE`).
    `CircularByteBuffer(int size)` Creates a new instance with the given buffer size.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(byte value)` Adds a new byte to the buffer, which will eventually be returned by following invocations of `read()`.
    `void` | `add(byte[] targetBuffer, int offset, int length)` Adds the given bytes to the buffer.
    `void` | `clear()` Removes all bytes from the buffer.
    `int` | `getCurrentNumberOfBytes()` Returns the number of bytes, that are currently present in the buffer.
    `int` | `getSpace()` Returns the number of bytes, that can currently be added to the buffer.
    `boolean` | `hasBytes()` Returns, whether the buffer is currently holding, at least, a single byte.
    `boolean` | `hasSpace()` Returns, whether there is currently room for a single byte in the buffer.
    `boolean` | `hasSpace(int count)` Returns, whether there is currently room for the given number of bytes in the buffer.
    `boolean` | `peek(byte[] sourceBuffer, int offset, int length)` Returns, whether the next bytes in the buffer are exactly those, given by `sourceBuffer`, `offset`, and `length`.
    `byte` | `read()` Returns the next byte from the buffer, removing it at the same time, so that following invocations won't return it again.
    `void` | `read(byte[] targetBuffer, int targetOffset, int length)` Returns the given number of bytes from the buffer by storing them in the given byte array at the given offset.

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

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

- - ### Constructor Detail

    - #### CircularByteBuffer

          public CircularByteBuffer(int size)

      Creates a new instance with the given buffer size.
      Parameters:
        `size` - the size of buffer to create

    - #### CircularByteBuffer

          public CircularByteBuffer()

      Creates a new instance with a reasonable default buffer size (`IOUtils.DEFAULT_BUFFER_SIZE`).

  - ### Method Detail

    - #### read

          public byte read()

      Returns the next byte from the buffer, removing it at the same time, so that following invocations won't return it again.
      Returns:
        The byte, which is being returned.
      Throws:
        `IllegalStateException` - The buffer is empty. Use `hasBytes()`, or `getCurrentNumberOfBytes()`, to prevent this exception.

    - #### read

          public void read(byte[] targetBuffer,
                           int targetOffset,
                           int length)

      Returns the given number of bytes from the buffer by storing them in the given byte array at the given offset.
      Parameters:
        `targetBuffer` - The byte array, where to add bytes.
        `targetOffset` - The offset, where to store bytes in the byte array.
        `length` - The number of bytes to return.
      Throws:
        `NullPointerException` - The byte array `pBuffer` is null.
        `IllegalArgumentException` - Either of `pOffset`, or `length` is negative, or the length of the byte array `targetBuffer` is too small.
        `IllegalStateException` - The buffer doesn't hold the given number of bytes. Use `getCurrentNumberOfBytes()` to prevent this exception.

    - #### add

          public void add(byte value)

      Adds a new byte to the buffer, which will eventually be returned by following invocations of `read()`.
      Parameters:
        `value` - The byte, which is being added to the buffer.
      Throws:
        `IllegalStateException` - The buffer is full. Use `hasSpace()`, or `getSpace()`, to prevent this exception.

    - #### peek

          public boolean peek(byte[] sourceBuffer,
                              int offset,
                              int length)

      Returns, whether the next bytes in the buffer are exactly those, given by `sourceBuffer`, `offset`, and `length`. No bytes are being removed from the buffer. If the result is true, then the following invocations of `read()` are guaranteed to return exactly those bytes.
      Parameters:
        `sourceBuffer` - the buffer to compare against
        `offset` - start offset
        `length` - length to compare
      Returns:
        True, if the next invocations of `read()` will return the bytes at offsets `pOffset`+0, `pOffset`+1, ..., `pOffset`+`length`-1 of byte array `pBuffer`.
      Throws:
        `IllegalArgumentException` - Either of `pOffset`, or `length` is negative.
        `NullPointerException` - The byte array `pBuffer` is null.

    - #### add

          public void add(byte[] targetBuffer,
                          int offset,
                          int length)

      Adds the given bytes to the buffer. This is the same as invoking `add(byte)` for the bytes at offsets `offset+0`, `offset+1`, ..., `offset+length-1` of byte array `targetBuffer`.
      Parameters:
        `targetBuffer` - the buffer to copy
        `offset` - start offset
        `length` - length to copy
      Throws:
        `IllegalStateException` - The buffer doesn't have sufficient space. Use `getSpace()` to prevent this exception.
        `IllegalArgumentException` - Either of `offset`, or `length` is negative.
        `NullPointerException` - The byte array `pBuffer` is null.

    - #### hasSpace

          public boolean hasSpace()

      Returns, whether there is currently room for a single byte in the buffer. Same as `hasSpace(1)`.
      Returns:
        true if there is space for a byte
      See Also:
        `hasSpace(int)`, `getSpace()`

    - #### hasSpace

          public boolean hasSpace(int count)

      Returns, whether there is currently room for the given number of bytes in the buffer.
      Parameters:
        `count` - the byte count
      Returns:
        true if there is space for the given number of bytes
      See Also:
        `hasSpace()`, `getSpace()`

    - #### hasBytes

          public boolean hasBytes()

      Returns, whether the buffer is currently holding, at least, a single byte.
      Returns:
        true if the buffer is not empty

    - #### getSpace

          public int getSpace()

      Returns the number of bytes, that can currently be added to the buffer.
      Returns:
        the number of bytes that can be added

    - #### getCurrentNumberOfBytes

          public int getCurrentNumberOfBytes()

      Returns the number of bytes, that are currently present in the buffer.
      Returns:
        the number of bytes

    - #### clear

          public void clear()

      Removes all bytes from the buffer.

Copyright © 2002–2021 The Apache Software Foundation. All rights reserved.