# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.26 Math Constants | Up: 8 API Reference | 8.28 Statistics > | 9 Release Notes >>

## 8.27 Random Numbers

#### 8.27.0.1 rand

    <built-in> function rand(object maximum)

returns a random integral value.

##### Parameters:

1. `maximum` : an atom, a cap on the value to return.

##### Returns:

An atom, from 1 to `maximum`.

##### Comments:

- The minimum value of `maximum` is 1.
- The maximum value that can possibly be returned is `#FFFFFFFF` (`4_294_967_295`)
- This function may be applied to an atom or to all elements of a sequence.
- In order to get reproducible results from this function, you should call set_rand with a reproducible value prior.

##### Example 1:

    s = rand({10, 20, 30})
    -- s might be: {5, 17, 23} or {9, 3, 12} etc.

##### See Also:

set_rand, ceil

#### 8.27.0.2 rand_range

    include std/rand.e
    namespace random
    public function rand_range(atom lo, atom hi)

returns a random integer from a specified inclusive integer range.

##### Parameters:

1. `lo` : an atom, the lower bound of the range
2. `hi` : an atom, the upper bound of the range.

##### Returns:

An atom, randomly drawn between `lo` and `hi` inclusive.

##### Comments:

This function may be applied to an atom or to all elements of a sequence. In order to get reproducible results from this function, you should call `set_rand` with a reproducible value prior.

##### Example 1:

    s = rand_range(18, 24)
    -- s could be any of: 18, 19, 20, 21, 22, 23 or 24

##### See Also:

rand, set_rand, rnd

#### 8.27.0.3 rnd

    include std/rand.e
    namespace random
    public function rnd()

returns a random floating point number in the range 0 to 1.

##### Parameters:

None.

##### Returns:

An atom, randomly drawn between 0.0 and 1.0 inclusive.

##### Comments:

In order to get reproducible results from this function, you should call `set_rand` with a reproducible value prior to calling this.

##### Example 1:

    set_rand(1001)
    s = rnd()
      -- s is 0.6277338201

##### See Also:

rand, set_rand, rand_range

#### 8.27.0.4 rnd_1

    include std/rand.e
    namespace random
    public function rnd_1()

returns a random floating point number in the range 0 to less than 1.

##### Parameters:

None.

##### Returns:

An atom, randomly drawn between 0.0 and a number less than 1.0

##### Comments:

In order to get reproducible results from this function, you should call `set_rand` with a reproducible value prior to calling this.

##### Example 1:

    set_rand(1001)
    s = rnd_1()
      -- s is 0.6277338201

##### See Also:

rand, set_rand, rand_range

#### 8.27.0.5 set_rand

    include std/rand.e
    namespace random
    public procedure set_rand(object seed)

resets the random number generator.

##### Parameters:

1. `seed` : an object. The generator uses this initialize itself for the next random number generated. This can be a single integer or atom, or a sequence of two integers, or an empty sequence or any other sort of sequence.

##### Comments:

- Starting from a `seed`, the values returned by `rand` are reproducible. This is useful for demos and stress tests based on random data. Normally the numbers returned by the `rand` function are totally unpredictable, and will be different each time you run your program. Sometimes however you may wish to repeat the same series of numbers, perhaps because you are trying to debug your program, or maybe you want the ability to generate the same output (for example random picture) for your user upon request.
- Internally there are actually two seed values.
  - When `set_rand` is called with a single integer or atom, the two internal seeds are derived from the parameter.
  - When `set_rand` is called with a sequence of exactly two integers or atoms the internal seeds are set to the parameter values.
  - When `set_rand` is called with an empty sequence, the internal seeds are set to random values and are unpredictable. This is how to reset the generator.
  - When `set_rand` is called with any other sequence, the internal seeds are set based on the length of the sequence and the hashed value of the sequence.
- Aside from an empty `seed` parameter, this sets the generator to a known state and the random numbers generated after come in a predicable order, though they still appear to be random.

##### Example 1:

    sequence s, t
    s = repeat(0, 3)
    t = s

    set_rand(12345)
    s[1] = rand(10)
    s[2] = rand(100)
    s[3] = rand(1000)

    set_rand(12345)  -- same value for set_rand()
    t[1] = rand(10)  -- same arguments to rand() as before
    t[2] = rand(100)
    t[3] = rand(1000)
    -- at this point s and t will be identical
    set_rand("") -- Reset the generator to an unknown seed.
    t[1] = rand(10)  -- Could be anything now, no way to predict it.

##### See Also:

rand

#### 8.27.0.6 get_rand

    include std/rand.e
    namespace random
    public function get_rand()

retrieves the current values of the random generator's seeds.

##### Returns:

a sequence. A 2-element sequence containing the values of the two internal seeds.

##### Comments:

You can use this to save the current seed values so that you can later reset them back to a known state.

##### Example 1:

    sequence seeds
     seeds = get_rand()
     some_func() -- Which might set the seeds to anything.
     set_rand(seeds) -- reset them back to whatever they were
                     -- before calling 'some_func()'.

##### See Also:

set_rand

