std.containers.stack

std.containers.stack

std.containers.stack provides a generic, fixed-capacity LIFO stack for :core code. It stores values inline, performs no allocation, requires no capability, and exposes overflow or empty-state results explicitly.

Import

use std.containers.stack

Contract

The shipped v1 profile is deliberately bounded:

• capacity is stack.MAX_CAP, currently 64
• storage is inline in Stack[T]
• push and try_push return false when full
• pop and peek return null when empty
• reset clears the logical length without zeroing retained storage

There is no silent overflow. A failed push does not mutate the stack.

API

pub const MAX_CAP: usize = 64

pub struct Stack[T] {
    data: [MAX_CAP]T,
    len: usize
}

pub func init[T]() -> Stack[T]
pub func reset[T](edit self: *Stack[T]) -> void
pub func push[T](edit self: *Stack[T], value: T) -> bool
pub func try_push[T](edit self: *Stack[T], value: T) -> bool
pub func pop[T](edit self: *Stack[T]) -> ?T
pub func peek[T](view self: *Stack[T]) -> ?T
pub func len[T](view self: *Stack[T]) -> usize
pub func size[T](view self: *Stack[T]) -> usize
pub func is_empty[T](view self: *Stack[T]) -> bool
pub func is_full[T](view self: *Stack[T]) -> bool
pub func remaining[T](view self: *Stack[T]) -> usize
pub func capacity() -> usize

size is an alias for len.

Example

use std.containers.stack

func main() -> i32 do
    var s = stack.init[u64]()

    if stack.push[u64](&s, 10) != true do return 1 end
    if stack.push[u64](&s, 20) != true do return 2 end

    let top = stack.pop[u64](&s)
    if top == null do return 3 end
    if top.? != 20 do return 4 end

    if stack.pop[u64](&s).? != 10 do return 5 end
    if stack.pop[u64](&s) != null do return 6 end

    return 0
end

Verification

cd janus
./scripts/zb test-containers-stack

The smoke imports the real module and proves LIFO order, overflow status, empty-state null, reset, and multiple payload instantiations.