Array stack

A stack implementation based on Array. More...

Typedefs
typedef amxc_array_t	amxc_astack_t
	The array stack structure. More...
typedef amxc_array_it_t	amxc_astack_it_t
	The array stack iterator structure. More...
typedef amxc_array_it_delete_t	amxc_astack_it_delete_t
	Definition of the item delete function. More...

Functions
AMXC_INLINE int	amxc_astack_new (amxc_astack_t **astack)
	Allocates an array stack. More...
AMXC_INLINE void	amxc_astack_delete (amxc_astack_t **astack, amxc_astack_it_delete_t func)
	Frees the previously allocated array stack. More...
AMXC_INLINE int	amxc_astack_init (amxc_astack_t *const astack)
	Initializes an array stack. More...
AMXC_INLINE void	amxc_astack_clean (amxc_astack_t *const astack, amxc_astack_it_delete_t func)
	Removes all items from the array stack. More...
AMXC_INLINE amxc_astack_it_t *	amxc_astack_push (amxc_astack_t *const astack, void *data)
	Adds an item to the array stack. More...
AMXC_INLINE void *	amxc_astack_pop (amxc_astack_t *const astack)
	Removes the last added data from the stack. More...
AMXC_INLINE void *	amxc_astack_peek (amxc_astack_t *const astack)
	Peek the top of the stack, without removing. More...
AMXC_INLINE size_t	amxc_astack_size (const amxc_astack_t *const astack)
	Calculate the number of items on the stack, expressed in number of items. More...
AMXC_INLINE bool	amxc_astack_is_empty (const amxc_astack_t *const astack)
	Checks that the array stack is empty. More...

Detailed Description

A stack implementation based on Array.

The basic operators on a stack are push and pop.

Using the Array a stack can be created which has a initial size and can grow when needed.

It is possible to peek at the top of the stack, without removing the element, using amxc_astack_peek

When pushing data on the stack, the data will be put in the first empty bucket, if no empty bucket is available, the stack (bucket array) will grow.

When popping data, the last non empty bucket is returned.

Typedef Documentation

amxc_astack_it_delete_t

typedef amxc_array_it_delete_t amxc_astack_it_delete_t

Definition of the item delete function.

A pointer to a delete function is used in the following functions amxc_astack_delete, amxc_astack_clean

Definition at line 115 of file amxc_astack.h.

amxc_astack_it_t

typedef amxc_array_it_t amxc_astack_it_t

The array stack iterator structure.

Definition at line 105 of file amxc_astack.h.

amxc_astack_t

typedef amxc_array_t amxc_astack_t

The array stack structure.

Definition at line 98 of file amxc_astack.h.

Function Documentation

amxc_astack_clean()

AMXC_INLINE void amxc_astack_clean	(	amxc_astack_t *const	astack,
		amxc_astack_it_delete_t	func
	)

Removes all items from the array stack.

Removes all items from the array stack. If a delete function is provided, it is called for each item on the stack.

Parameters

astack	a pointer to the array stack structure
func	a pointer to a function that is called to free each item in the array stack

Definition at line 205 of file amxc_astack.h.

                                                                                  {
    amxc_array_clean(astack, func);
}

amxc_astack_delete()

AMXC_INLINE void amxc_astack_delete	(	amxc_astack_t **	astack,
		amxc_astack_it_delete_t	func
	)

Frees the previously allocated array stack.

Removes all items from the array stack, if a delete function is provided, it is called for each item on the stack.

Frees the allocated memory and sets the pointer to NULL.

Note

Only call this function for array stacks that are allocated on the heap using amxc_astack_new

Parameters

astack	a pointer to the location where the pointer to the array stack is be stored
func	pointer to a function that is called to free each item in the array stack

Definition at line 161 of file amxc_astack.h.

                                                                              {
    amxc_array_delete(astack, func);
}

amxc_astack_init()

AMXC_INLINE int amxc_astack_init

(

amxc_astack_t *const

astack

)

Initializes an array stack.

Initializes the array stack structure. All pointers are reset to NULL. This function is typically called for array stacks that are on the stack. Allocating and initializing an array stack on the heap can be done using amxc_astack_new

Note

When calling this function on an already initialized array stack, that contains items, the array stack is reset and all items in the stack are lost (Could lead to memory loss). Use amxc_astack_clean to remove all items from the stack.

Parameters

astack

a pointer to the array stack structure.

Returns

0 on success. -1 if a NULL pointer is given.

Definition at line 188 of file amxc_astack.h.

                                                  {
    return amxc_array_init(astack, 10);
}

amxc_astack_is_empty()

AMXC_INLINE bool amxc_astack_is_empty

(

const amxc_astack_t *const

astack

)

Checks that the array stack is empty.

Parameters

astack

a pointer to the array stack structure

Returns

returns true when the array stack contains no items, false when there is at least one item on the stack.

Definition at line 286 of file amxc_astack.h.

                                                             {
    return amxc_array_is_empty(astack);
}

amxc_astack_new()

AMXC_INLINE int amxc_astack_new

(

amxc_astack_t **

astack

)

Allocates an array stack.

Allocates and initializes memory to store an array stack. This function allocates memory from the heap, if an array stack is on the stack, it can be initialized using function amxc_astack_init

Note

The allocated memory must be freed when not used anymore, use amxc_astack_delete to free the memory

Parameters

astack

a pointer to the location where the pointer to the new array stack can be stored

Returns

-1 if an error occured. 0 on success

Definition at line 137 of file amxc_astack.h.

                                            {
    return amxc_array_new(astack, 10);
}

amxc_astack_peek()

AMXC_INLINE void* amxc_astack_peek

(

amxc_astack_t *const

astack

)

Peek the top of the stack, without removing.

Parameters

astack

a pointer to the array stack structure

Returns

The pointer to the data last added to the stack or NULL if no more items on the stack

Definition at line 255 of file amxc_astack.h.

                                                    {
    return amxc_array_get_last(astack);
}

amxc_astack_pop()

AMXC_INLINE void* amxc_astack_pop

(

amxc_astack_t *const

astack

)

Removes the last added data from the stack.

Parameters

astack

a pointer to the array stack structure

Returns

The pointer to the data last added to the stack or NULL if no more items on the stack.

Definition at line 239 of file amxc_astack.h.

                                                   {
    return amxc_array_take_last_data(astack);
}

amxc_astack_push()

AMXC_INLINE amxc_astack_it_t* amxc_astack_push	(	amxc_astack_t *const	astack,
		void *	data
	)

Adds an item to the array stack.

If the item is already in a stack, it is removed from that stack.

Parameters

astack	a pointer to the array stack structure
data	a pointer to the data that needs to be added to the stack

Returns

returns 0 when the item is added, -1 when there was an error

Definition at line 223 of file amxc_astack.h.

                                                                            {
    return amxc_array_append_data(astack, data);
}

amxc_astack_size()

AMXC_INLINE size_t amxc_astack_size

(

const amxc_astack_t *const

astack

)

Calculate the number of items on the stack, expressed in number of items.

Parameters

astack

a pointer to the array stack structure

Returns

The number of items on the array stack.

Definition at line 270 of file amxc_astack.h.

                                                           {
    return amxc_array_size(astack);
}