Stack

LIFO stack of void *. Use the stack functions to maintain its ordering.

Usage#

Create and initialize a Stack. Pass NULL for stack allocated payloads, or a destructor such as free for payloads the stack should free when destroyed.

Stack stack;
stack_init(&stack, NULL);
int value = 42;
if (stack_push(&stack, &value) == 0) {
    void *data;
    if (stack_pop(&stack, &data) == 0) {
        /* data points to value. */
    }
}
stack_destroy(&stack);

Removal returns the payload without calling the destructor. Destroy frees the remaining nodes and runs the destructor on their payloads. It does not free the Stack handle.

Structs#

Stack#

typedef struct {
    List impl;
} Stack;

The top of the stack is the most recently pushed element.

Functions#

stack_init#

Initializes an empty stack. You own the Stack handle. destroy is an optional deallocation function for payloads remaining at destruction; pass NULL for borrowed data.

void stack_init(Stack *stack, void (*destroy)(void *data));

/* Usage */
Stack *stack = malloc(sizeof(Stack));

// Pass NULL for stack-allocated memory
stack_init(stack, NULL);

// Pass free or a custom freeing function for heap allocated memory
stack_init(stack, free);

stack_destroy#

Destroys the nodes inside a Stack and calls the deallocation function on the data if one was provided. Does not destroy the stack itself, that is left up to the user.

void stack_destroy(Stack *stack);

stack_push#

Push a new element onto the top of the stack. Returns 0 on success, -1 on error.

int stack_push(Stack *stack, const void *data);

/* Usage */
int x = 42;
stack_push(stack, &x);

stack_peek#

Returns a void * to the top element of the stack. Does not remove the element. Returns NULL if the stack is empty or the stored payload is NULL.

void *stack_peek(Stack *stack);

/* Usage */
// stack: 1 2 3
int *t = (int*)stack_peek(stack);
assert(*t == 3);
// stack: 1 2 3

stack_pop#

Pops the top element of the stack and stores its data in data. Returns 0 on success, -1 if the stack is empty or data is NULL. The destructor is not called. A NULL output does not remove the item.

int stack_pop(Stack *stack, void **data);

/* Usage */
// stack: 1 2 3
void *data;
stack_pop(stack, &data);
int *t = data;
assert(*t == 3);
// stack: 1 2

Macros#

stack_size#

Returns the number of elements in the stack.

#define stack_size(s) ((s)->impl.size)

stack_is_empty#

Returns true if the stack has no elements.

#define stack_is_empty(s) ((s)->impl.size == 0)