genericStack - generic stack interface
genericStack is a set of macros to manage a stack. It is is generic in the sense that it is not restricted to one type of variable. It is recommended to always use valid C identifiers in these macros.
#include <genericStack.h> genericStack_t myStack, *myStackp; /* The generic stack can be on the stack */ myStackp = &myStack; GENERICSTACK_INIT(myStackp); /* ... */ GENERICSTACK_RESET(myStackp); /* ... or on the heap */ GENERICSTACK_NEW(myStackp); /* ... */ GENERICSTACK_FREE(myStackp);
Initialize a stack pointer that is on the stack. Memory will be released with GENERICSTACK_RESET(stackName).
Create an empty stack referenced with the name stackName itself on the stack, though pre-allocating room for wantedSize elements>. The stack will also automatically grow if user if putting an element beyond wantedSize.
stackName
wantedSize
Create an empty stack referenced with the name stackName. The stack will automatically grow if needed.
Create an empty stack referenced with the name stackName, though pre-allocating room for wantedSize elements>. The stack will also automatically grow if user if putting an element beyond wantedSize.
Set an entry in stack stackName, at index index (numbering start 0), using the result of the expression var. XXX is meant to be a C datatype or an array (the later being nothing else but a PTR associated to a length), i.e. the exact list of macros is:
index
var
Set var expression result, explicitely typecasted into a char.
char
Set var expression result, explicitely typecasted into a short.
short
Set var expression result, explicitely typecasted into an int.
int
Set var expression result, explicitely typecasted into a long.
long
Set var expression result, explicitely typecasted into a long double.
long double
Set var expression result, explicitely typecasted into a float.
float
Set var expression result, explicitely typecasted into a double.
double
Set var expression result, explicitely typecasted into a void *.
void *
Set var, that is an internal structure containing both a pointer and a length to fully describe an array.
Set *var, that is an internal structure containing both a pointer and a length to fully describe an array.
*var
C99 datatypes (see NOTES) may be available via:
Set var expression result, explicitely typecasted into a long long.
long long
Set var expression result, explicitely typecasted into a _Bool.
_Bool
Set var expression result, explicitely typecasted into a float _Complex.
float _Complex
Set var expression result, explicitely typecasted into a double _Complex.
double _Complex
Set var expression result, explicitely typecasted into a long double _Complex.
long double _Complex
Custom datatype (see NOTES) is available via:
Set var expression result, explicitely typecasted into a GENERICSTACK_CUSTOM.
GENERICSTACK_CUSTOM
Set *var expression result, explicitely typecasted into a GENERICSTACK_CUSTOM.
Specific macro that removes any association at position index.
Get an entry in stack stackName, at index index (numbering start 0). The data type of the entry is left as-is, letting the compiler do type promotion, and eventually warn. XXX is meant to be a C datatype, an array, or an array pointer, i.e. the exact list of macros is:
Returns a pointer to the array element.
Custom datatype (see NOTES) may be available via:
This is an interface on top of <GENERICSTACK_SET_XXX>, that it automatically pushing data on the stack, the later will increase if needed.
This is an interface on top of <GENERICSTACK_GET_XXX>, that it automatically popping data from the stack (i.e. retreive the last argument, and (artificially) reduce the generic stack size.
Check if item at indice index is of type <XXX>, and returns a true or false value.
Releases a stack that is on the heap.
Releases a stack that is on the stack. It can be reused.
Fast dispose of a stack for immediate reuse. This does not prevent the user to call GENERICSTACK_RESET() or GENERICSTACK_FREE(), though.
GENERICSTACK_RESET()
GENERICSTACK_FREE()
Return a true value if there is an error. Should be called after every call to:
Return the number of available items always available.
Return the number of available items allocated on the heap.
Return the total number of available items.
Return the total used items. This can be used as l-value, the effect is to pretend that the stack is empty without releasing internal memory, the later will be reused if necessary. If you believe that the internal size of the stack (in particular the memory allocated on the heap) fit the whole lifetime of the stack, this is by far more effcient than doing sequences of FREE (or RESET) followed by NEW (or INIT, respectively).
Handy macro that dump the stack on stderr.
Reset error to a false value.
Switches items at positions i1 and i2.
i1
i2
Returns the type of the item at position index within stack stackName.
Convenient enum associating a value to the item type XXX, for example:
XXX
is the value 0
0
is the value 1
1
and so on.
Generates a basic C type from the item type XXX, for example:
generates char
generates short
An array is a special case of PTR, associated to a length. Internally, it is represented with the typedef genericStackItemTypeArray_t:
genericStackItemTypeArray_t
typedef struct genericStackItemTypeArray { void *p; size_t lengthl; } genericStackItemTypeArray_t;
nevertheless, the convenient macros should be used:
The array type.
Pointer associated to the array. Can be an l-value.
Idem, except that a is now a pointer to the array structure.
a
Length associated to the array. Can be an l-value.
Whenever ARRAYP interface exist, it means its argument is a pointer to the array internal structure. That is, for example:
*GENERICSTACK_GET_ARRAYP(stackName, indice)
and
GENERICSTACK_GET_ARRAY(stackName, indice)
will return the same information.
There is no GENERICSTACK_POP_ARRAYP, because when popped, the structure describing an array leave only in user-space, no more within the generic stack.
C99 data types are all available if the GENERICSTACK_C99 macro is defined. Otherwise, partial support of C99 from the compiler support is handled like this:
GENERICSTACK_C99
This genericStack should fit ok for small up to medium size stacks, not huge stacks because of its internal usage of an array instead of a linked list. The later implementation is not that hard, but left as an exercise to the reader.
The default is:
Minimum number of items that are always available. If necessary the stack will use the heap for increase. Default value is 128.
You should set this only if your system is not using only zero bytes to describe the integer nummber 0. Not defined by default.
If this #define is a true value, then long long is supported.
If this #define is a true value, then _Bool is supported.
If this #define is a true value, then float _Complex, double _Complex and long double _Complex are supported.
If this #define is a true value, then GENERICSTACK_CUSTOM custom type, that has to be defined prior to the include of genericStack.h, is supported,
genericStack.h
If this #define is a true value, this must be a valid datatype, then GENERICSTACK_HAVE_CUSTOM is automatically set to a true value. Example:
GENERICSTACK_HAVE_CUSTOM
typedef struct myStruct { short isstring; union { int i; char *s; } u; } myStruct_t; #define GENERICSTACK_CUSTOM myStruct_t #include <genericStack.h>
The GENERICSTACK_GET_CUSTOMP macro is in particulary very convenient if you want to work with the data directly in the stack.
GENERICSTACK_GET_CUSTOMP
This generic stack implementation supports indices that are expressions. The side-effect is that it is recommended to not use more than one generic stack macro on the same stack in statements where the order of execution is undefined. Basically, this mean: use one generic stack macro at a time for a given stack.
To install MarpaX::ESLIF, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MarpaX::ESLIF
CPAN shell
perl -MCPAN -e shell install MarpaX::ESLIF
For more information on module installation, please visit the detailed CPAN module installation guide.