CtplStack

CtplStack — Stack

Synopsis

#include <ctpl/stack.h>

                    CtplStack;
CtplStack *         ctpl_stack_new                      (GCompareFunc compare_func,
                                                         GFreeFunc free_func);
void                ctpl_stack_free                     (CtplStack *stack);
void                ctpl_stack_push                     (CtplStack *stack,
                                                         gpointer data);
gboolean            ctpl_stack_push_ref                 (CtplStack *stack);
gpointer            ctpl_stack_pop                      (CtplStack *stack);
gpointer            ctpl_stack_peek                     (const CtplStack *stack);
gboolean            ctpl_stack_is_empty                 (const CtplStack *stack);

Description

A stack optimised for storing same data multiple times at once. E.g., pushing "foo", "bar", "bar", "bar" could use only 2 data structures and not 4 since the three last elements may shares the same structure.

If a comparison function was given when creating the stack with ctpl_stack_new(), when you push an element in the stack that the comparison function reports as being the same as the last pushed one, a reference to it will be created in place of a new entry, and the data that was queried to be pushed will be free using the free function, if any. This allows an easy use of references in place of actual entry appending, saving both memory and computation time. If you don't want to use automatic references, simply don't provide a comparison function to ctpl_stack_new().

A CtplStack is created with ctpl_stack_new() and freed using ctpl_stack_free(). You can push data into a stack using ctpl_stack_push() and ctpl_stack_push_ref(), pop the data using ctpl_stack_pop() and gets the data using ctpl_stack_peek().

Example 12. Simple use of a CtplStack.

1
2
3
4
5
6
7
8
9
10
11
CtplStack *stack;

stack = ctpl_stack_new (g_strcmp0, NULL);
ctpl_stack_push (stack, "foo");
ctpl_stack_push (stack, "bar");

while (! ctpl_stack_is_empty (stack)) {
  printf ("%s\n", (char *)ctpl_stack_pop (stack));
}

ctpl_stack_free (stack);


Details

CtplStack

typedef struct _CtplStack CtplStack;

Opaque object representing a stack.


ctpl_stack_new ()

CtplStack *         ctpl_stack_new                      (GCompareFunc compare_func,
                                                         GFreeFunc free_func);

Creates a new empty CtplStack.

compare_func :

A GCompareFunc to compare data, or NULL

free_func :

A GFreeFunc to free pushed data, or NULL

Returns :

A new CtplStack

ctpl_stack_free ()

void                ctpl_stack_free                     (CtplStack *stack);

Frees a CtplStack

stack :

A CtplStack

ctpl_stack_push ()

void                ctpl_stack_push                     (CtplStack *stack,
                                                         gpointer data);

Adds data in top of stack. This function pushes data into the stack. If possible, it pushes a reference instead of actually pushing the data, see above examples and explanations for more details on actual pushing versus reference incrementation.

stack :

A CtplStack into which push data

data :

Some data to push into stack

ctpl_stack_push_ref ()

gboolean            ctpl_stack_push_ref                 (CtplStack *stack);

Adds a new reference to the last pushed item of the stack. You probably won't use this function but prefer use the automated way to do this bay providing a comparison function when creating the stack. See ctpl_stack_new().

stack :

A CtplStack

Returns :

TRUE on success, FALSE if the stack was empty, then no reference could be added. Trying to push a reference on an empty stack is considered as a programming error and outputs a critical message.

ctpl_stack_pop ()

gpointer            ctpl_stack_pop                      (CtplStack *stack);

Gets and removes the last pushed element from stack.

stack :

A CtplStack from which pop the last element

Returns :

The last pushed data, or NULL if the stack was empty. As it is not possible to know if this function returned NULL because of an empty stack or because the last pushed element is NULL, you should use ctpl_stack_is_empty() to check whether the stack contains or not some elements.

ctpl_stack_peek ()

gpointer            ctpl_stack_peek                     (const CtplStack *stack);

Peeks (gets) the top-level element of a CtplStack. See ctpl_stack_pop() if you want to get the element and pop it from the stack.

stack :

A CtplStack

Returns :

The top-level data of stack, or NULL if the stack is empty.

ctpl_stack_is_empty ()

gboolean            ctpl_stack_is_empty                 (const CtplStack *stack);

Checks whether stack is empty.

stack :

A CtplStack

Returns :

TRUE if the stack is empty, FALSE otherwise.