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);

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)

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)); \
}

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); \
}

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; \
}

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.