stack.h File Reference

#include "_bk_defines.h"

Include dependency graph for stack.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct internal_deque *	stack

Functions
stack	stack_init (size_t data_size)
size_t	stack_size (stack me)
bk_bool	stack_is_empty (stack me)
bk_err	stack_trim (stack me)
void	stack_copy_to_array (void *arr, stack me)
bk_err	stack_push (stack me, void *data)
bk_bool	stack_pop (void *data, stack me)
bk_bool	stack_top (void *data, stack me)
bk_err	stack_clear (stack me)
stack	stack_destroy (stack me)

Typedef Documentation

stack

typedef struct internal_deque* stack

The stack data structure, which adapts a container to provide a stack (last-in first-out). Adapts the deque container.

Function Documentation

stack_clear()

bk_err stack_clear

(

stack

me

)

Clears the stack and sets it to the state from original initialization.

Parameters

me	the stack to clear

Returns

BK_OK if no error

-BK_ENOMEM if out of memory

stack_copy_to_array()

void stack_copy_to_array	(	void *const	arr,
		stack	me
	)

Copies the stack to an array. Since it is a copy, the array may be modified without causing side effects to the stack data structure. Memory is not allocated, thus the array being used for the copy must be allocated before this function is called.

Parameters

arr	the initialized array to copy the stack to
me	the stack to copy to the array

stack_destroy()

stack stack_destroy

(

stack

me

)

Frees the stack memory. Performing further operations after calling this function results in undefined behavior. Freeing NULL is legal, and causes no operation to be performed.

Parameters

me	the stack to destroy

Returns

NULL

stack_init()

stack stack_init

(

const size_t

data_size

)

Initializes a stack.

Parameters

data_size

the size of each data element in the stack; must be positive

Returns

the newly-initialized stack, or NULL if it was not successfully initialized due to either invalid input arguments or memory allocation error

stack_is_empty()

bk_bool stack_is_empty

(

stack

me

)

Determines if the stack is empty, meaning it contains no elements.

Parameters

me	the stack to check if empty

Returns

BK_TRUE if the stack is empty, otherwise BK_FALSE

stack_pop()

bk_bool stack_pop	(	void *const	data,
		stack	me
	)

Removes the top element of the stack, and copies the data which is being removed. The pointer to the data being obtained should point to the data type which this stack holds. For example, if this stack holds integers, the data pointer should be a pointer to an integer. Since this data is being copied from the array to the data pointer, the pointer only has to be valid when this function is called.

Parameters

data	the copy of the element being removed
me	the stack to remove the top element from

Returns

BK_TRUE if the stack contained elements, otherwise BK_FALSE

stack_push()

bk_err stack_push	(	stack	me,
		void *const	data
	)

Adds an element to the top of the stack. The pointer to the data being passed in should point to the data type which this stack holds. For example, if this stack holds integers, the data pointer should be a pointer to an integer. Since the data is being copied, the pointer only has to be valid when this function is called.

Parameters

me	the stack to add an element to
data	the data to add to the stack

Returns

BK_OK if no error

-BK_ENOMEM if out of memory

-BK_ERANGE if size has reached representable limit

stack_size()

size_t stack_size

(

stack

me

)

Determines the size of the stack.

Parameters

me	the stack to check size of

Returns

the size of the stack

stack_top()

bk_bool stack_top	(	void *const	data,
		stack	me
	)

Copies the top element of the stack. The pointer to the data being obtained should point to the data type which this stack holds. For example, if this stack holds integers, the data pointer should be a pointer to an integer. Since this data is being copied from the array to the data pointer, the pointer only has to be valid when this function is called.

Parameters

data	the copy of the top element of the stack
me	the stack to copy from

Returns

BK_TRUE if the stack contained elements, otherwise BK_FALSE

stack_trim()

bk_err stack_trim

(

stack

me

)

Frees unused memory from the stack.

Parameters

me	the stack to trim

Returns

BK_OK if no error

-BK_ENOMEM if out of memory