<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Function set "Random functions" - Function set "Random functions"</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Function set "Random functions"</h1>
<p class="faldoc_brief">Functions providing random numbers and sequences. </p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#random">random()</a></td><td>Returns a pseudo random number. </td></tr>
<tr><td><a href="#randomChoice">randomChoice()</a></td><td>Selects one of the arguments at random and returns it. </td></tr>
<tr><td><a href="#randomDice">randomDice()</a></td><td>Performs a virtual dice set trow. </td></tr>
<tr><td><a href="#randomGrab">randomGrab()</a></td><td>Grabs repeatedly random elements from an array. </td></tr>
<tr><td><a href="#randomPick">randomPick()</a></td><td>Grabs repeatedly random elements from an array. </td></tr>
<tr><td><a href="#randomSeed">randomSeed()</a></td><td>Seeds the random number generator. </td></tr>
<tr><td><a href="#randomWalk">randomWalk()</a></td><td>Performs a random walk in an array. </td></tr>
</table>
<h2 class="faldoc_title">Members</h2>
<h3 class="faldoc_funcname"><a name="random">random()</a></h3>
<p class="item_brief">Returns a pseudo random number. </p>
<p class="faldoc_funcdecl">random( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">See below. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A pseudo random number or a random item picked from parameters. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function has actually several functionalities that are selected depending on the parameters. </p>
<p class="faldoc_text">Without parameters, the function returns a floating point number in the range [0,1). </p>
<p class="faldoc_text">With a signle numeric parameter, the function returns an integer between 0 and the number, included. The following functions are equivalent: </p>
<pre class="faldoc_code">
> random( x )
> int( random() * (x + 1) )
</pre>
<p class="faldoc_text">With two numeric parameters, the function returns an integer in the range [x, y]. The following functions are equivalent: </p>
<pre class="faldoc_code">
> random( x, y )
> int( x + (random() * (y + 1)) )
</pre>
<p class="faldoc_text">With more than two parameters, or when at least one of the first two parameters it not a number, one of the parameter is picked at random and then returned. </p>
<p class="faldoc_text"> The function <a href="./functions.html#randomChoice">randomChoice</a> returns unambiguously one of the parameters picked at random. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomChoice">randomChoice()</a></h3>
<p class="item_brief">Selects one of the arguments at random and returns it. </p>
<p class="faldoc_funcdecl">randomChoice( ... )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">...</td><td class="faldoc_paramdesc">At least two items of any kind. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">One of the parameters, picked at random. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function works as <a href="./functions.html#random">random</a> when it receives more than two parameters, but its usage is not ambiguous in case there are two items from which to choice. The function raises an error if less than two parameters are passed. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomDice">randomDice()</a></h3>
<p class="item_brief">Performs a virtual dice set trow. </p>
<p class="faldoc_funcdecl">randomDice( dices, [sides] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dices</td><td class="faldoc_paramdesc">Number of dices to be thrown. </td></tr>
<tr><td class="faldoc_optparam">sides</td><td class="faldoc_optparamdesc">Number of faces in the virtual dices. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A random value which is the sum of the virtual throws. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function generates a series of successive <b>dices</b> throws, each one being integer value in the range [1, <b>sides</b>]. </p>
<p class="faldoc_text"> If <b>sides</b> is not given, 6 is assumed. </p>
<p class="faldoc_text">It would be easy to obtain the same result with simple instructions in Falcon, but this function spares several wasted VM cycles. </p>
<p class="faldoc_text"> The <b>dices</b> parameter must be greater than zero, and the and <b>sides</b> parameter must be greater than one. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomGrab">randomGrab()</a></h3>
<p class="item_brief">Grabs repeatedly random elements from an array. </p>
<p class="faldoc_funcdecl">randomGrab( series, [size] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">series</td><td class="faldoc_paramdesc">An array from which items will be extracted. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Count of extracted items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array with some or all of the items grabbed from the original elements. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function extracts a desired amount of items from the elements array, putting them in a new array that will be returned. Items left in the elements array have a fair chance to be selected and removed at every step. If the size parameter is greater or equal than the size of the elements array, the array is eventually emptied and all the items are moved to the new array, actually performing a complete fair shuffling of the original. </p>
<p class="faldoc_text"> If <b>size</b> is not given, 1 is assumed; if it's zero or less than zero, then all the elements in the <b>series</b> array will be taken. </p>
<p class="faldoc_text">This function is suitable to emulate card shuffling or other random extraction events. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomPick">randomPick()</a></h3>
<p class="item_brief">Grabs repeatedly random elements from an array. </p>
<p class="faldoc_funcdecl">randomPick( series )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">series</td><td class="faldoc_paramdesc">An array containing one or more items. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">One of the items in the array. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ParamError.html">ParamError</a></td><td class="faldoc_raisedesc"> if the <b>series</b> is empty. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This function choices one of the items contained in the <b>series</b> array at random. </p>
<p class="faldoc_text">If the array is empty, a ParamError error is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomSeed">randomSeed()</a></h3>
<p class="item_brief">Seeds the random number generator. </p>
<p class="faldoc_funcdecl">randomSeed( [seed] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">seed</td><td class="faldoc_optparamdesc">An integer number being used as random seed. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The random seed should be set once per program, possibly using a number that is likely to vary greatly among different executions. A good seed may be the return of the seconds() function, eventually multiplied by 1000 to make the milliseconds to take part in the seeding. If called without parameters, a number based on the current system timer value will be used. </p>
<p class="faldoc_text">Repeated calls to random(), and calls based on random function as randomChoice, randomPick and so on, will produce the same sequences if randomSeed() is called with the same seed. </p>
<p class="faldoc_text">Using a constant number as random seed may be a good strategy to produce predictable debug sequences. </p>
</p>
<h3 class="faldoc_funcname"><a name="randomWalk">randomWalk()</a></h3>
<p class="item_brief">Performs a random walk in an array. </p>
<p class="faldoc_funcdecl">randomWalk( series, [size] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">series</td><td class="faldoc_paramdesc">An array containing one or more items. </td></tr>
<tr><td class="faldoc_optparam">size</td><td class="faldoc_optparamdesc">Desire size of the walk. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An array built from randomly picked items. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function picks one or more elements from the given array, and stores them in a new array without removing them from the old one. Elements can be picked up repeatedly, and the size of the target array may be larger than the size of the original one. </p>
<p class="faldoc_text">If the requested target size is zero, or if the original array is empty, an empty array is returned. </p>
<p class="faldoc_text"> If <b>size</b> is not given, 1 is assumed; if it's less than zero, then an the function will create an array of the same size of the <b>series</b> array, but the target array can contain multiple copies of the items in <b>series</b>, or it may be missing some of them. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
