de.caff.util

## Class TextLineRingBuffer

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

- All Implemented Interfaces:
    ByteCollector

      public class TextLineRingBuffer
      extends java.lang.Object
      implements ByteCollector

  A text line ring buffer working as a byte collector.

  This is especially useful for collecting text output.

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

  Since:
    August 10, 2022
  Author:
    Rammi

- - ### Field Summary

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

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TextLineRingBuffer(int limit, java.nio.charset.Charset charset)` Create a ring buffer with the given size.
    `TextLineRingBuffer(int limit, java.nio.charset.Charset charset, 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.
    `boolean` | `isEmpty()` Is the text line ring buffer empty.
    `int` | `size()` Get the number of valid lines cached in this buffer.
    `java.lang.String[]` | `toLineArray()` Get the lines of this ring buffer as an array of strings.
    `Indexable<java.lang.String>` | `toLineIndexable()` Get the lines of this ring buffer as an indexable of strings.
    `java.util.List<java.lang.String>` | `toLineList()` Get the lines of this ring buffer as a list of strings.
    `java.lang.String` | `toString()` Get the lines of this line buffer as a concatenated string.
    `Indexable<java.lang.String>` | `viewLines()` Get a temporary view of the lines in this ring buffer.

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

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

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

      `append`

- - ### Field Detail

    - #### INITIAL_LIMIT

          static final int INITIAL_LIMIT

      Initial limit: 64 Mi-lines.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TextLineRingBuffer

          public TextLineRingBuffer(int limit,
                                    @NotNull
                                    java.nio.charset.Charset charset)

      Create a ring buffer with the given size.
      Parameters:
        `limit` - size limit of this text line buffer
        `charset` - charset used to convert bytes into strings

    - #### TextLineRingBuffer

          TextLineRingBuffer(int limit,
                             @NotNull
                             java.nio.charset.Charset charset,
                             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
        `charset` - charset for decoding text from bytes
        `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 lines cached in this buffer. Due to implementation the returned number might be 1 more than the `cache limit`.
      Returns:
        number of text lines cached, possibly 1 more than the limit if the last line added is not ending with an eol mark

    - #### isEmpty

          public boolean isEmpty()

      Is the text line ring buffer empty.
      Returns:
        if there are no cached lines

    - #### 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`

    - #### 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`

    - #### viewLines

          @NotNull
          public Indexable<java.lang.String> viewLines()

      Get a temporary view of the lines in this ring buffer. Use only on finished buffer: the returned view will become invalid if any data is appended to this ring buffer. The advantage compared to `toLineIndexable()`, `toLineList()`, and `toString()` is that no data is copied.
      Returns:
        lines view

    - #### toLineIndexable

          @NotNull
          public Indexable<java.lang.String> toLineIndexable()

      Get the lines of this ring buffer as an indexable of strings. This is safe, the returned indexable is independent of this buffer with the price of copying the data.
      Returns:
        indexable of size size() with the lines of this ring buffer

    - #### toLineList

          @NotNull
          public java.util.List<java.lang.String> toLineList()

      Get the lines of this ring buffer as a list of strings. This is safe, the returned list is independent of this buffer with the price of copying the data.
      Returns:
        list with the lines of this ring buffer

    - #### toLineArray

          @NotNull
          public java.lang.String[] toLineArray()

      Get the lines of this ring buffer as an array of strings. This is safe, the returned array is independent of this buffer with the price of copying the data.
      Returns:
        array with the lines of this ring buffer

    - #### toString

          @NotNull
          public java.lang.String toString()

      Get the lines of this line buffer as a concatenated string.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        string representation of the lines, connected with the local end-of-line sequence

    - #### 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