12. Stack
The stack functions manipulate a simple LIFO stack of pointers to objects but the underlying array will grow and shrink as storage requirements change.
12.1. Memory management functions
These functions should be used to create and destroy stack objects.
The stack_new function
Synopsis
#include <mba/stack.h>
struct stack *stack_new(unsigned int max);
Description
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.
Returns
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.
The stack_del function
Synopsis
#include <mba/stack.h>
void stack_del(struct stack *s, void (*free_data_fn)(void *));
Description
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.
The stack_clear function
Synopsis
#include <mba/stack.h>
void stack_clear(struct stack *s, void (*free_data_fn)(void *));
Description
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.
12.2. Stack functions
The stack_push function
Synopsis
#include <mba/stack.h>
int stack_push(struct stack *s, void *data);
Description
The stack_push function pushes the element data onto the stack identified by s;
Returns
The stack_push function returns -1 and sets errno to an appropriate valid if the operation failed or 0 if the data pointer was successfully pushed on the stack.
The stack_pop function
Synopsis
#include <mba/stack.h>
void *stack_pop(struct stack *s);
Description
The stack_pop function removes the last element pushed onto the stack s (the top).
Returns
The stack_pop function returned the data pointer popped off the stack.
The stack_is_empty function
Synopsis
#include <mba/stack.h>
int stack_is_empty(const struct stack *s);
Description
Returns non-zero if the stack s has no elements and 0 otherwise.
The stack_size function
Synopsis
#include <mba/stack.h>
unsigned int stack_size(const struct stack *s);
Description
The stack_size function returns the number of elements currently on the stack.
The stack_iterate function
Synopsis
#include <mba/stack.h>
void stack_iterate(void *s, iter_t *iter);
Description
Enumerate each element on the stack. Call stack_iterate to initialize the iter object to point tothe 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.
The stack_next function
Synopsis
#include <mba/stack.h>
void *stack_next(void *s, iter_t *iter);
Returns
The stack_next function returns the next data pointer on the stack or NULL if the top of the stack has been exceeded.
The stack_peek function
Synopsis
#include <mba/stack.h>
void *stack_peek(struct stack *s);
Description
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.
Copyright 2002 Michael B. Allen <mballen@erols.com>