de.caff.util

## Class ByteRingBuffer

- java.lang.Object
- - de.caff.util.ByteRingBuffer

- All Implemented Interfaces:
    ByteCollector

      public class ByteRingBuffer
      extends java.lang.Object
      implements ByteCollector

  A byte buffer to which you can add data bytes up to a maximum size.

  If the buffer overflows you can only retrieve the latest getLimit() bytes.

  Since:
    August 10, 2022
  Author:
    Rammi

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static int` | `INITIAL_LIMIT` Initial limit: 1 MiB.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ByteRingBuffer(int limit)` Create a ring buffer with the given size.
    `ByteRingBuffer(int limit, int initialLimit)` Create a ring buffer with the given size.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `append(byte[] bytes, int offset, int length)` Append the given byte array part to this buffer.
    `void` | `append(int value)` Append one byte
    `void` | `clear()` Clear all data.
    `int` | `getLimit()` Get the limit of this ring buffer.
    `long` | `getNumberOfCollectedBytes()` Get the total number of bytes appended to this buffer.
    `int` | `size()` Get the number of valid bytes cached in this buffer.
    `byte[]` | `toByteArray()` Create a byte array with the bytes in this buffer.
    `ByteIndexable` | `toByteIndexable()` Get a stable byte indexable from this buffer.
    `ByteIndexable` | `view()` Get a byte indexable view of this ring buffer.

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

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

    - ### Methods inherited from interface de.caff.util.ByteCollector

      `append`

- - ### Field Detail

    - #### INITIAL_LIMIT

          static final int INITIAL_LIMIT

      Initial limit: 1 MiB.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ByteRingBuffer

          public ByteRingBuffer(int limit)

      Create a ring buffer with the given size.
      Parameters:
        `limit` - size limit of this buffer

    - #### ByteRingBuffer

          ByteRingBuffer(int limit,
                         int initialLimit)

      Create a ring buffer with the given size. This allows to set the initial limit for testing.
      Parameters:
        `limit` - size limit of this buffer
        `initialLimit` - initial limit

  - ### Method Detail

    - #### getLimit

          public int getLimit()

      Get the limit of this ring buffer.
      Returns:
        buffer limit

    - #### size

          public int size()

      Get the number of valid bytes cached in this buffer.
      Returns:
        number of bytes cached

    - #### append

          public void append(int value)

      Append one byte
      Specified by:
        `append` in interface `ByteCollector`
      Parameters:
        `value` - byte value. Accepts integer for convenience, but will cast the given value to byte.

    - #### append

          public void append(@NotNull
                             byte[] bytes,
                             int offset,
                             int length)

      Append the given byte array part to this buffer.
      Specified by:
        `append` in interface `ByteCollector`
      Parameters:
        `bytes` - basic byte array
        `offset` - start offset of the bytes to append
        `length` - number of bytes to append
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the parameters define a part which is at least partially outside the `bytes`

    - #### toByteArray

          @NotNull
          public byte[] toByteArray()

      Create a byte array with the bytes in this buffer.
      Returns:
        byte array of size size() containing with the buffered bytes

    - #### view

          @NotNull
          public ByteIndexable view()

      Get a byte indexable view of this ring buffer.

      This is more efficient than copying all bytes in toByteArray(), especially if only a few bytes of a larger content are of interest. But the price is high: any change to this buffer can break the returned view. So this is best used on a finished buffer.

      Returns:
        byte indexable view of this buffer
      See Also:
        `toByteIndexable()`, `toByteArray()`

    - #### toByteIndexable

          @NotNull
          public ByteIndexable toByteIndexable()

      Get a stable byte indexable from this buffer.

      Compared to `view()` the returned indexable is decoupled from this buffer, with the price of a copy of the bytes. Compared to the result of

           ByteIndexable.viewArray(ringBuffer.toByteArray())

      this method provides an already frozen byte indexable.
      Returns:
        stable frozen byte indexable
      See Also:
        `toByteArray()`, `view()`

    - #### clear

          public void clear()

      Clear all data. This will clear everything but `the total number of bytes handled by this buffer`.
      Specified by:
        `clear` in interface `ByteCollector`

    - #### getNumberOfCollectedBytes

          public long getNumberOfCollectedBytes()

      Get the total number of bytes appended to this buffer.
      Specified by:
        `getNumberOfCollectedBytes` in interface `ByteCollector`
      Returns:
        total number of appended bytes