#include <stdio.h>
#include <stdlib.h>
#include "stack.h"

Functions
Stack	STACKinit (void(destroy)(void data))

void	STACKdestroy (Stack stk)

int	STACKpush (Stack stk, const void *data)

int	STACKpop (Stack stk, void **data)

void *	STACKpeek (Stack stk)

int	STACKisempty (Stack stk)

int	STACKsize (Stack stk)

Function Documentation

void STACKdestroy ( Stack stk )

Destroy the stack.

The stack is destroyed - that is, all memory occupied by the elements is deallocated. The user-defined callback function destroy, given as an argument to STACKinit(), is responsible for freeing dynamically allocated element data, when this function is called. When all elements and data have been deallocated - the stack header is deallocated, too.

Parameters

[in] stk - a reference to current stack.

Returns: Nothing.

See Also: STACKinit()

Definition at line 39 of file stack.c.

Stack STACKinit ( void(*)(void *data) destroy )

Initiate the stack.

Parameters

[in] destroy - A reference to a user-made function, reponsible for freeing element data, when the stack is deleted. If destroy is NULL - then element data will be left untouched when the list is destroyed.

Returns: A reference - to a new, empty stack - if dynamic memory allocation for the ADT was successful - or NULL otherwise. Take really good care of this return value, since it will be needed as a parameter in subsequent calls - to the majority of other stack handling functions in this stack function interface - i.e. a sort of "handle" to the stack.

See Also: STACKdestroy()

Definition at line 34 of file stack.c.

int STACKisempty ( Stack stk )

Determine if the stack is empty - or not.

Parameters

[in] stk - a reference to the current stack.

Returns: Value 1 - if the stack is indeed empty - or 0 otherwise.

Definition at line 59 of file stack.c.

void* STACKpeek ( Stack stk )

Peek at the top of the stack.

Parameters

[in] stk - reference to the current stack.

Returns: NULL if the stack is empty - or a reference to data of the top element, otherwise.

Definition at line 54 of file stack.c.

int STACKpop	(	Stack	stk,
		void **	data
	)

Remove(=pop) the top element.

When called, the 2nd parameter of this function, data, should reference an (external, user-defined) pointer. After the call - this referenced, external pointer has been redirected, to point to the data of the removed element - if the call was succesful. The caller is responsible for the future of this memory - deallocating it, if needed, for example.

Parameters

[in]	stk	- reference to current stack.
[out]	data	- reference to a pointer. After the call, this referenced pointer has been redirected to point to the data of the removed element - if the call was successful. The caller is responsible for the future of this memory - deallocating it, for example.

Returns: Value 0 - if the call was OK - or value -1 otherwise.

Definition at line 49 of file stack.c.

int STACKpush	(	Stack	stk,
		const void *	data
	)

Insert(=push) a new element - at the top of the stack.

This function inserts an new element - with a reference to its corresponding data, given by parameter data - at the top of the stack.

Parameters

[in]	stk	- reference to current stack
[in]	data	- reference to data to be stored in the new element, which is to be inserted at the top of the stack.

Returns: Value 0 - if everything went OK - or value -1 otherwise.

Definition at line 44 of file stack.c.

int STACKsize ( Stack stk )

Get the stack size.

Parameters

[in] stk - a reference to the current stack.

Returns: The size, that is, the number of elements in the stack.

Definition at line 64 of file stack.c.

Functions

Function Documentation