bglibs: adt gstack: Generic simple stack.

bglibs

Data Structures | Macros | Functions
adt gstack: Generic simple stack.

## Data Structures
struct | gstack_node
struct | gstack

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

## Macro Definition Documentation

## ◆ GSTACK_DECL

#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);
gstack
Definition: gstack.h:29

Declare specialized `gstack` functions.

Examples:
  adt/gstack_test.c.

## ◆ GSTACK_DEFN

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

Value:
GSTACK_PUSH_DEFN(PREFIX,TYPE,COPY) \
GSTACK_TOP_DEFN(PREFIX,TYPE) \
GSTACK_POP_DEFN(PREFIX,FREE)
GSTACK_PUSH_DEFN
#define GSTACK_PUSH_DEFN(PREFIX, TYPE, COPY)
Definition: gstack.h:49

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.

## ◆ GSTACK_POP_DEFN

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

Value:
void PREFIX##_pop(struct gstack* s) { \
gstack_pop(s, (adt_free_fn*)(FREE)); \
}
adt_free_fn
void adt_free_fn(void *)
Definition: adt_common.h:12
gstack
Definition: gstack.h:29

Define a specialized `gstack` pop function.

## ◆ GSTACK_PUSH_DEFN

#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); \
}
gstack
Definition: gstack.h:29
gstack_push
int gstack_push(struct gstack *d, unsigned datasize, const void *data, adt_copy_fn *fn)
Definition: gstack_push.c:8
adt_copy_fn
int adt_copy_fn(void *, const void *)
Definition: adt_common.h:16

Define a specialized `gstack` push function.

## ◆ GSTACK_TOP_DEFN

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

Value:
TYPE* PREFIX##_top(struct gstack* s) { \
return (s->head == 0) ? 0 : (TYPE*)s->head->data; \
}
gstack::head
struct gstack_node * head
Definition: gstack.h:32
gstack
Definition: gstack.h:29
gstack_node::data
char data[0]
Definition: gstack.h:25

Define a specialized `gstack` top function.

## Function Documentation

## ◆ gstack_pop()

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.

References gstack::count, gstack_node::data, gstack::head, and gstack_node::next.

## ◆ gstack_push()

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.

References gstack::count, gstack_node::data, gstack::head, and gstack_node::next.

## ◆ gstack_top()

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

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

References gstack_node::data, and gstack::head.