Source

sjl.bitbucket.org / roul / usage / index.html

<html><head><title>Usage / Roul</title><link rel="stylesheet" href="../_dmedia/bootstrap.css"/><link rel="stylesheet" href="../_dmedia/tango.css"/><link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less"/><script src="../_dmedia/less.js" type="text/javascript">
        </script></head><body class="content">
        <div class="wrap">
            <header><h1><a href="..">Roul</a></h1></header><div class="markdown">
<h1 id="usage"><a href="">Usage</a></h1><p>Roul currently contains a few functions in one namespace.  It'll expand in the
future, but for now that's all it is.</p>
<div class="toc">
<ul><li><a href="#roulrandom">roul.random</a><ul><li><a href="#rand">rand</a></li>
<li><a href="#rand-int">rand-int</a></li>
<li><a href="#rand-nth">rand-nth</a></li>
<li><a href="#rand-nth-weighted">rand-nth-weighted</a></li>
<li><a href="#rand-bool">rand-bool</a></li>
<li><a href="#rand-gaussian">rand-gaussian</a></li>
<li><a href="#rand-gaussian-int">rand-gaussian-int</a></li>
</ul></li>
</ul></div>
<h2 id="roulrandom">roul.random</h2>
<p>The <code>roul.random</code> 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.</p>
<p>The recommended way is to <code>require</code> this namespace into your own instead of
overwriting Clojure's builtins:</p>
<div class="codehilite"><pre><span class="p">(</span><span class="kd">ns </span><span class="nv">foo.core</span>
  <span class="p">(</span><span class="ss">:require</span> <span class="p">[</span><span class="nv">roul.random</span> <span class="ss">:as</span> <span class="nv">rr</span><span class="p">]))</span>

<span class="c1">; or</span>

