linkedstack.h File Reference

This header file contains the structures and functions needed to work with stacks (implemented using doubly-linked lists). More...

Typedefs
typedef linkedstack_adt *	LinkedStack
	Pointer to structure representing a stack.
Functions
LinkedStack	LS_New ()
	Creates a new stack.
void	LS_Free (LinkedStack stack)
	Destroys the specified stack.
int	LS_Size (LinkedStack stack)
	Returns the size of the stack.
int	LS_Empty (LinkedStack stack)
	Determines if the stack is empty or not.
void	LS_Push (LinkedStack stack, void *el)
	Adds an element to the top of the stack.
void	LS_Pop (LinkedStack stack)
	Removes an element from the top of the stack.
void *	LS_Top (LinkedStack stack)
	Retrieves the data in the element at the top of the stack. The function returns the data in the element at the top of the stack but does not alter in any way the structure of the stack. However the actual data can be changed through the use of the void* pointer returned, which points to the memory location containing the data.

---

Detailed Description

This header file contains the structures and functions needed to work with stacks (implemented using doubly-linked lists).

Author:

Mihai Balan

It contains functions for creating a stack, destroying it and all the typical operations on a stack (push, pop, top).

---

Typedef Documentation

typedef struct linkedstack_adt* LinkedStack

Pointer to structure representing a stack.

The LinkedStack is implemented using a LinkedList . However, the underlying LinkedList should not be modified directly but only through the appropriate functions.

As is the case with the LinkedList element data is stored using a void* pointer. Thus, one should note there is no way to tell what kind of data is stored in the list or in a particular element.

See also:

LS_New(), LS_Free(), LS_Pop(), LS_Push(), LS_Top()

---

Function Documentation

int LS_Empty

(

LinkedStack

stack

)

Determines if the stack is empty or not.

The function actually returns the value of the expression Size==0.

Parameters:

stack

the stack to be tested.

Returns:

-1 if stack is NULL, 1 if the stack is empty, 0 otherwise.

void LS_Free

(

LinkedStack

stack

)

Destroys the specified stack.

The function freees the memory used by the stack structure itself as well as the memory used by the data in the stack, so trying to access the data after the destruction of the stack (e.g. through a pointer) will most likely result in a Access Violation / segfault.

Parameters:

stack

LinkedStack representing the stack to be destroyed.

LinkedStack LS_New

(

)

Creates a new stack.

The function creates a new linked stack (stack implemented using a LinkedList ).

Returns:

pointer to the newly created stack.

void LS_Pop

(

LinkedStack

stack

)

Removes an element from the top of the stack.

The function removes the element at the top of the stack. Note that the data in that element is not freed, so that it can be further referenced.

Parameters:

stack

the stack on which to perfom the operation

See also:

LS_Top()

void LS_Push	(	LinkedStack	stack,
		void *	el
	)

Adds an element to the top of the stack.

The function adds the data specified by el to the top of the stack.

Parameters:

	stack	the stack to add data to.
	*el	pointer to a initialized memory location containing the data to be added at the top of the stack.

int LS_Size

(

LinkedStack

stack

)

Returns the size of the stack.

The function returns the number of elements in the stack.

Parameters:

stack

stack to be tested

Returns:

number of elements in the stack.

void* LS_Top

(

LinkedStack

stack

)

Retrieves the data in the element at the top of the stack. The function returns the data in the element at the top of the stack but does not alter in any way the structure of the stack. However the actual data can be changed through the use of the void* pointer returned, which points to the memory location containing the data.

Parameters:

stack

the stack on which to perform the operation

Returns:

if stack is NULL or empty, it returns NULL . Otherwise, it returns a pointer to the memory location where the data in the element at the top of the stack is stored.

---