#ringbuffer API reference

A fixed-capacity ring buffer of strings: a bounded FIFO that overwrites the oldest entry when full. push appends (dropping the oldest once capacity is exceeded); pop removes the oldest; first / last peek without removing. Elements are ordered oldest-to-newest. Useful for a sliding window of recent events, log lines, or samples.

Value-semantic: push / pop return a fresh buffer (chain them, $rb = ringbuffer.push($rb, x)). Since a value-semantic pop cannot return both the item and the new buffer, read the oldest with first before you pop it. Over lists; runs on both binaries. Stores strings - serialize other values with convert.toString or json.

Import with import "ringbuffer.j" as ringbuffer;. See the ringbuffer guide for prose and examples.

#Functions

#ringbuffer.capacity(rb as RingBuffer)

The buffer's capacity.

Parameters

• rb {RingBuffer} - the buffer

Returns {int} - the capacity

#ringbuffer.first(rb as RingBuffer)

The oldest item, without removing it.

Parameters

• rb {RingBuffer} - the buffer

Returns {string} - the oldest item

Throws

• {Error} - kind "ringbuffer" if the buffer is empty

#ringbuffer.isEmpty(rb as RingBuffer)

Whether the buffer holds no entries.

Parameters

• rb {RingBuffer} - the buffer

Returns {bool} - true if empty

#ringbuffer.isFull(rb as RingBuffer)

Whether the buffer is at capacity.

Parameters

• rb {RingBuffer} - the buffer

Returns {bool} - true if full

#ringbuffer.last(rb as RingBuffer)

The newest item, without removing it.

Parameters

• rb {RingBuffer} - the buffer

Returns {string} - the newest item

Throws

• {Error} - kind "ringbuffer" if the buffer is empty

#ringbuffer.new(capacity as int)

Create an empty ring buffer of the given capacity.

Parameters

• capacity {int} - the maximum number of entries (must be >= 1)

Returns {RingBuffer} - the empty buffer

Throws

• {Error} - kind "ringbuffer" if capacity is < 1

#ringbuffer.pop(rb as RingBuffer)

Remove the oldest item. Returns a fresh buffer. Read the item with first before popping it.

Parameters

• rb {RingBuffer} - the buffer

Returns {RingBuffer} - the buffer without its oldest item

Throws

• {Error} - kind "ringbuffer" if the buffer is empty

#ringbuffer.push(rb as RingBuffer, item as string)

Append an item, dropping the oldest if the buffer is already full. Returns a fresh buffer.

Parameters

• rb {RingBuffer} - the buffer
• item {string} - the item to append

Returns {RingBuffer} - the updated buffer

#ringbuffer.size(rb as RingBuffer)

The number of entries currently held.

Parameters

• rb {RingBuffer} - the buffer

Returns {int} - the entry count

#ringbuffer.toList(rb as RingBuffer)

A copy of the entries, oldest to newest.

Parameters

• rb {RingBuffer} - the buffer

Returns {list of string} - the entries

#Structs

#ringbuffer.RingBuffer

A ring buffer.