summaryrefslogtreecommitdiffstats
path: root/queue.scm
diff options
context:
space:
mode:
Diffstat (limited to 'queue.scm')
-rw-r--r--queue.scm77
1 files changed, 57 insertions, 20 deletions
diff --git a/queue.scm b/queue.scm
index 89a65b0..820894f 100644
--- a/queue.scm
+++ b/queue.scm
@@ -1,21 +1,33 @@
-; "queue.scm" Queues/Stacks for Scheme
-; Written by Andrew Wilcox (awilcox@astro.psu.edu) on April 1, 1992.
-;
-; This code is in the public domain.
+;; "queue.scm" Queues/Stacks for Scheme
+;; Written by Andrew Wilcox (awilcox@astro.psu.edu) on April 1, 1992.
+;;
+;; This code is in the public domain.
(require 'record)
-; Elements in a queue are stored in a list. The last pair in the list
-; is stored in the queue type so that datums can be added in constant
-; time.
+;;@code{(require 'queue)}
+;;@ftindex queue
+;;
+;;A @dfn{queue} is a list where elements can be added to both the front
+;;and rear, and removed from the front (i.e., they are what are often
+;;called @dfn{dequeues}). A queue may also be used like a stack.
+
+;; Elements in a queue are stored in a list. The last pair in the list
+;; is stored in the queue type so that datums can be added in constant
+;; time.
(define queue:record-type
(make-record-type "queue" '(first-pair last-pair)))
+
+;;@args
+;;Returns a new, empty queue.
(define make-queue
(let ((construct-queue (record-constructor queue:record-type)))
(lambda ()
(construct-queue '() '()))))
+;;@args obj
+;;Returns @code{#t} if @var{obj} is a queue.
(define queue? (record-predicate queue:record-type))
(define queue:first-pair (record-accessor queue:record-type
@@ -27,21 +39,13 @@
(define queue:set-last-pair! (record-modifier queue:record-type
'last-pair))
+;;@body
+;;Returns @code{#t} if the queue @var{q} is empty.
(define (queue-empty? q)
(null? (queue:first-pair q)))
-(define (queue-front q)
- (let ((first-pair (queue:first-pair q)))
- (if (null? first-pair)
- (slib:error "queue is empty" q))
- (car first-pair)))
-
-(define (queue-rear q)
- (let ((last-pair (queue:last-pair q)))
- (if (null? last-pair)
- (slib:error "queue is empty" q))
- (car last-pair)))
-
+;;@body
+;;Adds @var{datum} to the front of queue @var{q}.
(define (queue-push! q datum)
(let* ((old-first-pair (queue:first-pair q))
(new-first-pair (cons datum old-first-pair)))
@@ -50,6 +54,8 @@
(queue:set-last-pair! q new-first-pair)))
q)
+;;@body
+;;Adds @var{datum} to the rear of queue @var{q}.
(define (enqueue! q datum)
(let ((new-pair (cons datum '())))
(cond ((null? (queue:first-pair q))
@@ -59,6 +65,11 @@
(queue:set-last-pair! q new-pair))
q)
+;;@body
+;;@deffnx {Procedure} queue-pop! q
+;;Both of these procedures remove and return the datum at the front of
+;;the queue. @code{queue-pop!} is used to suggest that the queue is
+;;being used like a stack.
(define (dequeue! q)
(let ((first-pair (queue:first-pair q)))
(if (null? first-pair)
@@ -68,5 +79,31 @@
(if (null? first-cdr)
(queue:set-last-pair! q '()))
(car first-pair))))
-
(define queue-pop! dequeue!)
+
+;;@ All of the following functions raise an error if the queue @var{q}
+;;is empty.
+
+;;@body
+;;Removes and returns (the list) of all contents of queue @var{q}.
+(define (dequeue-all! q)
+ (let ((lst (queue:first-pair q)))
+ (queue:set-first-pair! q '())
+ (queue:set-last-pair! q '())
+ lst))
+
+;;@body
+;;Returns the datum at the front of the queue @var{q}.
+(define (queue-front q)
+ (let ((first-pair (queue:first-pair q)))
+ (if (null? first-pair)
+ (slib:error "queue is empty" q))
+ (car first-pair)))
+
+;;@body
+;;Returns the datum at the rear of the queue @var{q}.
+(define (queue-rear q)
+ (let ((last-pair (queue:last-pair q)))
+ (if (null? last-pair)
+ (slib:error "queue is empty" q))
+ (car last-pair)))