# LispKit Stack

Library `(lispkit stack)` provides an implementation for mutable stacks, i.e. mutable LIFO buffers.

stack-type-tag [constant]

Symbol representing the `stack` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all stack objects.

(make-stack) [procedure]

Returns a new empty stack.

(stack x …) [procedure]

Returns a new stack with x on its top position followed by the remaining parameters.

    (stack-top (stack 1 2 3))  ⟹  1

(stack? obj) [procedure]

Returns `#t` if obj is a stack; otherwise `#f` is returned.

(stack-empty? s) [procedure]

Returns `#t` if stack s is empty.

(stack-size s) [procedure]

Returns the size of stack s, i.e. the number of elements buffered in s.

(stack=? s1 s2) [procedure]

Returns `#t` if stack s1 has the exact same elements in the same order like stack s2; otherwise, `#f` is returned.

(stack-push! s x) [procedure]

Pushes element x onto stack s.

(stack-top s) [procedure]

Returns the top element of stack s. If the stack is empty, an error is raised.

(stack-pop! s) [procedure]

Removes the top element from stack s and returns its value.

    (define s (make-stack))
    (stack-push! s 1)
    (stack-push! s 2)
    (stack-pop! s)  ⟹  2
    (stack-size s)  ⟹  1

(stack-clear! s) [procedure]

Removes all elements from stack s.

(stack-copy s) [procedure]

Returns a copy of stack s.

(stack->list s) [procedure]

Returns a list consisting of all elements on stack s in the order they appear, i.e. starting with the top element.

    (stack->list (stack 1 2 3))

(list->stack l) [procedure]

Returns a new stack consisting of the elements of list l. The first element in l will become the top element of the stack that is returned.

(list->stack! s l) [procedure]

Pushes the elements of list l onto stack s in reverse order.

    (define s (list->stack '(3 2 1)))
    (list->stack! s '(6 5 4))
    (stack->list s)  ⟹  (6 5 4 3 2 1)