Aurora.Uix.Stack (Aurora UIX v0.1.4-rc.3)

Copy Markdown

Provides a stack data structure implementation with standard stack operations: push, pop, peek, and empty checks. Includes both safe (error tuple) and bang (raising) variants of operations.

Key Features

  • Implements push, pop, peek, and empty checks for stack-based algorithms.
  • Supports both safe (error tuple) and bang (raising) variants of operations.

Key Constraints

  • Not intended for general-purpose use outside Aurora UIX internals.
  • Raises Aurora.Uix.Stack.EmptyStackError on invalid bang operations.

Summary

Types

t()

Functions

empty?(stack)

Checks if the stack is empty.

new()

Creates a new empty stack.

new(values)

Creates a new stack with initial value(s).

peek(stack)

Returns the top value of the stack in a safe way.

peek!(stack)

Returns the top value of the stack.

pop(stack)

Removes and returns the top value from the stack in a safe way.

pop(stack, default_value)

Removes and returns the top value from the stack, or returns a default value if empty.

pop!(stack)

Removes and returns the top value from the stack.

push(stack, value)

Pushes a new value onto the top of the stack.

push_replace(stack, value)

Replaces the top value of the stack with a new value.

Types

t()

@type t() :: %Aurora.Uix.Stack{values: [term()]}

Functions

empty?(stack)

@spec empty?(t()) :: boolean()

Checks if the stack is empty.

Parameters

  • stack (Aurora.Uix.Stack.t()) - The stack to check.

Returns

boolean() - true if stack is empty, false otherwise.

Examples

Aurora.Uix.Stack.empty?(Aurora.Uix.Stack.new())
# => true
Aurora.Uix.Stack.empty?(Aurora.Uix.Stack.new([1]))
# => false

new()

@spec new() :: t()

Creates a new empty stack.

Returns

Aurora.Uix.Stack.t() - An empty stack.

Examples

Aurora.Uix.Stack.new()
# => %Aurora.Uix.Stack{values: []}

new(values)

@spec new([term()]) :: t()
@spec new(term()) :: t()

Creates a new stack with initial value(s).

Parameters

  • values (list(term()) | term()) - A single value or list of values to initialize the stack.

Returns

Aurora.Uix.Stack.t() - A stack containing the value(s).

Examples

Aurora.Uix.Stack.new([1, 2, 3])
# => %Aurora.Uix.Stack{values: [1, 2, 3]}
Aurora.Uix.Stack.new(:foo)
# => %Aurora.Uix.Stack{values: [:foo]}

peek(stack)

@spec peek(t()) :: {:ok, term()} | {:error, t()}

Returns the top value of the stack in a safe way.

Parameters

  • stack (Aurora.Uix.Stack.t()) - The stack to peek.

Returns

{:ok, term()} | {:error, Aurora.Uix.Stack.t()} - Tuple with :ok and the top value if stack is not empty, or :error and the stack if empty.

Examples

stack = Aurora.Uix.Stack.new([:a, :b])
Aurora.Uix.Stack.peek(stack)
# => {:ok, :a}
Aurora.Uix.Stack.peek(Aurora.Uix.Stack.new())
# => {:error, %Aurora.Uix.Stack{values: []}}

peek!(stack)

@spec peek!(t()) :: term()

Returns the top value of the stack.

Parameters

  • stack (Aurora.Uix.Stack.t()) - The stack to peek.

Returns

term() - The top value of the stack.

Raises

Aurora.Uix.Stack.EmptyStackError - When the stack is empty.

Examples

stack = Aurora.Uix.Stack.new([:a, :b])
Aurora.Uix.Stack.peek!(stack)
# => :a

pop(stack)

@spec pop(t()) :: {:ok, t(), term()} | {:error, t()}

Removes and returns the top value from the stack in a safe way.

Parameters

  • stack (Aurora.Uix.Stack.t()) - The stack to pop from.

Returns

{:ok, Aurora.Uix.Stack.t(), term()} | {:error, Aurora.Uix.Stack.t()} - Tuple with :ok, the new stack, and the popped value if not empty, or :error and the stack if empty.

Examples

stack = Aurora.Uix.Stack.new([:a, :b])
Aurora.Uix.Stack.pop(stack)
# => {:ok, %Aurora.Uix.Stack{values: [:b]}, :a}
Aurora.Uix.Stack.pop(Aurora.Uix.Stack.new())
# => {:error, %Aurora.Uix.Stack{values: []}}

pop(stack, default_value)

@spec pop(t(), term()) :: {t(), term()}

Removes and returns the top value from the stack, or returns a default value if empty.

Parameters

  • stack (Aurora.Uix.Stack.t()) - The stack to pop from.
  • default_value (term()) - The value to return if the stack is empty.

Returns

{Aurora.Uix.Stack.t(), term()} - Tuple with the stack and either the popped value or the default value.

Examples

stack = Aurora.Uix.Stack.new([:a, :b])
Aurora.Uix.Stack.pop(stack, :default)
# => {%Aurora.Uix.Stack{values: [:b]}, :a}

Aurora.Uix.Stack.pop(Aurora.Uix.Stack.new(), :default)
# => {%Aurora.Uix.Stack{values: []}, :default}

pop!(stack)

@spec pop!(t()) :: {t(), term()}

Removes and returns the top value from the stack.

Parameters

  • stack (Aurora.Uix.Stack.t()) - The stack to pop from.

Returns

{Aurora.Uix.Stack.t(), term()} - Tuple with the new stack and the popped value.

Raises

Aurora.Uix.Stack.EmptyStackError - When the stack is empty.

Examples

stack = Aurora.Uix.Stack.new([:a, :b])
Aurora.Uix.Stack.pop!(stack)
# => {%Aurora.Uix.Stack{values: [:b]}, :a}

push(stack, value)

@spec push(t(), term()) :: t()

Pushes a new value onto the top of the stack.

Parameters

  • stack (Aurora.Uix.Stack.t()) - The stack to push onto.
  • value (term()) - The value to push.

Returns

Aurora.Uix.Stack.t() - A stack with the value pushed on top.

Examples

stack = Aurora.Uix.Stack.new([1, 2])
Aurora.Uix.Stack.push(stack, 3)
# => %Aurora.Uix.Stack{values: [3, 1, 2]}

push_replace(stack, value)

@spec push_replace(t(), term()) :: t()

Replaces the top value of the stack with a new value.

Parameters

  • stack (Aurora.Uix.Stack.t()) - The stack to modify.
  • value (term()) - The new value to replace the top value with.

Returns

Aurora.Uix.Stack.t() - A stack with the top value replaced.

Raises

Aurora.Uix.Stack.EmptyStackError - When the stack is empty.

Examples

stack = Aurora.Uix.Stack.new([1, 2])
Aurora.Uix.Stack.push_replace(stack, :foo)
# => %Aurora.Uix.Stack{values: [:foo, 2]}