March Docs

RingBuf

RingBuf: mutable fixed-capacity circular buffer.

All operations are O(1) and allocation-free after make().

Complexity: make O(n) — allocates backing array of [cap] slots push O(1) — writes newest; overwrites oldest when full pop O(1) — removes and returns oldest (FIFO) get / peek_* O(1) — indexed and endpoint access size / cap O(1) clear O(1) — resets cursors; does not zero the array to_list O(n)

Index convention: 0 = oldest element (natural FIFO drain order). When the buffer is full, push overwrites the oldest element silently.

Ownership contract: RingBuf is a single-owner primitive. The typechecker rejects RingBuf values in send() payloads. Pass the buffer as initial actor state at spawn time; do not share it across actor boundaries.

Shared-reference semantics: within one actor, all aliases to a RingBuf see the same mutations. push/pop/clear mutate in place and return Unit.

Functions

fncapcap(rb : RingBuf(a)) : Int#

Fixed capacity of the buffer. O(1). Set once at make() and never changes.

Examples

    march> RingBuf.cap(RingBuf.make(8))
    8
fnclearclear(rb : RingBuf(a)) : Unit#

Reset to empty in O(1). Does not zero the backing array — elements previously written remain in memory until overwritten by future pushes. Cap is unchanged.

Examples

    march> RingBuf.to_list(RingBuf.make(4))
    []
fngetget(rb : RingBuf(a), i : Int) : Option(a)#

Return the element at logical index [i] (0 = oldest), or None if out of range. O(1).

Valid indices are 0 .. size(rb)-1. Negative indices or indices >= size
return None.

## Examples

    march> RingBuf.get(RingBuf.make(4), 0)
    None
    march> RingBuf.get(RingBuf.make(4), -1)
    None
fnis_emptyis_empty(rb : RingBuf(a)) : Bool#

True when the buffer contains no elements.

Examples

    march> RingBuf.is_empty(RingBuf.make(4))
    true
fnis_fullis_full(rb : RingBuf(a)) : Bool#

True when size equals cap. The next push will overwrite the oldest element.

Examples

    march> RingBuf.is_full(RingBuf.make(4))
    false
fnmakemake(cap : Int) : RingBuf(a)#

Create a new ring buffer with fixed [cap] capacity. Panics if [cap] <= 0.

Examples

    march> RingBuf.make(4)
    RingBuf(size=0, cap=4)
    march> RingBuf.cap(RingBuf.make(16))
    16
fnpeek_newestpeek_newest(rb : RingBuf(a)) : Option(a)#

Return the newest element without removing it, or None if empty. O(1).

Equivalent to get(rb, size(rb) - 1).

## Examples

    march> RingBuf.peek_newest(RingBuf.make(4))
    None
fnpeek_oldestpeek_oldest(rb : RingBuf(a)) : Option(a)#

Return the oldest element without removing it, or None if empty. O(1).

Equivalent to get(rb, 0).

## Examples

    march> RingBuf.peek_oldest(RingBuf.make(4))
    None
fnpoppop(rb : RingBuf(a)) : Option(a)#

Remove and return the oldest element (FIFO head), or None if empty. O(1).

Clears the vacated slot so the GC can collect the element's storage.

## Examples

    march> RingBuf.pop(RingBuf.make(4))
    None
fnpushpush(rb : RingBuf(a), x : a) : Unit#

Push [x] as the newest element. O(1), in-place, returns Unit.

When the buffer is already full (size == cap), the oldest element is
silently overwritten and size remains at cap.

## Examples

    march> RingBuf.is_empty(RingBuf.make(4))
    true
fnsizesize(rb : RingBuf(a)) : Int#

Current number of elements. O(1).

Starts at 0 and grows with each push up to cap. Once full, subsequent
pushes overwrite the oldest element and size stays at cap.

## Examples

    march> RingBuf.size(RingBuf.make(8))
    0
fnto_listto_list(rb : RingBuf(a)) : List(a)#

Snapshot of all elements from oldest to newest as a List. O(n).

Does not modify the buffer. The returned list is a copy — mutations to
the buffer after this call do not affect the list.

## Examples

    march> RingBuf.to_list(RingBuf.make(4))
    []