Source

roul / docs / usage.markdown

Usage

Roul currently contains a few functions in one namespace. It'll expand in the future, but for now that's all it is.

roul.random

The roul.random namespace contains wrappers around some of Clojure's built-in random functions to make them more user friendly, as well as some uniqe functions of its own.

The recommended way is to require this namespace into your own instead of overwriting Clojure's builtins:

(ns foo.core
  (:require [roul.random :as rr]))

; or

(require '[roul.random :as rr])

rand

(rand)           ; return a float in [0, 1)
(rand end)       ; return a float in [0, end)
(rand start end) ; return a float in [start, end)

A wrapper around the built-in rand. Returns a random floating point number between start (inclusive) and end (exclusive).

If not given, start defaults to 0 and end defaults to 1.

rand-int

(rand-int end)       ; return an int in [0, end)
(rand-int start end) ; return an int in [start, end)

A wrapper around the built-in rand-int. Returns a random integer between start (inclusive) and end (exclusive).

If not given, start defaults to 0.

rand-nth

(rand-nth coll) ; return a random element of coll

A wrapper around the built-in rand-nth. Returns a random element of the given collection.

This is a transparent wrapper around the builtin, included only for completeness. Unlike the other wrappers no new functionality has been added (yet).

rand-nth-weighted

(rand-nth-weighted coll) ; return a random element of coll

Returns a random element of a weighted collection.

A weighted collection can be any seq of [choice, weight] elements. The weights can be arbitrary numbers -- they do not need to add up to anything specific.

; Returns coffee roughly 80% of the time, tea 15%, and soda 5%.
(rr/rand-nth-weighted {:coffee 0.80, :tea 0.15, :soda 0.05})

; Returns cats roughly twice as often as boots.
(rr/rand-nth-weighted [[:boots 14]
                       [:cats 28]])

rand-bool

(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

(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.

; 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

(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.

; 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)]
  ...)