A Stack and Queue Library

A short overview of the stack & queue library contained in jlib.lib - created by John Findlay

library version 1.00

Introduction:

The stack library functionality is similar to the way the hardware stack operates, the last item put onto the stack will be the first item taken off. LIFO (last in first out) The queue library works as a FIFO (first in first out) queue. For both the stack & queue libraries one creates a separate stack or queue for each of the standard types. There are 'long', 'long long', 'float', double, long double, double _Complex and pointer stacks and queues, each of which is created with a call to initialise that particular type.

For instance, one would call LStackInit( var, 10 ) to create a stack capable for holding 10 'long's. The var is a struct of type LSTACK defined in stack.h. Likewise one would call LQueueInit( var, 29 ) to create a queue capable of holding 29 longs in the queue and var is a struct of type LQUEUE. All structures are passed by reference for efficiency reasons. Here is an example or initialising a stack for long's:

DSTACK d;
DStackInit( d, 100 );

The above will initialise a stack that will hold 100 doubles.

Here is a list of types:

Stacks Queues Type
LSTACK LQUEUE long
LLSTACK LLQUEUE long long
FSTACK FQUEUE float
DSTACK DQUEUE double
LDSTACK LDQUEUE long double
DCSTACK DCQUEUE double _Complex
PSTACK PQUEUE generic pointer

Apart from the init function call (i.e. LStackInit) all other calls are attached to members of the structure. So calling the function to 'push' a long onto the stack looks like this:

LSTACK l;
LStackInit( l, 100 );
l.lpush( l, 12345 );

And pop

long var = l.lpop( l );

The stack member function calls for dealing with longs are named thus:

lpush Pushes a long onto the stack
lpop Pops a long off the stack
lpurge Purges the stack so it will be as when newly created.
lisempty Returns true is stack is empty
lisfull Returns true is stack is full
lnumitem Returns the number of items on the stack
ldelete Deletes the stack

Note the prefix 'l' for long. All other types follow the same method. So to push a double one uses dpush, to push a float one uses fpush and so on.

The queue member function calls for dealing with longs are named thus:

lput Pushes a long onto the queue
lget Pops a long off the queue
lclear Clears the queue so it will be as when newly created.
lisqempty Returns true is queue is empty
lisqfull Returns true is queue is full
litems Returns the number of items on the queue
lerase Deletes the queue

All other types follow the same method. So to 'put' a double one uses 'dput', to put a float one uses fput and so on. Attempting to 'pop' or 'get' when the stack or queue is empty is of course not of any value, the returned value will not be meaningful. Attempting to 'push' or 'put' to the stack or queue when full results in nothing being added. Use isempty/isqempty and isfull/isqfull to determine those conditions. Please take a look at the example listings Stacktest.c and Queuetest.c for further enlightenment. Remember to link with jlib.lib.


Two other functions are supplied to identify the library versions.

void stack_libvers(void) and void queue_libvers(void)

Both these functions display the version number of their respective libraries.