Linked stack

Typedefs
typedef amxc_llist_t	amxc_lstack_t
	The linked stack structure. More...
typedef amxc_llist_it_t	amxc_lstack_it_t
	The linked stack iterator structure. More...
typedef amxc_llist_it_delete_t	amxc_lstack_it_delete_t
	Definition of the item delete function. More...

Functions
AMXC_INLINE int	amxc_lstack_new (amxc_lstack_t **lstack)
	Allocates a linked stack. More...
AMXC_INLINE void	amxc_lstack_delete (amxc_lstack_t **lstack, amxc_lstack_it_delete_t func)
	Frees the previously allocated linked stack. More...
AMXC_INLINE int	amxc_lstack_init (amxc_lstack_t *const lstack)
	Initializes a linked stack. More...
AMXC_INLINE void	amxc_lstack_clean (amxc_lstack_t *const lstack, amxc_lstack_it_delete_t func)
	Removes all items from the linked stack. More...
AMXC_INLINE int	amxc_lstack_push (amxc_lstack_t *const lstack, amxc_lstack_it_t *const it)
	Adds an item to the linked stack. More...
AMXC_INLINE amxc_lstack_it_t *	amxc_lstack_pop (amxc_lstack_t *const lstack)
	Removes the last added item from the stack. More...
AMXC_INLINE amxc_lstack_it_t *	amxc_lstack_peek (amxc_lstack_t *const lstack)
	Peeks the top of the stack, without removing. More...
AMXC_INLINE size_t	amxc_lstack_size (const amxc_lstack_t *const lstack)
	Calculates the size of the stack, expressed in number of items. More...
AMXC_INLINE bool	amxc_lstack_is_empty (const amxc_lstack_t *const lstack)
	Checks if the linked stack is empty. More...
AMXC_INLINE int	amxc_lstack_it_init (amxc_lstack_it_t *const it)
	Initializes a linked stack iterator. More...

Detailed Description

Typedef Documentation

amxc_lstack_it_delete_t

typedef amxc_llist_it_delete_t amxc_lstack_it_delete_t

Definition of the item delete function.

A pointer to a delete function is used in the following functions amxc_lstack_delete, amxc_lstack_clean

Definition at line 99 of file amxc_lstack.h.

amxc_lstack_it_t

typedef amxc_llist_it_t amxc_lstack_it_t

The linked stack iterator structure.

Definition at line 89 of file amxc_lstack.h.

amxc_lstack_t

typedef amxc_llist_t amxc_lstack_t

The linked stack structure.

Definition at line 82 of file amxc_lstack.h.

Function Documentation

amxc_lstack_clean()

AMXC_INLINE void amxc_lstack_clean	(	amxc_lstack_t *const	lstack,
		amxc_lstack_it_delete_t	func
	)

Removes all items from the linked stack.

Removes all items from the linked stack, if a delete function is provided, it is called for each item after it was removed from the stack.

Parameters

lstack	a pointer to the linked stack structure
func	a pointer to a function that is called to free each item in the linked stack

Definition at line 190 of file amxc_lstack.h.

                                                                                  {
    amxc_llist_clean(lstack, func);
}

amxc_lstack_delete()

AMXC_INLINE void amxc_lstack_delete	(	amxc_lstack_t **	lstack,
		amxc_lstack_it_delete_t	func
	)

Frees the previously allocated linked stack.

Removes all items from the linked stack, if a delete function is provided, it is called for each item after it was removed from the stack.

Frees the allocated memory and sets the pointer to NULL.

Note

Only call this function for linked stacks that are allocated on the heap using amxc_lstack_new

Parameters

lstack	a pointer to the location where the pointer to the linked stack is stored
func	a pointer to a function that is called to free each item in the linked stack

Definition at line 146 of file amxc_lstack.h.

                                                                              {
    amxc_llist_delete(lstack, func);
}

amxc_lstack_init()