<span class="p">(</span><span class="nf">require</span> <span class="o">'</span><span class="p">[</span><span class="nv">roul.random</span> <span class="ss">:as</span> <span class="nv">rr</span><span class="p">])</span>
</pre></div>


<h3 id="rand">rand</h3>
<div class="codehilite"><pre><span class="p">(</span><span class="nf">rand</span><span class="p">)</span>           <span class="c1">; return a float in [0, 1)</span>
<span class="p">(</span><span class="nb">rand </span><span class="nv">end</span><span class="p">)</span>       <span class="c1">; return a float in [0, end)</span>
<span class="p">(</span><span class="nb">rand </span><span class="nv">start</span> <span class="nv">end</span><span class="p">)</span> <span class="c1">; return a float in [start, end)</span>
</pre></div>


<p>A wrapper around the built-in <code>rand</code>.  Returns a random floating point number
between <code>start</code> (inclusive) and <code>end</code> (exclusive).</p>
<p>If not given, <code>start</code> defaults to <code>0</code> and <code>end</code> defaults to <code>1</code>.</p>
<h3 id="rand-int">rand-int</h3>
<div class="codehilite"><pre><span class="p">(</span><span class="nb">rand-int </span><span class="nv">end</span><span class="p">)</span>       <span class="c1">; return an int in [0, end)</span>
<span class="p">(</span><span class="nb">rand-int </span><span class="nv">start</span> <span class="nv">end</span><span class="p">)</span> <span class="c1">; return an int in [start, end)</span>
</pre></div>


<p>A wrapper around the built-in <code>rand-int</code>.  Returns a random integer between
<code>start</code> (inclusive) and <code>end</code> (exclusive).</p>
<p>If not given, <code>start</code> defaults to <code>0</code>.</p>
<h3 id="rand-nth">rand-nth</h3>
<div class="codehilite"><pre><span class="p">(</span><span class="nf">rand-nth</span> <span class="nv">coll</span><span class="p">)</span> <span class="c1">; return a random element of coll</span>
</pre></div>


<p>A wrapper around the built-in <code>rand-nth</code>.  Returns a random element of the given
collection.</p>
<p>This is a transparent wrapper around the builtin, included only for
completeness.  Unlike the other wrappers no new functionality has been added
(yet).</p>
<h3 id="rand-nth-weighted">rand-nth-weighted</h3>
<div class="codehilite"><pre><span class="p">(</span><span class="nf">rand-nth-weighted</span> <span class="nv">coll</span><span class="p">)</span> <span class="c1">; return a random element of coll</span>
</pre></div>


<p>Returns a random element of a weighted collection.</p>
<p>A weighted collection can be any seq of <code>[choice, weight]</code> elements.  The
weights can be arbitrary numbers -- they do not need to add up to anything
specific.</p>
<div class="codehilite"><pre><span class="c1">; Returns coffee roughly 80% of the time, tea 15%, and soda 5%.</span>
<span class="p">(</span><span class="nf">rr/rand-nth-weighted</span> <span class="p">{</span><span class="ss">:coffee</span> <span class="mf">0.80</span>, <span class="ss">:tea</span> <span class="mf">0.15</span>, <span class="ss">:soda</span> <span class="mf">0.05</span><span class="p">})</span>

<span class="c1">; Returns cats roughly twice as often as boots.</span>
<span class="p">(</span><span class="nf">rr/rand-nth-weighted</span> <span class="p">[[</span><span class="ss">:boots</span> <span class="mi">14</span><span class="p">]</span>
                       <span class="p">[</span><span class="ss">:cats</span> <span class="mi">28</span><span class="p">]])</span>
</pre></div>


<h3 id="rand-bool">rand-bool</h3>
<div class="codehilite"><pre><span class="p">(</span><span class="nf">rand-bool</span><span class="p">)</span>         <span class="c1">; return true or false</span>
<span class="p">(</span><span class="nf">rand-bool</span> <span class="nv">percent</span><span class="p">)</span> <span class="c1">; return true the given percent of the time, false the rest</span>
</pre></div>


<p>Returns <code>true</code> or <code>false</code> randomly.</p>
<p><code>percent</code> can be an integer or a float like <code>20</code> or <code>39.2</code>.  If given, <code>true</code>
will be returned that percent of the time (and <code>false</code> the rest).</p>
<p>If percent is not given it defaults to <code>50</code> (an equal chance for <code>true</code> and
<code>false</code>).</p>
<h3 id="rand-gaussian">rand-gaussian</h3>
<div class="codehilite"><pre><span class="p">(</span><span class="nf">rand-gaussian</span><span class="p">)</span>
<span class="p">(</span><span class="nf">rand-gaussian</span> <span class="nv">mean</span> <span class="nv">standard-deviation</span><span class="p">)</span>
<span class="p">(</span><span class="nf">rand-gaussian</span> <span class="nv">mean</span> <span class="nv">standard-deviation</span> <span class="nv">upper-bound</span> <span class="nv">lower-bound</span><span class="p">)</span>
</pre></div>


<p>Return a random float taken from a Gaussian distribution with the given mean and
standard deviation.</p>
<p><code>mean</code> defaults to 0.</p>
<p><code>standard-deviation</code> defaults to 1.</p>
<p>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.</p>
<div class="codehilite"><pre><span class="c1">; Generate an [x, y] pair with Gaussian-distributed values.</span>
<span class="c1">; The x value here is clamped between 0 and graph-width.</span>
<span class="p">(</span><span class="k">let </span><span class="p">[</span><span class="nv">x</span> <span class="p">(</span><span class="nf">rand-gaussian</span> <span class="mi">100</span> <span class="mi">20</span> <span class="mi">0</span> <span class="nv">graph-width</span><span class="p">)</span>
      <span class="nv">y</span> <span class="p">(</span><span class="nf">rand-gaussian</span> <span class="mi">200</span> <span class="mi">40</span><span class="p">)]</span>
  <span class="nv">...</span><span class="p">)</span>
</pre></div>


<h3 id="rand-gaussian-int">rand-gaussian-int</h3>
<div class="codehilite"><pre><span class="p">(</span><span class="nf">rand-gaussian</span><span class="p">)</span>
<span class="p">(</span><span class="nf">rand-gaussian</span> <span class="nv">mean</span> <span class="nv">standard-deviation</span><span class="p">)</span>
<span class="p">(</span><span class="nf">rand-gaussian</span> <span class="nv">mean</span> <span class="nv">standard-deviation</span> <span class="nv">upper-bound</span> <span class="nv">lower-bound</span><span class="p">)</span>
</pre></div>


<p>Return a random int taken from a Gaussian distribution with the given mean and
standard deviation.</p>
<p><code>mean</code> defaults to 0.</p>
<p><code>standard-deviation</code> defaults to 1.</p>
<p>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.</p>
<div class="codehilite"><pre><span class="c1">; Generate an [x, y] pair with Gaussian-distributed values.</span>
<span class="c1">; The x value here is clamped between 0 and graph-width.</span>
<span class="p">(</span><span class="k">let </span><span class="p">[</span><span class="nv">x</span> <span class="p">(</span><span class="nf">rand-gaussian</span> <span class="mi">100</span> <span class="mi">20</span> <span class="mi">0</span> <span class="nv">graph-width</span><span class="p">)</span>
      <span class="nv">y</span> <span class="p">(</span><span class="nf">rand-gaussian</span> <span class="mi">200</span> <span class="mi">40</span><span class="p">)]</span>
  <span class="nv">...</span><span class="p">)</span>
</pre></div>
                </div>
            <footer><p>Created by <a href="http://stevelosh.com">Steve Losh</a>.
Docs made with <a href="http://sjl.bitbucket.org/d/">d</a>.</p>
<p><br/><a id="rochester-made" href="http://rochestermade.com" title="Rochester Made"><img src="http://rochestermade.com/media/images/rochester-made-dark-on-light.png" alt="Rochester Made" title="Rochester Made"/></a></p>
<script type="text/javascript">
  var _gauges = _gauges || [];
  (function() {
    var t   = document.createElement('script');
    t.type  = 'text/javascript';
    t.async = true;
    t.id    = 'gauges-tracker';
    t.setAttribute('data-site-id', '4f80ace2f5a1f538860000c2');
    t.src = '//secure.gaug.es/track.js';
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(t, s);
  })();
</script></footer></div>
    </body></html>