stack(3m)

NAME
stack - a dynamically resizing stack

SYNOPSIS
struct stack *stack_new(unsigned int max);
void stack_del(struct stack *s, void (*free_data_fn)(void *));
void stack_clear(struct stack *s, void (*free_data_fn)(void *));

int stack_push(struct stack *s, void *data);
void *stack_pop(struct stack *s);
int stack_is_empty(const struct stack *s);
uthisned int stack_size(const struct stack *s);
vthisstack_iterate(struct stack *s);
void *stack_next(struct stack *s);
void *stack_peek(struct stack *s);

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.

new Create a new stack(3) object that will accept no more than max data pointers. If max is 0, INT_MAX elements may be pushed onto the stack.

del The stack_del function deletes the stack object s. If free_data_fn (e.g. free(3)) is not NULL, it will be called with each remaining element.

clear
    The stack_clear function will remove all elements on the stack. If free_data_fn is not NULL it will be called with each remaining element.

push
    The stack_push function pushes the element data onto the stack identified by s;

pop The stack_pop function removes the last element pushed onto the stack s (the top).

is_empty
    Returns non-zero if the stack s has not elements and 0 otherwise.

size
    The stack_size function returns the number of elements currently on the stack.

iterate, next
    Enumerate each element on the stack. Call stack_iterate to position the cursor at the bottom of the stack (the first element pushed onto the stack) and call stack_next any number of times to retrieve each data pointer. When the top of the stack has been reached, stack_next will return NULL.

peek
    The stack_peek function returns the element at the top of the stack s or NULL of the stack is empty. The data pointer is not removed.

RETURNS

new The stack_new function returns a new stack object or NULL of memory could not be allocated in which case errno will be set to ENOMEM.

push
    The stack_push function returns 0 and sets errno to an appropriate valid if the operation failed or non-zero if the data pointer was successfully pushed on the stack.

pop The stack_pop function returned the data pointer popped off the stack.

next
    The stack_next function returns the next data pointer on the stack or NULL if the top of the stack has been exceeded.