3967e218bd90

--- a/docs/usage.markdown	Sat Apr 07 17:33:13 2012 -0400
+++ b/docs/usage.markdown	Thu Nov 08 12:50:43 2012 -0500
@@ -77,3 +77,70 @@
     ; Returns cats roughly twice as often as boots.
     (rr/rand-nth-weighted [[:boots 14]
                            [:cats 28]])
+
+### rand-bool
+
+    :::clojure
+    (rand-bool)         ; return true or false
+    (rand-bool percent) ; return true the given percent of the time, false the rest
+
+Returns `true` or `false` randomly.
+
+`percent` can be an integer or a float like `20` or `39.2`.  If given, `true`
+will be returned that percent of the time (and `false` the rest).
+
+If percent is not given it defaults to `50` (an equal chance for `true` and
+`false`).
+
+### rand-gaussian
+
+    :::clojure
+    (rand-gaussian)
+    (rand-gaussian mean standard-deviation)
+    (rand-gaussian mean standard-deviation upper-bound lower-bound)
+
+Return a random float taken from a Gaussian distribution with the given mean and
+standard deviation.
+
+`mean` defaults to 0.
+
+`standard-deviation` defaults to 1.
+
+A lower and upper bound can be specified if desired, which will clamp the output
+of this function to those bounds.  Note that this clamping does NOT adjust the
+distribution, so if you clamp too tightly you'll get a disproportionate number
+of the boundary values.  It's just here to give you a way to prevent garbage
+values.
+
+    :::clojure
+    ; Generate an [x, y] pair with Gaussian-distributed values.
+    ; The x value here is clamped between 0 and graph-width.
+    (let [x (rand-gaussian 100 20 0 graph-width)
+          y (rand-gaussian 200 40)]
+      ...)
+### rand-gaussian-int
+
+    :::clojure
+    (rand-gaussian)
+    (rand-gaussian mean standard-deviation)
+    (rand-gaussian mean standard-deviation upper-bound lower-bound)
+
+Return a random int taken from a Gaussian distribution with the given mean and
+standard deviation.
+
+`mean` defaults to 0.
+
+`standard-deviation` defaults to 1.
+
+A lower and upper bound can be specified if desired, which will clamp the output
+of this function to those bounds.  Note that this clamping does NOT adjust the
+distribution, so if you clamp too tightly you'll get a disproportionate number
+of the boundary values.  It's just here to give you a way to prevent garbage
+values.
+
+    :::clojure
+    ; Generate an [x, y] pair with Gaussian-distributed values.
+    ; The x value here is clamped between 0 and graph-width.
+    (let [x (rand-gaussian 100 20 0 graph-width)
+          y (rand-gaussian 200 40)]
+      ...)

--- a/src/roul/random.clj	Sat Apr 07 17:33:13 2012 -0400
+++ b/src/roul/random.clj	Thu Nov 08 12:50:43 2012 -0500
@@ -1,12 +1,16 @@
 (ns roul.random
   (:refer-clojure :exclude [rand-int rand rand-nth]))
+ 
 
+(def generator (java.util.Random.))
 
 (defn rand
   "Return a random float between start (inclusive) and end (exclusive).
 
   start defaults to 0
-  end defaults to 1"
+  end defaults to 1
+
+  "
   ([] (clojure.core/rand))
   ([end] (clojure.core/rand end))
   ([start end] (+ start (clojure.core/rand (- end start)))))
@@ -14,13 +18,18 @@
 (defn rand-int
   "Return a random int between start (inclusive) and end (exclusive).
 
-  start defaults to 0"
+  start defaults to 0
+
+  "
   ([end] (clojure.core/rand-int end))
   ([start end] (+ start (clojure.core/rand-int (- end start)))))
 
 (defn rand-nth
-  "Return a random element of the collection.  Delegates to the built-in
-  rand-nth for now."
+  "Return a random element of the collection.
+
+  Delegates to the built-in rand-nth for now.
+
+  "
   [coll]
   (clojure.core/rand-nth coll))
 
@@ -34,7 +43,9 @@
   Examples:
 
   (rand-nth-weighted [[:a 0.50] [:b 0.20] [:c 0.30]])
-  (rand-nth-weighted {:a 10 :b 200})"
+  (rand-nth-weighted {:a 10 :b 200})
+
+  "
   [coll]
   (let [total (reduce + (map second coll))]
     (loop [i (rand total)
@@ -43,3 +54,66 @@
         choice
         (recur (- i weight) remaining)))))
 
+(defn rand-bool
+  "Return true or false with a percent chance of being true.
+
+  percent defaults to 50.0
+
+  "
+  ([]
+   (rand-bool 50.0))
+  ([percent]
+   (< (rand 100) percent)))
+
+(defn rand-gaussian
+  "Return a random float.
+
+  Floats are generated from a Gaussian distribution with the given mean and
+  standard deviation.
+
+  A lower and upper bound can be specified if desired, which will clamp the
+  output of this function to those bounds.  Note that this clamping does NOT
+  adjust the distribution, so if you clamp too tightly you'll get
+  a disproportionate number of the boundary values.  It's just here to give you
+  a way to prevent garbage values.
+
+  mean defaults to 0.
+  standard-deviation defaults to 1.
+
+  "
+  ([]
+   (.nextGaussian generator))
+  ([mean standard-deviation]
+   (-> (rand-gaussian)
+     (* standard-deviation)
+     (+ mean)))
+  ([mean standard-deviation lower-bound upper-bound]
+   (-> (rand-gaussian mean standard-deviation)
+     (max lower-bound)
+     (min upper-bound))))
+
+(defn rand-gaussian-int
+  "Return a random integer.
+
+  Integers are generated from a Gaussian distribution with the given mean and
+  standard deviation.
+
+  A lower and upper bound can be specified if desired, which will clamp the
+  output of this function to those bounds.  Note that this clamping does NOT
+  adjust the distribution, so if you clamp too tightly you'll get
+  a disproportionate number of the boundary values.  It's just here to give you
+  a way to prevent garbage values.
+
+  mean defaults to 0.
+  standard-deviation defaults to 1.
+
+  "
+  ([]
+   (int (rand-gaussian)))
+  ([mean standard-deviation]
+   (int (rand-gaussian mean standard-deviation)))
+  ([mean standard-deviation lower-bound upper-bound]
+   (-> (rand-gaussian-int mean standard-deviation)
+     (max lower-bound)
+     (min upper-bound))))
+