de.caff.util

## Class RingBuffer<T>

- java.lang.Object
- - de.caff.util.RingBuffer<T>

-     public class RingBuffer<T>
      extends java.lang.Object

  A byte buffer to which you can add data 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
    `RingBuffer(int limit)` Create a ring buffer with the given size.
    `RingBuffer(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(T... items)` Append the given items to the buffer.
    `void` | `append(T item)` Append one item.
    `void` | `append(T[] items, int offset, int length)` Append the given byte array part to this buffer.
    `void` | `clear()` Clear all data.
    `int` | `getLimit()` Get the limit of this ring buffer.
    `long` | `getNumberOfCollectedItems()` Get the total number of items appended to this buffer.
    `boolean` | `isEmpty()` Is this ring buffer empty?
    `int` | `size()` Get the number of valid bytes cached in this buffer.
    `Indexable<T>` | `toIndexable()` Get a stable byte indexable from this buffer.
    `java.util.List<T>` | `toList()` Create a list with the items in this buffer.
    `Indexable<T>` | `view()` Get an indexable view of this ring buffer.

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

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

- - ### Field Detail

    - #### INITIAL_LIMIT

          static final int INITIAL_LIMIT

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

  - ### Constructor Detail

    - #### RingBuffer

          public RingBuffer(int limit)

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

    - #### RingBuffer

          RingBuffer(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

    - #### isEmpty

          public boolean isEmpty()

      Is this ring buffer empty?
      Returns:
        `true` if the buffer is empty
        `false` if not

    - #### append

          public void append(T item)

      Append one item.
      Parameters:
        `item` - item to append

    - #### append

          @SafeVarargs
          public final void append(@NotNull
                                                T... items)

      Append the given items to the buffer.
      Parameters:
        `items` - items to append

    - #### append

          public void append(@NotNull
                             T[] items,
                             int offset,
                             int length)

      Append the given byte array part to this buffer.
      Parameters:
        `items` - items to append
        `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`

    - #### toList

          @NotNull
          public java.util.List<T> toList()

      Create a list with the items in this buffer.
      Returns:
        list of size size() containing the buffered items

    - #### view

          @NotNull
          public Indexable<T> view()

      Get an indexable view of this ring buffer.

      This is more efficient than copying all bytes in toList(), especially if only a few items 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:
        indexable view of this buffer
      See Also:
        `toIndexable()`, `toList()`

    - #### toIndexable

          @NotNull
          public Indexable<T> toIndexable()

      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:
        `toList()`, `view()`

    - #### clear

          public void clear()

      Clear all data. This will clear everything but `the total number of bytes handled by this buffer`.

    - #### getNumberOfCollectedItems

          public long getNumberOfCollectedItems()

      Get the total number of items appended to this buffer.
      Returns:
        total number of appended items