AMXC_INLINE int amxc_lstack_init

(

amxc_lstack_t *const

lstack

)

Initializes a linked stack.

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

Note

When calling this function on an already initialized linked stack, that contains items, the linked stack is reset and all items in the stack are lost. Use amxc_lstack_clean to remove all items from the stack.

Parameters

lstack

a pointer to the linked stack structure.

Returns

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

Definition at line 172 of file amxc_lstack.h.

                                                  {
    return amxc_llist_init(lstack);
}

amxc_lstack_is_empty()

AMXC_INLINE bool amxc_lstack_is_empty

(

const amxc_lstack_t *const

lstack

)

Checks if the linked stack is empty.

Parameters

lstack

a pointer to the linked stack structure

Returns

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

Definition at line 275 of file amxc_lstack.h.

                                                             {
    return amxc_llist_is_empty(lstack);
}

amxc_lstack_it_init()

AMXC_INLINE int amxc_lstack_it_init

(

amxc_lstack_it_t *const

it

)

Initializes a linked stack iterator.

Initializes the linked stack iterator structure. All pointers are reset to NULL.

Note

When calling this function on an already initialized linked stack iterator, the linked stack iterator is reset and the stack the iterator was in, is corrupted. Use amxc_lstack_pop to remove the iterator from the stack

Parameters

it	a pointer to the linked stack iterator structure.

Returns

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

Definition at line 299 of file amxc_lstack.h.

                                                    {
    return amxc_llist_it_init(it);
}

amxc_lstack_new()

AMXC_INLINE int amxc_lstack_new

(

amxc_lstack_t **

lstack

)

Allocates a linked stack.

Allocates and initializes memory to store a linked stack. This function allocates memory from the heap, if a linked stack is on the stack, it can be initialized using function amxc_lstack_init

Note

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

Parameters

lstack

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

Returns

-1 if an error occured. 0 on success

Definition at line 122 of file amxc_lstack.h.

                                            {
    return amxc_llist_new(lstack);
}

amxc_lstack_peek()

AMXC_INLINE amxc_lstack_it_t* amxc_lstack_peek

(

amxc_lstack_t *const

lstack

)

Peeks the top of the stack, without removing.

Parameters

lstack

a pointer to the linked stack structure

Returns

The iterator to the last added item or NULL if no more items on the stack

Definition at line 243 of file amxc_lstack.h.

                                                                {
    return amxc_llist_get_last(lstack);
}

amxc_lstack_pop()

AMXC_INLINE amxc_lstack_it_t* amxc_lstack_pop

(

amxc_lstack_t *const

lstack

)

Removes the last added item from the stack.

Parameters

lstack

a pointer to the linked stack structure

Returns

The iterator to the last added item or NULL if no more items on the stack

Definition at line 228 of file amxc_lstack.h.

                                                               {
    return amxc_llist_take_last(lstack);
}

amxc_lstack_push()

AMXC_INLINE int amxc_lstack_push	(	amxc_lstack_t *const	lstack,
		amxc_lstack_it_t *const	it
	)

Adds an item to the linked stack.

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

Note

Make sure that the iterator of the item is at least initialized when it is first used. Initializing an iterator can be done using amxc_lstack_it_init. An iterator that is already used in a linked stack is considered initialized.

Parameters

lstack	a pointer to the linked stack structure
it	a pointer to the linked stack item iterator

Returns

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

Definition at line 213 of file amxc_lstack.h.

                                                                              {
    return amxc_llist_append(lstack, it);
}

amxc_lstack_size()

AMXC_INLINE size_t amxc_lstack_size

(

const amxc_lstack_t *const

lstack

)

Calculates the size of the stack, expressed in number of items.

Parameters

lstack

a pointer to the linked stack structure

Returns

The number of items on the linked stack.

Definition at line 259 of file amxc_lstack.h.

                                                           {
    return amxc_llist_size(lstack);
}