From 5c1bd77b9e92f29dfb3271f37a0b86ddfddc65fb Mon Sep 17 00:00:00 2001
From: Eli Barzilay <eli@barzilay.org>
Date: Fri, 12 Nov 2010 16:43:33 -0500
Subject: [PATCH] Add `shuffle' to `racket/list'.

---
 collects/racket/list.rkt                   |  5 ++++-
 collects/scribblings/reference/pairs.scrbl | 10 ++++++++++
 collects/tests/racket/list.rktl            |  8 ++++++++
 3 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/collects/racket/list.rkt b/collects/racket/list.rkt
index 657bec147f..50b7155986 100644
--- a/collects/racket/list.rkt
+++ b/collects/racket/list.rkt
@@ -30,7 +30,8 @@
 
          ;; convenience
          append-map
-         filter-not)
+         filter-not
+         shuffle)
 
 (define (first x)
   (if (and (pair? x) (list? x))
@@ -327,6 +328,8 @@
       (reverse result)
       (loop (cdr l) (if (f (car l)) result (cons (car l) result))))))
 
+(define (shuffle l)
+  (sort l < #:key (lambda (_) (random)) #:cache-keys? #t))
 
 ;; mk-min : (number number -> boolean) symbol (X -> real) (listof X) -> X
 (define (mk-min cmp name f xs)
diff --git a/collects/scribblings/reference/pairs.scrbl b/collects/scribblings/reference/pairs.scrbl
index ad003860ae..74e08fa780 100644
--- a/collects/scribblings/reference/pairs.scrbl
+++ b/collects/scribblings/reference/pairs.scrbl
@@ -949,6 +949,16 @@ returns @scheme[#f].
   (filter-not even? '(1 2 3 4 5 6))
 ]}
 
+
+@defproc[(shuffle [lst list?]) list?]{
+
+Returns a list with all elements from @racket[lst], randomly shuffled.
+
+@mz-examples[#:eval list-eval
+  (shuffle '(1 2 3 4 5 6))
+]}
+
+
 @defproc[(argmin [proc (-> any/c real?)] [lst (and/c pair? list?)]) any/c]{
 
 This returns the first element in the list @scheme[lst] that minimizes
diff --git a/collects/tests/racket/list.rktl b/collects/tests/racket/list.rktl
index 23d21a62ac..c29a4c4335 100644
--- a/collects/tests/racket/list.rktl
+++ b/collects/tests/racket/list.rktl
@@ -317,6 +317,14 @@
   (test '(1 2 3) am list '(1 2 3))
   (test '(1 1 2 2 3 3) am (lambda (x) (list x x)) '(1 2 3)))
 
+;; ---------- shuffle ----------
+(let loop ([l (reverse '(1 2 4 8 16 32))])
+  (define (length+sum l) (list (length l) (apply + l)))
+  (define expected (length+sum l))
+  (for ([i (in-range 100)])
+    (test expected length+sum (shuffle l)))
+  (when (pair? l) (loop (cdr l))))
+
 ;; ---------- argmin & argmax ----------
 
 (let ()