Documentation for package rsm.queue

Author : R. Scott McIntire

Version: 1.1

Overview:

This package provides the usual queuing functions.

Export Summary:

append-queue : Create a new queue which concatenates queues.
nappend-queue: Similar to nconc, but for queues.
create       : Create a new queue.
do-queue     : Control structure for queue: Like dolist but for queues. 
               Each element is formed by dequeuing a copy of the original queue.
do-nqueue    : Control structure for queue: Like dolist but for queues. 
               Each element is formed by dequeuing the original queue. 
               This function is destructive.
empty-p      : Is this queue empty?
enqueue      : Enqueue an element onto a queue.
dequeue      : Dequeue a queue (returning the dequeued element).
get-first    : Get the first element of the queue. The next element to be
               dequeued.
get-last     : Get the last element of the queue. The last element to be 
               dequeued.
nget-list    : Get the list of the queue. Does NOT make a copy.
list->queue  : Returns a copy of a list as a queue.
queue        : A type for queues.
queue-p      : Returns true if argument is a queue.
queue->list  : Returns a copy of the list of the queue.
nsort-queue  : Sort a queue in place.
sort-queue   : Sort a copy of a queue.

append-queue (&rest queues)

Create a new queue which appends the other queues. The original queues are
not changed.

copy-queue (que)

Copy a queue.

create (&optional obj)

Create a queue. If <obj> is non nil queue it up. In order to create a queue
with nil as the first element, call queue with no arguments and then call
enqueue with nil as the value to queue.

dequeue (queue)

Dequeue an object. Return the object queued.

do-nqueue ((var que &optional result) &body body)

Loop construct for queues that sets <var> to the successive values of the
queue, <que>, (by dequeuing) and then evaluates <body>. If the symbol <result> 
is supplied, its value is returned when the iteration is finished.
Example: (rsm.queue:do-nqueue (item que) (format t "queue item = ~s~%" item))  
This drains the queue, <que>, printing each of the elements of the queue.  
Note:  This is a destructive function. If <body> mutates <que>, this 
construct could go into an infinite loop.

do-queue ((var que &optional result) &body body)

Loop construct for queues that sets <var> to the successive values of a copy
of the queue, <que>, (by dequeuing) and then evaluates <body>. If the symbol 
<result> is supplied, its value is returned when the iteration is finished.
Example: (rsm.queue:do-queue (item que) (format t "queue item = ~s~%" item))  
This drains a copy of the queue, <que>, printing each of the elements 
of the queue.

empty-p (queue)

Is the queue empty?

enqueue (obj queue)

Enqueue an object. Return the queue.

get-first (queue)

Get the next element the queue would dequeue. Does not affect the queue.

get-last (queue)

Get the last element the queue would dequeue. Does not affect the queue.

list->queue (list)

Return a copy of the list as a queue.

nappend-queue (&rest queues)

Append (destructively (like nconc) the queues <queues> essentially by
nconsing the internal list of the first nonempty queue with the lists from the
rest of the non empty queues.  
Note:  After this operation, do not use the other queues.

nget-list (queue)

Get the internal list of queue, <queue>. The integrity of the queue cannot be
guaranteed if this list is destructively modified.

nsort-queue (queue sort-func)

Sort a queue, <queue>, in place using sort function <sort-func>.

queue->list (que)

Return a copy of the queue as a list, from 'first in' to 'last in'.

queue-p (que)

Returns true if <que> is a queue.

sort-queue (queue sort-func)

Sort a copy of queue, <queue>, using sort function <sort-func>.