#### 8.27.0.7 chance

    include std/rand.e
    namespace random
    public function chance(atom my_limit, atom top_limit = 100)

simulates the probability of a desired outcome.

##### Parameters:

1. `my_limit` : an atom. The desired chance of something happening.
2. `top_limit`: an atom. The maximum chance of something happening. The default is 100.

##### Returns:

an integer. 1 if the desired chance happened otherwise 0.

##### Comments:

This simulates the chance of something happening. For example, if you wnat something to happen with a probablity of 25 times out of 100 times then you code `chance(25)` and if you want something to (most likely) occur 345 times out of 999 times, you code `chance(345, 999)`.

##### Example 1:

    -- 65% of the days are sunny, so ...
     if chance(65) then
         puts(1, "Today will be a sunny day")
     elsif chance(40) then
         -- And 40% of non-sunny days it will rain.
         puts(1, "It will rain today")
     else
         puts(1, "Today will be a overcast day")
     end if

##### See Also:

rnd, roll

#### 8.27.0.8 roll

    include std/rand.e
    namespace random
    public function roll(object desired, integer sides = 6)

simulates the probability of a dice throw.

##### Parameters:

1. `desired` : an object. One or more desired outcomes.
2. `sides`: an integer. The number of sides on the dice. Default is 6.

##### Returns:

an integer. 0 if none of the desired outcomes occured, otherwise the face number that was rolled.

##### Comments:

The minimum number of sides is two and there is no maximum.

##### Example 1:

    res = roll(1, 2)
          --> Simulate a coin toss.
    res = roll({1,6})
          --> Try for a 1 or a 6 from a standard die toss.
    res = roll({1,2,3,4}, 20)
          --> Looking for any number under 5 from a 20-sided die.

##### See Also:

rnd, chance

#### 8.27.0.9 sample

    include std/rand.e
    namespace random
    public function sample(sequence population, integer sample_size, integer sampling_method = 0)

selects a set of random samples from a population set.

##### Parameters:

1. `population` : a sequence. The set of items from which to take a sample.
2. `sample_size`: an integer. The number of samples to take.
3. `sampling_method`: an integer.
   1. When < 0, "with-replacement" method used.
   2. When = 0, "without-replacement" method used and a single set of samples returned.
   3. When > 0, "without-replacement" method used and a sequence containing the set of samples (chosen items) and the set unchosen items, is returned.

##### Returns:

A sequence. When `sampling_method` less than or equal to 0 then this is the set of samples, otherwise it returns a two-element sequence; the first is the samples, and the second is the remainder of the population (in the original order).

##### Comments:

Selects a set of random samples from a population set. This can be done with either the "with-replacement" or "without-replacement" methods. When using the "with-replacement" method, after each sample is taken it is returned to the population set so that it could possible be taken again. The "without-replacement" method does not return the sample so these items can only ever be chosen once.

- If `sample_size` is less than `1` , an empty set is returned.
- When using "without-replacement" method, if `sample_size` is greater than or equal to the population count, the entire population set is returned, but in a random order.
- When using "with-replacement" method, if `sample_size` can be any positive integer, thus it is possible to return more samples than there are items in the population set as items can be chosen more than once.

##### Example 1:

    -- without replacement

    set_rand("example")
    printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 1)})
         --> "t"
    printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 5)})
         --> "flukq"
    printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", -1)})
         --> ""
    printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 26)})
         --> "kghrsxmjoeubaywlzftcpivqnd"
    printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 25)})
        --> "omntrqsbjguaikzywvxflpedc"

##### Example 2:

    -- with replacement

    set_rand("example")
    printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 1, -1)})
         --> "t"
    printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 5, -1)})
         --> "fzycn"
    printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", -1, -1)})
         --> ""
    printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 26, -1)})
         --> "keeamenuvvfyelqapucerghgfa"
    printf(1, "%s\n", { sample("abcdefghijklmnopqrstuvwxyz", 45, -1)})
        --> "orwpsaxuwuyrbstqqwfkykujukuzkkuxvzvzniinnpnxm"

##### Example 3:

    -- Deal 4 hands of 5 cards from a standard deck of cards.
    sequence theDeck
    sequence hands = {}
    sequence rt
    function new_deck(integer suits = 4, integer cards_per_suit = 13, integer wilds = 0)
    	sequence nd = {}
    	for i = 1 to suits do
    		for j = 1 to cards_per_suit do
    			nd = append(nd, {i,j})
    		end for
    	end for
     for i = 1 to wilds do
         nd = append(nd, {suits+1 , i})
     end for
    	return nd
    end function

    theDeck = new_deck(4, 13, 2) -- Build the initial deck of cards
    for i = 1 to 4 do
     -- Pick out 5 cards and also return the remaining cards.
    	rt = sample(theDeck, 5, 1)
    	theDeck = rt[2] -- replace the 'deck' with the remaining cards.
    	hands = append(hands, rt[1])
    end for

| Up |  |  | TOC | Index
<< 7 Included Tools | < 8.26 Math Constants | Up: 8 API Reference | 8.28 Statistics > | 9 Release Notes >>