#totto2727/x/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 : @ring_buffer.RingBuffer[Int32] = @ring_buffer.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

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

    RingBufferError

    pub(all) suberror RingBufferError {
    InvalidCapacity(Int)
    } derive(Eq,
    Debug
    )

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

    RingBufferError::equal

    RingBufferError::not_equal

    fn RingBufferError::not_equal(x : RingBufferError, y : RingBufferError) -> Bool

    RingBuffer

    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 Debug for RingBuffer[A]
    impl ToJson for RingBuffer[A]

    RingBuffer::RingBuffer

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

    Constructs an empty ring buffer with a positive fixed capacity.

    RingBuffer::as_views

    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

    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().
    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

    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

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

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

    RingBuffer::clear

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

    Removes every value without changing the fixed capacity.

    RingBuffer::compare

    fn[A : Compare + Eq] RingBuffer::compare(self : RingBuffer[A], other : RingBuffer[A]) -> Int

    RingBuffer::contains

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

    Returns whether any current value equals value.

    RingBuffer::copy

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

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

    RingBuffer::each

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

    Calls action for each value from oldest to newest.

    RingBuffer::eachi

    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::equal

    fn[A : Eq] RingBuffer::equal(self : RingBuffer[A], other : RingBuffer[A]) -> Bool

    RingBuffer::filter

    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

    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

    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

    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::hash

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

    RingBuffer::hash_combine

    fn[A : Hash] RingBuffer::hash_combine(self : RingBuffer[A], hasher : Hasher) -> Unit

    RingBuffer::indexed_get

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

    Provides indexed access in logical insertion order.

    RingBuffer::indexed_set

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

    Provides indexed replacement in logical insertion order.

    RingBuffer::is_empty

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

    Returns whether the buffer contains no values.

    RingBuffer::is_full

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

    Returns whether the current length has reached the fixed capacity.

    RingBuffer::iter

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

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

    RingBuffer::iter2

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

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

    RingBuffer::join

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

    Joins the current strings from oldest to newest with separator.

    RingBuffer::length

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

    Returns the current number of values.

    RingBuffer::map

    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

    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::not_equal

    fn[A : Eq] RingBuffer::not_equal(x : RingBuffer[A], y : RingBuffer[A]) -> Bool

    RingBuffer::op_ge

    fn[A : Compare + Eq] RingBuffer::op_ge(x : RingBuffer[A], y : RingBuffer[A]) -> Bool

    RingBuffer::op_gt

    fn[A : Compare + Eq] RingBuffer::op_gt(x : RingBuffer[A], y : RingBuffer[A]) -> Bool

    RingBuffer::op_le

    fn[A : Compare + Eq] RingBuffer::op_le(x : RingBuffer[A], y : RingBuffer[A]) -> Bool

    RingBuffer::op_lt

    fn[A : Compare + Eq] RingBuffer::op_lt(x : RingBuffer[A], y : RingBuffer[A]) -> Bool

    RingBuffer::peek

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

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

    RingBuffer::peek_latest

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

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

    RingBuffer::pop

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

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

    RingBuffer::push

    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

    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

    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

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

    Calls action for each value from newest to oldest.

    RingBuffer::rev_eachi

    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

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

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

    RingBuffer::rev_iter2

    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

    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

    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

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

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

    Source Files