![]() |
![]() |
![]() |
CTPL Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#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
);
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); |
CtplStack * ctpl_stack_new (GCompareFunc compare_func
,GFreeFunc free_func
);
Creates a new empty CtplStack.
|
A GCompareFunc to compare data, or NULL
|
|
A GFreeFunc to free pushed data, or NULL
|
Returns : |
A new CtplStack |
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.
|
A CtplStack into which push data
|
|
Some data to push into stack
|
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()
.
gpointer ctpl_stack_pop (CtplStack *stack
);
Gets and removes the last pushed element from 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. |
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.