Ring

A first-in, first-out queue of a fixed size. OnFull says what a push into a full ring does: “Reject” returns false, “Overwrite” drops the oldest entry, and “Error” throws.

By default, entries are numbers in a buffer, Stride numbers to an entry, so at a Stride of 2 Push(X, Y) takes two and Pop() gives two back. A Backend of “Table” holds any value, one to an entry.

local Recent = Collections.Ring.new({ Capacity = 3, OnFull = "Overwrite" })
for Index = 1, 5 do
  Recent:Push(Index)
end
print(Recent:Pop(), Recent:Length()) -- 3 2

Summary

Member	Description
.new()	Creates an empty ring.
:Push()	Adds an entry at the tail, and returns false when a “Reject” ring is full.
:Pop()	Removes and returns the oldest entry, or nil when the ring is empty.
:Peek()	Returns the oldest entry without removing it, or nil when the ring is empty.
:Length()	How many entries the ring holds.
:IsFull()	Whether the ring holds Capacity entries.
:IsEmpty()	Whether the ring holds no entries.
:Drain()	Passes every entry to Fn, oldest first, empties the ring, and returns how many there were.
:Clear()	Removes every entry.
Config	Settings for Ring.new.
Ring	The type Ring.new returns.

Functions

new

function Ring.new(Config: Config): Ring

Creates an empty ring. Errors if Capacity or Stride is not a whole number of 1 or more, if OnFull or Backend is not one of its names, or if a “Table” ring has a Stride other than 1.

Methods

Push

function Ring:Push(...: any): boolean

Adds an entry at the tail, and returns false when a “Reject” ring is full. A buffer ring that would store the entry raises and changes nothing when a number is missing.

Pop

function Ring:Pop(): ...any

Removes and returns the oldest entry, or nil when the ring is empty.

Peek

function Ring:Peek(): ...any

Returns the oldest entry without removing it, or nil when the ring is empty.

Length

function Ring:Length(): number

How many entries the ring holds.

IsFull

function Ring:IsFull(): boolean

Whether the ring holds Capacity entries.

IsEmpty

function Ring:IsEmpty(): boolean

Whether the ring holds no entries.

Drain

function Ring:Drain(Fn: (...any) -> ()): number

Passes every entry to Fn, oldest first, empties the ring, and returns how many there were. Fn must not push, pop or clear the ring. If Fn raises, a buffer ring keeps every entry, and a “Table” ring still counts them all but gives nil for the ones already passed.

Clear

function Ring:Clear()

Removes every entry.

Types

Config

export type Config = {
	Capacity: number,
	Stride: number?,
	OnFull: string,
	Backend: string?,
}

Settings for Ring.new.

Field	Type	Description
Capacity	number	how many entries it holds, 1 or more
OnFull	"Reject" | "Overwrite" | "Error"	what a push into a full ring does
Stride	number?	numbers per entry in a buffer ring, 1 by default
Backend	"Buffer" | "Table" | nil	“Buffer” by default

Ring

export type Ring = {
	Push: (self: any, ...any) -> boolean,
	Pop: (self: any) -> ...any,
	Peek: (self: any) -> ...any,
	Length: (self: any) -> number,
	IsFull: (self: any) -> boolean,
	IsEmpty: (self: any) -> boolean,
	Drain: (self: any, Fn: (...any) -> ()) -> number,
	Clear: (self: any) -> (),
}

The type Ring.new returns.