/usr/share/doc/libghc-dice-entropy-conduit-doc/html/System-Random-Dice.html is in libghc-dice-entropy-conduit-doc 1.0.0.1-4build7.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>System.Random.Dice</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script src="file:///usr/share/javascript/mathjax/MathJax.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_System-Random-Dice.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/System-Random-Dice.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">dice-entropy-conduit-1.0.0.1: Cryptographically secure n-sided dice via rejection sampling.</p></div><div id="content"><div id="module-header"><table class="info"><tr><th valign="top">Copyright</th><td>Peter Robinson 2014</td></tr><tr><th>License</th><td>LGPL</td></tr><tr><th>Maintainer</th><td>Peter Robinson <peter.robinson@monoid.at></td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Portability</th><td>portable</td></tr><tr><th>Safe Haskell</th><td>None</td></tr><tr><th>Language</th><td>Haskell98</td></tr></table><p class="caption">System.Random.Dice</p></div><div id="description"><p class="caption">Description</p><div class="doc"><p>This module implements an <code>n</code>-sided dice and provides sampling from a given
integer range.
The algorithm uses rejection sampling and attempts to keep the total number
of used random bits as close as possible to the information theoretic lower
bound of <code>ln(n) / ln(2)</code> (for a range of size <code>n</code>).</p><p>The implementation exposes streams of random values as conduits, see
<code><a href="System-Random-Dice.html#v:diceRolls">diceRolls</a></code> and <code><a href="System-Random-Dice.html#v:randomRs">randomRs</a></code>. We also provide IO wrappers around these
functions, see <code><a href="System-Random-Dice.html#v:getDiceRolls">getDiceRolls</a></code> and <code><a href="System-Random-Dice.html#v:getRandomRs">getRandomRs</a></code>.
The conduit interface allows us to use a specific entropy source, which has
type <code>Producer</code> <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a></code> <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Word.html#t:Word">Word</a></code>. </p><p><em>Usage:</em></p><p>If we wanted to use the system-specific entropy source (<code><a href="System-Random-Dice.html#v:systemEntropy">systemEntropy</a></code>) to
produce 10 dice rolls of a 6-sided dice (i.e. range [0,5]), we could write:</p><pre>> systemEntropy $$ diceRolls 6 =$= CL.take 10
[5,1,3,3,0,5,3,2,2,1]</pre><p>The function <code><a href="System-Random-Dice.html#v:testPerformance">testPerformance</a></code> yields the actual number of consumed random
bits:</p><pre>> testPerformance 12 10000
Generated 10000 random samples in range [0,11]
Average number of bits used: 3.5904
Entropy lower bound on the number of required bits: 3.5849625007211565
Performance ratio: 1.0015167520658164</pre></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><a href="#v:diceRolls">diceRolls</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> -> <a href="file:///usr/share/doc/libghc-conduit-doc/html/Data-Conduit.html#t:Conduit">Conduit</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Word.html#t:Word8">Word8</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a></li><li class="src short"><a href="#v:randomRs">randomRs</a> :: (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>) -> <a href="file:///usr/share/doc/libghc-conduit-doc/html/Data-Conduit.html#t:Conduit">Conduit</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Word.html#t:Word8">Word8</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a></li><li class="src short"><a href="#v:getDiceRolls">getDiceRolls</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>]</li><li class="src short"><a href="#v:getRandomRs">getRandomRs</a> :: (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>) -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>]</li><li class="src short"><a href="#v:testPerformance">testPerformance</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:systemEntropy">systemEntropy</a> :: <a href="file:///usr/share/doc/libghc-conduit-doc/html/Data-Conduit.html#t:Producer">Producer</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Word.html#t:Word8">Word8</a></li></ul></div><div id="interface"><h1>Documentation</h1><div class="top"><p class="src"><a id="v:diceRolls" class="def">diceRolls</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> -> <a href="file:///usr/share/doc/libghc-conduit-doc/html/Data-Conduit.html#t:Conduit">Conduit</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Word.html#t:Word8">Word8</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> <a href="src/System-Random-Dice-Internal.html#diceRolls" class="link">Source</a> <a href="#v:diceRolls" class="selflink">#</a></p><div class="doc"><p>Produces a stream of random integer values in the range <code>[0,n-1]</code>, for a
given <code>n <= 2^55</code>.
This conduit needs to be attached to an entropy source such as
<code><a href="System-Random-Dice.html#v:systemEntropy">systemEntropy</a></code>.</p></div></div><div class="top"><p class="src"><a id="v:randomRs" class="def">randomRs</a> <a href="src/System-Random-Dice-Internal.html#randomRs" class="link">Source</a> <a href="#v:randomRs" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>)</td><td class="doc"><p>range (inclusive)</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/libghc-conduit-doc/html/Data-Conduit.html#t:Conduit">Conduit</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Word.html#t:Word8">Word8</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a></td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Produces a stream of random integer values within a range.
This conduit needs to be attached to an entropy source such as
<code><a href="System-Random-Dice.html#v:systemEntropy">systemEntropy</a></code>.</p></div></div><div class="top"><p class="src"><a id="v:getDiceRolls" class="def">getDiceRolls</a> <a href="src/System-Random-Dice-Internal.html#getDiceRolls" class="link">Source</a> <a href="#v:getDiceRolls" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a></td><td class="doc"><p><code>n:</code> number of sides</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a></td><td class="doc"><p><code>k:</code> number of rolls</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>]</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Generates <code>k</code> rolls of an <code>n</code> sided dice.</p></div></div><div class="top"><p class="src"><a id="v:getRandomRs" class="def">getRandomRs</a> <a href="src/System-Random-Dice-Internal.html#getRandomRs" class="link">Source</a> <a href="#v:getRandomRs" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: (<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>, <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>)</td><td class="doc"><p>(inclusive) range</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a></td><td class="doc"><p>number of samples</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a>]</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Generates a list of random integer values in the specified range.</p></div></div><div class="top"><p class="src"><a id="v:testPerformance" class="def">testPerformance</a> <a href="src/System-Random-Dice-Internal.html#testPerformance" class="link">Source</a> <a href="#v:testPerformance" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a></td><td class="doc"><p>number of sides of dice</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a></td><td class="doc"><p>number of samples used for computing average.</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Compute the performance of the algorithm in terms of used random bits
versus produced random values.</p></div></div><div class="top"><p class="src"><a id="v:systemEntropy" class="def">systemEntropy</a> :: <a href="file:///usr/share/doc/libghc-conduit-doc/html/Data-Conduit.html#t:Producer">Producer</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Word.html#t:Word8">Word8</a> <a href="src/System-Random-Dice-Internal.html#systemEntropy" class="link">Source</a> <a href="#v:systemEntropy" class="selflink">#</a></p><div class="doc"><p>A source of entropy. By default, we use the <code><a href="file:///usr/share/doc/libghc-entropy-doc/html/System-Entropy.html#v:getEntropy">getEntropy</a></code> function from
the entropy package, see <code><a href="System-Random-Dice.html#v:systemEntropy">systemEntropy</a></code>. </p><p><em>Warning:</em> When combining a source of entropy with other conduits, it is
important that there is no "backflow" due to leftover values that
are being returned to the
source from the conduit. This can be done by fusing the conduit with the
identity map, e.g: <code>myEntropySrc $$ Data.Conduit.List.map id =$= myConduit</code></p></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.17.3</p></div></body></html>
|