Skip to content

StringBuffer

Inherits: RefCounted
Namespace: TauPlot

Ring buffer that stores String values with a fixed capacity.

Description

StringBuffer stores a sequence of String values in a ring buffer of fixed capacity. When the buffer is full, appending a new value drops the oldest one.

All read and write operations use logical indices. Index 0 refers to the oldest value currently in the buffer. Index size()- 1 refers to the most recently appended one. Logical indices shift when the buffer wraps: after a new value is appended into a full buffer, every index decreases by one.

The buffer is pre-allocated at construction and does not resize unless set_capacity() is called explicitly.

Example

# Ring buffer with a capacity of 64 strings.
var labels := TauPlot.StringBuffer.new(64)

# Append one string.
labels.append_value("January")

Notes

  1. Default value fills unused slots. At construction and after clear(), every slot is filled with p_default_value. Default: "" (empty string).

  2. Out-of-range access logs an error. get_value(), set_value(), and set_values() log an error and return early when the buffer is empty or the index is out of range.

  3. append_value() and append_values() always succeed. They never reject input. When the buffer is full, the oldest value is silently overwritten. The return value indicates how many existing values were overwritten.

Constructor

new()

StringBuffer.new(p_capacity: int) -> StringBuffer

Creates an empty buffer with the given capacity. The buffer is ready to use immediately after construction.

Parameters

  • p_capacity: int Maximum number of String values the buffer can hold. Values below 1 are clamped to 1.
  • p_default_value: String Value used to fill unused slots at construction and after clear(). Default: "".

Methods

Introspection

get_capacity()

get_capacity() -> int

Returns the maximum number of values the buffer can hold.

size()

size() -> int

Returns the number of values currently stored. Always between 0 and get_capacity().

Reading and writing individual values

get_value()

get_value(p_logical_index: int) -> String

Returns the String at the given logical index. Index 0 is the oldest value in the buffer, size()- 1 is the most recent. Logs an error and returns "" if the buffer is empty or the index is out of range.

Parameters

  • p_logical_index: int Logical index in the range [0,size()- 1].

set_value()

set_value(p_logical_index: int, p_value: String) -> void

Overwrites the String at the given logical index. Index 0 is the oldest value, size()- 1 is the most recent. Logs an error and does nothing if the buffer is empty or the index is out of range.

Parameters

  • p_logical_index: int Logical index in the range [0,size()- 1].
  • p_value: String Replacement value.

set_values()

set_values(p_start_index: int, p_values: PackedStringArray) -> int

Overwrites a contiguous range of values starting at p_start_index. Writes as many values as fit from p_start_index to the end of the currently stored range. Returns the number of values actually written. Returns 0 without writing if p_values is empty, the buffer is empty, or p_start_index is out of range. Logs an error in the latter two cases.

Parameters

  • p_start_index: int Logical index of the first slot to overwrite. Must be in the range [0,size()- 1].
  • p_values: PackedStringArray Replacement values. Values beyond size()- p_start_index are ignored.

Appending values

append_value()

append_value(p_value: String) -> int

Appends one String to the buffer. If the buffer is full, the oldest value is overwritten. Returns 1 if an existing value was overwritten, 0 otherwise.

Parameters

  • p_value: String Value to append.

append_values()

append_values(p_values: PackedStringArray) -> int

Appends multiple String values to the buffer. If the buffer does not have enough free slots, the oldest values are overwritten. Returns the number of existing values overwritten. Returns 0 immediately if p_values is empty.

Parameters

  • p_values: PackedStringArray Values to append, in order from oldest to newest.

Capacity

set_capacity()

set_capacity(p_capacity: int) -> void

Resizes the buffer to the new capacity. Values below 1 are clamped to 1. If the new capacity is smaller than the current sample count, the oldest values are dropped. If the new capacity is greater, existing values are preserved, new slots are pre-filled with the default value set at construction, and size() is unchanged. Does nothing if the new capacity equals the current one.

Parameters

  • p_capacity: int New maximum number of values the buffer can hold.

Clearing data

clear()

clear() -> void

Removes all stored values. The buffer capacity is unchanged. All slots are refilled with the p_default_value set at construction.

  • ColorBuffer Sibling ring buffer storing Color values.
  • Float32Buffer Sibling ring buffer storing float values (32-bit).
  • Float64Buffer Sibling ring buffer storing float values (64-bit).
  • Int32Buffer Sibling ring buffer storing int values (32-bit).