From 42b8163f8f78eed8468de6ca9b2bb8fe675879fb Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Thu, 21 Feb 2013 08:32:52 -0700
Subject: [PATCH] fix docs on `case'

The Guide was was out-of-date in several ways, and the Reference
didn't describe the dispatch-time guarantee.
---
 collects/scribblings/guide/case.scrbl       | 17 +++++++++--------
 collects/scribblings/guide/cond.scrbl       | 10 +++++-----
 collects/scribblings/reference/syntax.scrbl |  3 +++
 doc/release-notes/racket/HISTORY.txt        |  1 +
 4 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/collects/scribblings/guide/case.scrbl b/collects/scribblings/guide/case.scrbl
index 67a6008da3..0147b6648f 100644
--- a/collects/scribblings/guide/case.scrbl
+++ b/collects/scribblings/guide/case.scrbl
@@ -8,16 +8,16 @@ The @racket[case] form dispatches to a clause by matching the result
 of an expression to the values for the clause:
 
 @specform[(case expr
-            [(datum ...+) expr ...+]
+            [(datum ...+) body ...+]
             ...)]
 
-Each @racket[_datum] will be compared to the result of the first
-@racket[_expr] using @racket[eqv?]. Since @racket[eqv?] doesn't work on
-many kinds of values, notably strings and lists, each @racket[_datum]
-is typically a number, symbol, or boolean.
+Each @racket[_datum] will be compared to the result of @racket[_expr]
+using @racket[equal?], and then the corresponding @racket[body]s are
+evaluated. The @racket[case] form can dispatch to the correct clause
+in @math{O(log N)} time for @math{N} @racket[datum]s.
 
 Multiple @racket[_datum]s can be supplied for each clause, and the
-corresponding @racket[_expr] is evaluated if any of the
+corresponding @racket[_body]s are evaluated if any of the
 @racket[_datum]s match.
 
 @examples[
@@ -41,5 +41,6 @@ like @racket[cond]:
   [else 'many])
 ]
 
-For more general pattern matching, use @racket[match], which is
-introduced in @secref["match"].
+For more general pattern matching (but without the dispatch-time
+guarantee), use @racket[match], which is introduced in
+@secref["match"].
diff --git a/collects/scribblings/guide/cond.scrbl b/collects/scribblings/guide/cond.scrbl
index 2f1afc508c..4ed5e8b4e2 100644
--- a/collects/scribblings/guide/cond.scrbl
+++ b/collects/scribblings/guide/cond.scrbl
@@ -99,13 +99,13 @@ as follows:
 
 @refalso["if"]{@racket[cond]}
 
-@specform[(cond [test-expr expr ...+]
+@specform[(cond [test-expr body ...+]
                 ...)]
 
 Each @racket[_test-expr] is evaluated in order. If it produces
-@racket[#f], the corresponding @racket[_expr]s are ignored, and
+@racket[#f], the corresponding @racket[_body]s are ignored, and
 evaluation proceeds to the next @racket[_test-expr]. As soon as a
-@racket[_test-expr] produces a true value, its @racket[_expr]s
+@racket[_test-expr] produces a true value, its @racket[_body]s
 are evaluated to produce the result for the @racket[cond] form, and no
 further @racket[_test-expr]s are evaluated.
 
@@ -142,8 +142,8 @@ The full syntax of @racket[cond] includes two more kinds of clauses:
 
 @specform/subs[#:literals (else =>)
                (cond cond-clause ...)
-               ([cond-clause [test-expr then-expr ...+]
-                             [else then-expr ...+]
+               ([cond-clause [test-expr then-body ...+]
+                             [else then-body ...+]
                              [test-expr => proc-expr]
                              [test-expr]])]
 
diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl
index 35f3ae5bd9..94c5ac5705 100644
--- a/collects/scribblings/reference/syntax.scrbl
+++ b/collects/scribblings/reference/syntax.scrbl
@@ -2153,6 +2153,9 @@ For the selected @racket[case-clause], the results of the last
 A @racket[case-clause] that starts with @racket[else] must be the last
 @racket[case-clause].
 
+The @racket[case] form can dispatch to a matching @racket[case-clause]
+in @math{O(log N)} time for @math{N} @racket[datum]s.
+
 @mz-examples[
 (case (+ 7 5)
  [(1 2 3) 'small]
diff --git a/doc/release-notes/racket/HISTORY.txt b/doc/release-notes/racket/HISTORY.txt
index fdf63b8485..0c60ac2ad8 100644
--- a/doc/release-notes/racket/HISTORY.txt
+++ b/doc/release-notes/racket/HISTORY.txt
@@ -74,6 +74,7 @@ Addded define-logger
 Changed -W, -L, PLTSTDERR, and PLTSYSLOG to support log
  filters of the form "<level> <name>=<level> ..."
 Changed log-error, etc., to support format mode
+Changed case to dispatch in logarithmic time
 Added racket/format, which is re-exported by racket
 Added #:break and #:final clauses to for forms
 Added exn:break:hang-up and exn:break:terminate, added