From 6ab4085db36e6708ddc3fbcea65ff1b5b875db6f Mon Sep 17 00:00:00 2001
From: Danny Yoo <dyoo@hashcollision.org>
Date: Sat, 3 Nov 2012 15:36:11 -0600
Subject: [PATCH] documentation: adding data/heap examples

---
 collects/data/scribblings/heap.scrbl | 83 +++++++++++++++++++++++++++-
 1 file changed, 82 insertions(+), 1 deletion(-)

diff --git a/collects/data/scribblings/heap.scrbl b/collects/data/scribblings/heap.scrbl
index 0862ebe591..7bffe723cf 100644
--- a/collects/data/scribblings/heap.scrbl
+++ b/collects/data/scribblings/heap.scrbl
@@ -19,64 +19,145 @@ Binary heaps are a simple implementation of priority queues.
          heap?]{
 
 Makes a new empty heap using @racket[<=?] to order elements.
+
+@examples[#:eval the-eval
+(define a-heap-of-strings (make-heap string<=?))
+a-heap-of-strings
+@code:comment{With structs:}
+(struct node (name val))
+(define (node<=? x y)
+  (<= (node-val x) (node-val y)))
+(define a-heap-of-nodes (make-heap node<=?))
+a-heap-of-nodes]
 }
 
 @defproc[(heap? [x any/c]) boolean?]{
 
 Returns @racket[#t] if @racket[x] is a heap, @racket[#f] otherwise.
+
+@examples[#:eval the-eval
+(heap? (make-heap <=))
+(heap? "I am not a heap")]
 }
 
 @defproc[(heap-count [h heap?]) exact-nonnegative-integer?]{
 
 Returns the number of elements in the heap.
+@examples[#:eval the-eval
+(define a-heap (make-heap <=))
+(heap-add-all! a-heap '(7 3 9 1 13 21 15 31))
+(heap-count a-heap)
+]
 }
 
 @defproc[(heap-add! [h heap?] [v any/c] ...) void?]{
 
 Adds each @racket[v] to the heap.
+
+@examples[#:eval the-eval
+(define a-heap (make-heap <=))
+(heap-add! a-heap 2009 1009)]
 }
 
+
 @defproc[(heap-add-all! [h heap?] [v (or/c list? vector? heap?)]) void?]{
 
 Adds each element contained in @racket[v] to the heap, leaving
 @racket[v] unchanged.
+
+@examples[#:eval the-eval
+(define heap-1 (make-heap <=))
+(define heap-2 (make-heap <=))
+(define heap-12 (make-heap <=))
+(heap-add-all! heap-1 '(3 1 4 1 5 9 2 6))
+(heap-add-all! heap-2 #(2 7 1 8 2 8 1 8))
+(heap-add-all! heap-12 heap-1)
+(heap-add-all! heap-12 heap-2)
+(heap-count heap-12)]
 }
 
 @defproc[(heap-min [h heap?]) any/c]{
 
 Returns the least element in the heap @racket[h], according to the
 heap's ordering. If the heap is empty, an exception is raised.
+
+@examples[#:eval the-eval
+(define a-heap (make-heap string<=?))
+(heap-add! a-heap "sneezy" "sleepy" "dopey" "doc"
+            "happy" "bashful" "grumpy")
+(heap-min a-heap)
+
+@code:comment{Taking the min of the empty heap is an error:}
+(heap-min (make-heap <=))
+]
 }
 
 @defproc[(heap-remove-min! [h heap?]) void?]{
 
 Removes the least element in the heap @racket[h]. If the heap is
 empty, an exception is raised.
+
+@examples[#:eval the-eval
+(define a-heap (make-heap string<=?))
+(heap-add! a-heap "fili" "fili" "oin" "gloin" "thorin"
+                  "dwalin" "balin" "bifur" "bofur"
+                  "bombur" "dori" "nori" "ori")
+(heap-min a-heap)
+(heap-remove-min! a-heap)
+(heap-min a-heap)]
 }
 
 @defproc[(vector->heap [<=? (-> any/c any/c any/c)] [items vector?]) heap?]{
 
 Builds a heap with the elements from @racket[items]. The vector is not
 modified.
+@examples[#:eval the-eval
+(struct item (val frequency))
+(define (item<=? x y)
+  (<= (item-frequency x) (item-frequency y)))
+(define some-sample-items 
+  (vector (item #\a 17) (item #\b 12) (item #\c 19)))
+(define a-heap (vector->heap item<=? some-sample-items))
+]
 }
 
 @defproc[(heap->vector [h heap?]) vector?]{
 
 Returns a vector containing the elements of heap @racket[h] in the
 heap's order. The heap is not modified.
+
+@examples[#:eval the-eval
+(define word-heap (make-heap string<=?))
+(heap-add! word-heap "pile" "mound" "agglomerate" "cumulation")
+(heap->vector word-heap)
+]
 }
 
 @defproc[(heap-copy [h heap?]) heap?]{
 
 Makes a copy of heap @racket[h].
+
+(define word-heap (make-heap string<=?))
+(heap-add! word-heap "pile" "mound" "agglomerate" "cumulation")
+(define a-copy (heap-copy word-heap))
+(heap-remove-min! a-copy)
+(heap-count word-heap)
+(heap-count a-copy)
+]
 }
 
 
 @;{--------}
 
-@defproc[(heap-sort! [<=? (-> any/c any/c any/c)] [v vector?]) void?]{
+@defproc[(heap-sort! [<=? (-> any/c any/c any/c)] [v (and/c vector? (not/c immutable?))]) void?]{
 
 Sorts vector @racket[v] using the comparison function @racket[<=?].
+
+@examples[#:eval the-eval
+(define terms (vector "batch" "deal" "flock" "good deal" "hatful" "lot"))
+(heap-sort! string<=? terms)
+terms
+]
 }