bglibs: adt gstack: Generic simple stack.

- Main Page
- Modules
- Data Structures
- Files
- Directories
- Related Pages
- Examples

# adt gstack: Generic simple stack.

## Data Structures
struct | gstack_node
struct | gstack
## Defines
#define | GSTACK_DECL(PREFIX, TYPE)
#define | GSTACK_PUSH_DEFN(PREFIX, TYPE, COPY)
#define | GSTACK_TOP_DEFN(PREFIX, TYPE)
#define | GSTACK_POP_DEFN(PREFIX, FREE)
#define | GSTACK_DEFN(PREFIX, TYPE, COPY, FREE)
## Functions
int | gstack_push (struct gstack *d, unsigned datasize, const void *data, adt_copy_fn *fn)
void * | gstack_top (const struct gstack *s)
void | gstack_pop (struct gstack *s, adt_free_fn *fn)

## Detailed Description

A generic stack is a first-in-last-out structure defined here based on three primary operations: push, top, and pop. Pushing an element onto a stack adds it to the head of the list. The top operation fetches the most recently pushed element still on the stack, and popping removes it.

## Define Documentation

#define GSTACK_DECL | ( | PREFIX,
|  | TYPE |  | ) |

Value:

    extern int PREFIX##_push(struct gstack* s, TYPE const* data); \
    extern TYPE* PREFIX##_top(struct gstack* s); \
    extern void PREFIX##_pop(struct gstack* s);

Declare specialized `gstack` functions.

Examples:
  adt/gstack_test.c.

#define GSTACK_DEFN | ( | PREFIX,
|  | TYPE,
|  | COPY,
|  | FREE |  | ) |

Value:

    GSTACK_PUSH_DEFN(PREFIX,TYPE,COPY) \
    GSTACK_TOP_DEFN(PREFIX,TYPE) \
    GSTACK_POP_DEFN(PREFIX,FREE)

Define all the specialized `gstack` functions. If `COPY` is `NULL`, a simple memcpy is used instead. If `FREE` is `NULL`, no attempt is made to free the data.

Examples:
  adt/gstack_test.c.

#define GSTACK_POP_DEFN | ( | PREFIX,
|  | FREE |  | ) |

Value:

    void PREFIX##_pop(struct gstack* s) { \
      gstack_pop(s, (adt_free_fn*)(FREE)); \
    }

Define a specialized `gstack` pop function.

#define GSTACK_PUSH_DEFN | ( | PREFIX,
|  | TYPE,
|  | COPY |  | ) |

Value:

    int PREFIX##_push(struct gstack* s, TYPE const* data) { \
      return gstack_push(s, sizeof *data, data, (adt_copy_fn*)COPY); \
    }

Define a specialized `gstack` push function.

#define GSTACK_TOP_DEFN | ( | PREFIX,
|  | TYPE |  | ) |

Value:

    TYPE* PREFIX##_top(struct gstack* s) { \
      return (s->head == 0) ? 0 : (TYPE*)s->head->data; \
    }

Define a specialized `gstack` top function.

## Function Documentation

void gstack_pop | ( | struct gstack * | s,
|  | adt_free_fn * | fn |
| ) |  |  |

Remove the first (most recently pushed) element from the queue. If the free function `fn` is `NULL` no data freeing is done. Note that this does not return a pointer to the popped item, as once the item has been popped it is also freed.

int gstack_push | ( | struct gstack * | s,
|  | unsigned | datasize,
|  | const void * | data,
|  | adt_copy_fn * | fn |
| ) |  |  |

Add a new element onto the stack. If the copy function `fn` is `NULL` memcpy is used in its place.

void* gstack_top | ( | const struct gstack * | s | ) |

Return the address of first (most recently pushed) element in the queue.