Functions providing random numbers and sequences.
Returns a pseudo random number.
random( ... )
| ... | See below. |
| Return | A pseudo random number or a random item picked from parameters. |
This function has actually several functionalities that are selected depending on the parameters.
Without parameters, the function returns a floating point number in the range [0,1).
With a signle numeric parameter, the function returns an integer between 0 and the number, included. The following functions are equivalent:
> random( x )
> int( random() * (x + 1) )
With two numeric parameters, the function returns an integer in the range [x, y]. The following functions are equivalent:
> random( x, y )
> int( x + (random() * (y + 1)) )
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.
The function randomChoice returns unambiguously one of the parameters picked at random.
Selects one of the arguments at random and returns it.
randomChoice( ... )
| ... | At least two items of any kind. |
| Return | One of the parameters, picked at random. |
This function works as random 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.
Performs a virtual dice set trow.
randomDice( dices, [sides] )
| dices | Number of dices to be thrown. |
| sides | Number of faces in the virtual dices. |
| Return | A random value which is the sum of the virtual throws. |
This function generates a series of successive dices throws, each one being integer value in the range [1, sides].
If sides is not given, 6 is assumed.
It would be easy to obtain the same result with simple instructions in Falcon, but this function spares several wasted VM cycles.
The dices parameter must be greater than zero, and the and sides parameter must be greater than one.
Grabs repeatedly random elements from an array.
randomGrab( series, [size] )
| series | An array from which items will be extracted. |
| size | Count of extracted items. |
| Return | An array with some or all of the items grabbed from the original elements. |
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.
If size is not given, 1 is assumed; if it's zero or less than zero, then all the elements in the series array will be taken.
This function is suitable to emulate card shuffling or other random extraction events.
Grabs repeatedly random elements from an array.
randomPick( series )
| series | An array containing one or more items. | ||
| Return | One of the items in the array. | ||
| Raise |
|
This function choices one of the items contained in the series array at random.
If the array is empty, a ParamError error is raised.
Seeds the random number generator.
randomSeed( [seed] )
| seed | An integer number being used as random seed. |
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.
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.
Using a constant number as random seed may be a good strategy to produce predictable debug sequences.
Performs a random walk in an array.
randomWalk( series, [size] )
| series | An array containing one or more items. |
| size | Desire size of the walk. |
| Return | An array built from randomly picked items. |
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.
If the requested target size is zero, or if the original array is empty, an empty array is returned.
If size 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 series array, but the target array can contain multiple copies of the items in series, or it may be missing some of them.