DQUEUE(3)

NAME
dqueue - procedures for managing double-ended queues in libmagicutils.a

SYNOPSIS
#include magic.h
#include malloc.h
#include dqueue.h

DQInit(q, capacity)
DQueue *q;
int capacity;

DQFree(q)
DQueue *q;

DQPushFront(q, elem)
DQueue *q;
ClientData elem;

DQPushRear(q, elem)
DQueue *q;
ClientData elem;

ClientData DQPopFront(q)
DQueue *q;

ClientData DQPopRear(q)
DQueue *q;

DQChangeSize(q, newSize)
DQueue *q;
int newSize

DQCopy(dst, src)
DQueue *dst;
DQueue *src;

bool DQIsEmpty(q)
DQueue *q;

DESCRIPTION
These procedures manipulate double-ended queues. A double-ended queue (DQueue) is a structure to which single word elements of type ClientData (actually type (char *), but intended to mean ``any one-word type at all'') may be added to either end or removed from either end. Callers should not reference fields of a DQueue directly, but rather should use the following procedures:

DQInit initializes the DQueue q to have sufficient capacity to hold capacity entries at first. If more than this many entries are pushed on the queue, it automatically doubles its size (at the cost of copying, however), so capacity should be treated as the expected number of entries on the queue rather than the maximum number. DQFree frees the storage allocated by DQinit for the DQueue q.

DQPushFront and DQPushRear each place a new entry elem on the queue q; DQPushFront places it on the front of the queue, while DQPushRear places it on the rear. If the current maximum size of the queue would be exceeded by either operation, twice as much space is allocated automatically and the existing queue contents are copied to the bigger area. DQPopFront and DQPopRear remove an element from respectively the front or rear of the DQueue q and return it. If no elements are left, they return NULL (zero).

Although DQPushFront and DQPushRear take care of increasing the space for a queue automatically, sometimes it is desirable to change the size of a queue explicitly. This can be done with DQChangeSize, which changes the size of the DQueue q to newSize, as long as newSize is at least as great as the number of entries already in the queue. If there are more than newSize entries in the queue, nothing happens.

One DQueue may be copied to another by DQCopy, which copies the DQueue src to the DQueue dst.

Finally, to check whether a queue q is empty, one may call DQIsEmpty, which returns TRUE (non-zero) if the queue is empty, or FALSE (zero) if it contains any elements.

BUGS
Using NULL to indicate end-of-queue in DQPopFront and DQPopRear is of marginal usefulness. Callers should stick to using DQIsEmpty unless they are certain not to have pushed any zero elements on the queue.

SEE ALSO
magicutils(3)