Stack

# 14. 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.

### 14.1. Memory management functions

These functions should be used to create and destroy stack objects.

The `stack_init` function
Synopsis

      #include <mba/stack.h>
      int stack_init(struct stack *s, unsigned int max_size, struct allocator *al);

Description
The `stack_init` function initializes the stack `s` and saving a pointer to the allocator(3m) `al` which will be used to allocate memory for susequent stack operations. The stack will accept no more than `max` data pointers. If `max` is 0, `INT_MAX` elements may be pushed onto the stack.
Returns
The `stack_init` function returns -1 if `s` is a null pointer. Otherwise 0 is returned.

The `stack_deinit` function
Synopsis

      #include <mba/stack.h>
      int stack_deinit(struct stack *s, del_fn data_del, void *context)

Description
The `stack_deinit` function deinitializes the stack `s`. If the `data_del` function is not `NULL`, it will be called with the `context` parameter and each element on the stack.
Returns
The `stack_deinit` function returns 0 if the stack was successfully deinitialized or -1 if the `data_del` function returned anything other than 0 or if an error occured attempting to free the memory backing the stack.

The `stack_new` function
Synopsis

      #include <mba/stack.h>
      struct stack *stack_new(unsigned int max_size, struct allocator *al);

Description
Create a new stack(3) object that will accept no more than `max_size` data pointers. If `max_size` is 0, the stack will accept at most `INT_MAX` elements.
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>
      int stack_del(struct stack *s, del_fn data_del, void *context);

Description
The `stack_del` function deletes the stack object `s`. If the `data_del` function is not `NULL`, it will be called with each remaining element before deallocating the stack `s` itself.

The `stack_clear` function
Synopsis

      #include <mba/stack.h>
      int stack_clear(struct stack *s, del_fn data_del, void *context)

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

The `stack_clean` function
Synopsis

      #include <mba/stack.h>
      int stack_clean(struct stack *s)

Description
The `stack_clean` function reallocates the array backing the stack to be exactly the number of elements necessary. A stack(3m) will automatically shrink at an appropriate point but this function might be called by an allocator(3m) `reclaim_fn` function.

### 14.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 value if the operation failed or 0 if the data pointer was successfully pushed onto the stack (e.g. `ERANGE` if the stack is full).

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`.
Returns
The `stack_pop` function returns 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 to the bottom of the stack (the first element pushed onto the stack) and call `stack_next` 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 <mba2000 ioplex.com>