ring_buffer

Provides a fixed-capacity FIFO collection that retains the newest values without growing after construction. See the module README for consumer setup and package imports.

#Usage

Retain the three most recent measurements while consuming them in insertion order.

///|
test {
  let measurements : RingBuffer[Int] = RingBuffer::RingBuffer(3)
  for value in [10, 20, 30, 40] {
    measurements.push(value)
  }
  debug_inspect(measurements.peek(), content="Some(20)")
  debug_inspect(measurements.to_array(), content="[20, 30, 40]")
}

#Package behavior

Fixed positive capacity established at construction
FIFO push, pop, and peek operations without directional terminology
Oldest-value overwrite when a full buffer receives a new value
Logical-order iterators, indexing, array copies, and zero-copy split views
No arbitrary position-based insertion or removal, reordering, capacity changes, or multi-buffer operations that would weaken FIFO ring-buffer semantics
Order-preserving predicate-based retain and retain_map transformations
No nested collection or FromJson operations whose resulting fixed capacity would be ambiguous

#API

Mooncakes API reference

This README was generated from the share-artifact skill and README template.

RingBufferError

source

pub(all) suberror RingBufferError {
  InvalidCapacity(Int)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

A failure raised while constructing a fixed-capacity ring buffer.

RingBuffer

source

pub struct RingBuffer[A] {
  // private fields
}

A fixed-capacity FIFO collection that overwrites its oldest value when full.

The representation is private so callers cannot bypass the fixed-capacity and insertion-order invariants through directional deque operations. Arbitrary position-based insertion or removal, reordering, capacity changes, and multi-buffer operations are intentionally excluded from the public API. Predicate-based retain operations remain available because they preserve the relative insertion order of every retained value. Nested collection operations and FromJson are also excluded because a fixed capacity cannot be inferred for their resulting buffers.

impl Compare for RingBuffer[A]

impl Eq for RingBuffer[A]

impl Hash for RingBuffer[A]

impl ToJson for RingBuffer[A]

impl Debug for RingBuffer[A]

RingBuffer::RingBuffer

source

fn[A] RingBuffer::RingBuffer(capacity : Int) -> RingBuffer[A] raise RingBufferError

Constructs an empty ring buffer with a positive fixed capacity.

RingBuffer::as_views

source

fn[A] RingBuffer::as_views(self : RingBuffer[A]) -> (ArrayView[A], ArrayView[A])

Returns two borrowed views that together contain values from oldest to newest.

The first view starts at the physical head. The second view contains any wrapped values from the physical start. Mutating the buffer may invalidate either view.

RingBuffer::at

source

fn[A] RingBuffer::at(self : RingBuffer[A], index : Int) -> A

Returns the value at a logical insertion-order index.

Panics when index is negative or not less than length().

RingBuffer::binary_search

source

fn[A : Compare + Eq] RingBuffer::binary_search(self : RingBuffer[A], value : A) -> Result[Int, Int]

Searches logically ordered values and returns a matching index or insertion index.

The values must already be sorted according to Compare.

RingBuffer::binary_search_by

source

fn[A] RingBuffer::binary_search_by(self : RingBuffer[A], compare : (A) -> Int) -> Result[Int, Int]

Searches logically ordered values with a caller-provided comparison.

The callback must describe a sequence sorted around the requested value.

RingBuffer::capacity

source

fn[A] RingBuffer::capacity(self : RingBuffer[A]) -> Int

Returns the fixed maximum number of values held by the buffer.

RingBuffer::clear

source

fn[A] RingBuffer::clear(self : RingBuffer[A]) -> Unit

Removes every value without changing the fixed capacity.

RingBuffer::contains

source

fn[A : Eq] RingBuffer::contains(self : RingBuffer[A], value : A) -> Bool

Returns whether any current value equals value.

RingBuffer::copy

source

fn[A] RingBuffer::copy(self : RingBuffer[A]) -> RingBuffer[A]

Creates a shallow copy with the same fixed capacity and logical order.

RingBuffer::each

source

fn[A] RingBuffer::each(self : RingBuffer[A], action : (A) -> Unit) -> Unit

Calls action for each value from oldest to newest.

RingBuffer::eachi

source

fn[A] RingBuffer::eachi(self : RingBuffer[A], action : (Int, A) -> Unit) -> Unit

Calls action for each logical index and value from oldest to newest.

RingBuffer::filter

source

fn[A] RingBuffer::filter(self : RingBuffer[A], predicate : (A) -> Bool raise?) -> RingBuffer[A] raise?

Copies matching values in logical order into a buffer with the same capacity.

RingBuffer::from_array

source

fn[A] RingBuffer::from_array(values : ArrayView[A], capacity~ : Int) -> RingBuffer[A] raise RingBufferError

Constructs a ring buffer by pushing values in order.

When values contains more elements than capacity, only the newest capacity elements are retained.

RingBuffer::from_iter

source

fn[A] RingBuffer::from_iter(values : Iter[A], capacity~ : Int) -> RingBuffer[A] raise RingBufferError

Constructs a ring buffer by consuming values in order.

When the iterator yields more elements than capacity, only the newest capacity elements are retained.

RingBuffer::get

source

fn[A] RingBuffer::get(self : RingBuffer[A], index : Int) -> A?

Returns the value at a logical insertion-order index, or None when out of bounds.

RingBuffer::indexed_get

source

#alias("_[_]")
fn[A] RingBuffer::indexed_get(self : RingBuffer[A], index : Int) -> A

Provides indexed access in logical insertion order.

RingBuffer::indexed_set

source

#alias("_[_]=_")
fn[A] RingBuffer::indexed_set(self : RingBuffer[A], index : Int, value : A) -> Unit

Provides indexed replacement in logical insertion order.

RingBuffer::is_empty

source

fn[A] RingBuffer::is_empty(self : RingBuffer[A]) -> Bool

Returns whether the buffer contains no values.

RingBuffer::is_full

source

fn[A] RingBuffer::is_full(self : RingBuffer[A]) -> Bool

Returns whether the current length has reached the fixed capacity.

RingBuffer::iter

source

fn[A] RingBuffer::iter(self : RingBuffer[A]) -> Iter[A]

Returns an iterator from the oldest value to the newest value.

RingBuffer::iter2

source

fn[A] RingBuffer::iter2(self : RingBuffer[A]) -> Iter2[Int, A]

Returns an iterator of logical indices and values from oldest to newest.

RingBuffer::join

source

fn RingBuffer::join(self : RingBuffer[String], separator : StringView) -> String

Joins the current strings from oldest to newest with separator.

RingBuffer::length

source

fn[A] RingBuffer::length(self : RingBuffer[A]) -> Int

Returns the current number of values.

RingBuffer::map

source

fn[A, B] RingBuffer::map(self : RingBuffer[A], transform : (A) -> B) -> RingBuffer[B]

Maps every value in logical order into a buffer with the same fixed capacity.

RingBuffer::mapi

source

fn[A, B] RingBuffer::mapi(self : RingBuffer[A], transform : (Int, A) -> B) -> RingBuffer[B]

Maps every logical index and value into a buffer with the same fixed capacity.

RingBuffer::peek

source

fn[A] RingBuffer::peek(self : RingBuffer[A]) -> A?

Returns the oldest value without removing it, or returns None when empty.

RingBuffer::peek_latest

source

fn[A] RingBuffer::peek_latest(self : RingBuffer[A]) -> A?

Returns the newest value without removing it, or returns None when empty.

RingBuffer::pop

source

fn[A] RingBuffer::pop(self : RingBuffer[A]) -> A?

Removes and returns the oldest value, or returns None when empty.

RingBuffer::push

source

fn[A] RingBuffer::push(self : RingBuffer[A], value : A) -> Unit

Adds the newest value, overwriting the oldest value when the buffer is full.

RingBuffer::retain

source

fn[A] RingBuffer::retain(self : RingBuffer[A], predicate : (A) -> Bool) -> Unit

Keeps only matching values while preserving their logical order and capacity.

RingBuffer::retain_map

source

fn[A] RingBuffer::retain_map(self : RingBuffer[A], transform : (A) -> A?) -> Unit

Replaces or removes values while preserving logical order and capacity.

RingBuffer::rev_each

source

fn[A] RingBuffer::rev_each(self : RingBuffer[A], action : (A) -> Unit) -> Unit

Calls action for each value from newest to oldest.

RingBuffer::rev_eachi

source

fn[A] RingBuffer::rev_eachi(self : RingBuffer[A], action : (Int, A) -> Unit) -> Unit

Calls action for each logical index and value from newest to oldest.

RingBuffer::rev_iter

source

fn[A] RingBuffer::rev_iter(self : RingBuffer[A]) -> Iter[A]

Returns an iterator from the newest value to the oldest value.

RingBuffer::rev_iter2

source

fn[A] RingBuffer::rev_iter2(self : RingBuffer[A]) -> Iter2[Int, A]

Returns an iterator of logical indices and values from newest to oldest.

RingBuffer::search

source

fn[A : Eq] RingBuffer::search(self : RingBuffer[A], value : A) -> Int?

Returns the logical index of the first matching value, or None when absent.

RingBuffer::set

source

fn[A] RingBuffer::set(self : RingBuffer[A], index : Int, value : A) -> Unit

Replaces the value at a logical insertion-order index without changing order.

Panics when index is negative or not less than length().

RingBuffer::to_array

source

fn[A] RingBuffer::to_array(self : RingBuffer[A]) -> Array[A]

Copies the current values into an array ordered from oldest to newest.

Source Files

ring_buffer.mbt

Site source Report issue Packages Build queue Skills Statistics

#totto2727/x/ring_buffer

#Usage

#Package behavior

#API

#RingBufferError

#RingBuffer

#RingBuffer::RingBuffer

#RingBuffer::as_views

#RingBuffer::at

#RingBuffer::binary_search

#RingBuffer::binary_search_by

#RingBuffer::capacity

#RingBuffer::clear

#RingBuffer::contains

#RingBuffer::copy

#RingBuffer::each

#RingBuffer::eachi

#RingBuffer::filter

#RingBuffer::from_array

#RingBuffer::from_iter

#RingBuffer::get

#RingBuffer::indexed_get

#RingBuffer::indexed_set

#RingBuffer::is_empty

#RingBuffer::is_full

#RingBuffer::iter

#RingBuffer::iter2

#RingBuffer::join

#RingBuffer::length

#RingBuffer::map

#RingBuffer::mapi

#RingBuffer::peek

#RingBuffer::peek_latest

#RingBuffer::pop

#RingBuffer::push

#RingBuffer::retain

#RingBuffer::retain_map

#RingBuffer::rev_each

#RingBuffer::rev_eachi

#RingBuffer::rev_iter

#RingBuffer::rev_iter2

#RingBuffer::search

#RingBuffer::set

#RingBuffer::to_array

Source Files

RingBufferError

RingBuffer

RingBuffer::RingBuffer

RingBuffer::as_views

RingBuffer::at

RingBuffer::binary_search

RingBuffer::binary_search_by

RingBuffer::capacity

RingBuffer::clear

RingBuffer::contains

RingBuffer::copy

RingBuffer::each

RingBuffer::eachi

RingBuffer::filter

RingBuffer::from_array

RingBuffer::from_iter

RingBuffer::get

RingBuffer::indexed_get

RingBuffer::indexed_set

RingBuffer::is_empty

RingBuffer::is_full

RingBuffer::iter

RingBuffer::iter2

RingBuffer::join

RingBuffer::length

RingBuffer::map

RingBuffer::mapi

RingBuffer::peek

RingBuffer::peek_latest

RingBuffer::pop

RingBuffer::push

RingBuffer::retain

RingBuffer::retain_map

RingBuffer::rev_each

RingBuffer::rev_eachi

RingBuffer::rev_iter

RingBuffer::rev_iter2

RingBuffer::search

RingBuffer::set

RingBuffer::to_array