.\" 
.\" 	Copyright 2002 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH stack 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
stack \- a dynamically resizing stack
.SH SYNOPSIS
.nf
.B #include <mba/stack.h>
.sp
.BI "int stack_init(struct stack *" s ", unsigned int " max_size ", struct allocator *" al ");
.br
.BI "int stack_deinit(struct stack *" s ", del_fn " data_del ", void *" context ")
.br
.BI "struct stack *stack_new(unsigned int " max_size ", struct allocator *" al ");
.br
.BI "int stack_del(struct stack *" s ", del_fn " data_del ", void *" context ");
.br
.BI "int stack_clear(struct stack *" s ", del_fn " data_del ", void *" context ")
.br
.BI "int stack_clean(struct stack *" s ")
.br
.sp
.BI "int stack_push(struct stack *" s ", void *" data ");
.br
.BI "void *stack_pop(struct stack *" s ");
.br
.BI "int stack_is_empty(const struct stack *" s ");
.br
.BI "unsigned int stack_size(const struct stack *" s ");
.br
.BI "void stack_iterate(void *" s ", iter_t *" iter ");
.br
.BI "void *stack_next(void *" s ", iter_t *" iter ");
.br
.BI "void *stack_peek(struct stack *" s ");
.br

.fi
.SH DESCRIPTION
The stack functions manipulate a simple LIFO stack of pointers to objects but the underlying array will grow and shrink as storage requirements change.
.PP
.TP
.B init
The
.B stack_init
function initializes the stack
.I s
and saving a pointer to the
.BR "allocator" (3m)
.I al
which will be used to allocate memory for susequent stack operations. The stack will accept no more than
.I max
data pointers. If
.I max
is 0,
.B INT_MAX
elements may be pushed onto the stack.
.TP
.B deinit
The
.B stack_deinit
function deinitializes the stack
.IR "s" .
If the
.I data_del
function is not
.BR "NULL" ,
it will be called with the
.I context
parameter and each element on the stack.
.TP
.B new
Create a new
.BR "stack" (3)
object that will accept no more than
.I max_size
data pointers. If
.I max_size
is 0, the stack will accept at most
.B INT_MAX
elements.
.TP
.B del
The
.B stack_del
function deletes the stack object
.IR "s" .
If the
.I data_del
function is not
.BR "NULL" ,
it will be called with each remaining element before deallocating the stack
.I s
itself.
.TP
.B clear
The
.B stack_clear
function will remove all elements on the stack. If the
.I data_del
function is not
.B NULL
it will be called with each remaining element.
.TP
.B clean
The
.B stack_clean
function reallocates the array backing the stack to be exactly the number of elements necessary. A
.BR "stack" (3m)
will automatically shrink at an appropriate point but this function might be called by an
.BR "allocator" (3m)
.B reclaim_fn
function.
.TP
.B push
The
.B stack_push
function pushes the element
.I data
onto the stack identified by
.IR "s" ;
.TP
.B pop
The
.B stack_pop
function removes the last element pushed onto the stack
.IR "s" .
.TP
.B is_empty
Returns non-zero if the stack
.I s
has no elements and 0 otherwise.
.TP
.B size
The
.B stack_size
function returns the number of elements currently on the stack.
.TP
.B iterate\fR, \fBnext
Enumerate each element on the stack. Call
.B stack_iterate
to initialize the
.I iter
object to point to the bottom of the stack (the first element pushed onto the stack) and call
.B stack_next
to retrieve each data pointer. When the top of the stack has been reached,
.B stack_next
will return
.BR "NULL" .
.TP
.B peek
The
.B stack_peek
function returns the element at the top of the stack
.I s
or
.B NULL
of the stack is empty. The data pointer is not removed.
.SH RETURNS
.TP
.B init
The
.B stack_init
function returns -1 if
.I s
is a null pointer. Otherwise 0 is returned.
.TP
.B deinit
The
.B stack_deinit
function returns 0 if the stack was successfully deinitialized or -1 if the
.I data_del
function returned anything other than 0 or if an error occured attempting to free the memory backing the stack.
.TP
.B new
The
.B stack_new
function returns a new
.B stack
object or
.B NULL
of memory could not be allocated in which case
.I errno
will be set to
.BR "ENOMEM" .
.TP
.B push
The
.B stack_push
function returns -1 and sets
.I errno
to an appropriate value if the operation failed or 0 if the data pointer was successfully pushed onto the stack (e.g.
.B ERANGE
if the stack is full).
.TP
.B pop
The
.B stack_pop
function returns the data pointer popped off the stack.
.TP
.B next
The
.B stack_next
function returns the next data pointer on the stack or
.B NULL
if the top of the stack has been exceeded.