# random

The random function can be used in a few different ways, although of course all of them revolve around randomness.

# random( )

If you don’t provide any values within the random function’s parenthesis then the random function will simply make a random (whole) number.

## Returns

A random whole number greater than or equal to zero.

## Example

This example prints one hundred random numbers to the Application messages window.

1 2 3 4 5 6 |
define counter = 0 while counter < 100 define r = random( ) print("Random number: " + r ) counter += 1 end while |

random( minimum, maximum )

If you pass in two numeric values they are treated as a minimum and maximum value and the random function will create a random number between the minimum and maximum (inclusive) that you provided.

You can pass in two numbers, two percents, or two time values (see the examples).

## Arguments

minimum |
- The minimum random value to return |

maximum |
- The maximum random value to return |

Note that if the minimum is larger than the maximum then the function switches the minimum and the maximum values and proceeds as normal.

## Returns

A random value between the minimum and maximum numbers specified. If you pass in two percents then you will get out a percent; if you pass in two durations then you will get out a random duration. See the examples below for more details on how this works.

## Minimum/maximum example 1 – number

Prints one hundred random numbers between 20 and 2736 (why not?) to the Application messages window.

1 2 3 4 5 6 |
define counter = 0 while counter < 100 define r = random( 20, 2736 ) print("Random number: " + r ) counter += 1 end while |

In this example we will only get whole numbers (no random numbers after the decimal).

## Minimum/maximum example 2 – number with decimals

This example is exactly the same code as the previous number example 1 (above) except that we’ve added some decimal places to one of the numbers (it doesn’t matter which one). This causes the random function to generate random numbers with the same number of decimal places (so, for example, 50.234).

1 2 3 4 5 6 |
define counter = 0 while counter < 100 define r = random( 20.000, 2736 ) print("Random number: " + r ) counter += 1 end while |

So in this example we will get decimal random numbers (with up to three digits after the decimal). If both numbers we were passing into the random function had decimals, then the one with the most decimals would determine the number of decimals in the resulting random numbers.

## Minimum/maximum example 3 – number variable with decimals

This example is almost the same code as the previous number example 2 (above) except that rather than pass in a number directly we are passing in a variable that has a number in it. The number inside the variable has two decimal places, so the random function will generate random numbers with two decimal places (so, for example, 50.24).

1 2 3 4 5 6 7 |
define counter = 0 define inputPercent = 20.00 while counter < 100 define r = random( inputPercent, 80 ) print("Random number: " + r ) counter += 1 end while |

In this example we will get decimal random numbers (with up to two digits after the decimal). If both numbers we were passing into the random function had decimals, then the one with the most decimals would determine the number of decimals in the resulting random numbers.

## Minimum/maximum example 4 – percent

Prints one hundred random percent values between 20% and 70% to the Application messages window.

1 2 3 4 5 6 |
define counter = 0 while counter < 100 define r = random( 20%, 70% ) print("Random percent: " + r ) counter += 1 end while |

Just like with number example 1 (above), because our inputs to the random function did not have decimal values we will not get any decimals in the random output, so 27% or 50% but you will not get results like 50.234%.

## Minimum/maximum example 5 – percent with decimals and a variable

This example shows how both decimal places and variables affect the output. Our variable has a percent with three decimal places, and the other value passed in has only one decimal digit. The largest number of decimal digits defines how many decimal places will be in the output, so in this case our resulting random percents will have at most two decimal places.

1 2 3 4 5 6 7 |
define counter = 0 define inputPercent = 20.00% while counter < 100 define r = random( inputPercent, 80.2% ) print("Random number: " + r ) counter += 1 end while |

In this example we will get decimal results, so 62.73%.

## Minimum/maximum example 6 – time

Prints one hundred random times between 5sec and 20sec to the Application messages window.

1 2 3 4 5 6 |
define counter = 0 while counter < 100 define r = random( 5sec, 20sec ) print("Random time: " + r ) counter += 1 end while |

Note that in this example you might get results like 7.2345 seconds. Randomly generating time values doesn’t work like numbers and percents. This is because most of the time if you are generating a random number between 1 minute and 2 minutes (for example) you would expect results like 1 minute and 41 seconds (rather than either just getting 1 minute or 2 minutes as possible random results). If you think this should be changed please let us know!

random( item, item, item, …. item )

Randomly returns one of the items from the list of items you provide.

## Arguments

A collection of individual items (whatever you want) to randomly select from.

## Returns

One of the items in the list within the parenthesis.

## Example

Randomly prints out one of the items from the list of items within the parenthesis.

1 2 3 4 |
define aNumber = 2360 define aTime = 5sec define result = random( aNumber, aTime, "apple", "pear", "peach" ) print("Random item: " + result ) |

random( collection )

Randomly returns one of the items from the collection you provide within the parenthesis.

## Arguments

Pass in a collection object; note that if you pass in two or more collections then you will randomly get back one of the collections that you passed in

(because you will actually be using the random( item1, item2, item3, … itemN) function above and not this version of the function).

## Returns

One of the items from the collection within the parenthesis.

## Example 1 – words

Randomly prints out a series of ten words from our collection.

1 2 3 4 5 6 7 8 9 10 11 12 13 |
define collection WordsCollectionType "hello" "goodbye" end collection define words = create WordsCollectionType define counter = 0 while counter < 10 define word = random( words ) print("Random word: " + word ) counter += 1 end while |

Of course, this could have been done with the random( item1, item2, item3, … itemN) function (discussed above) but this approach is more powerful because we can easily add and remove items from our collection. To see that in action, let’s first change to choosing colours.

## Example 2 – choosing a colour

Randomly prints out one of the colours from the collection of colours.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
define collection WordsCollectionType "hello" "goodbye" end collection // Create our collection define words = create WordsCollectionType // Run our random colour selection 10 times define counter = 0 while counter < 10 // Choose a random colour from the collection of colours define word = random( words ) print("Random colour: " + word ) counter += 1 end while |

So here again we could have been done this with the random( item1, item2, item3, … itemN) function. So to see how this approach is more powerful, let us now choose two distinct colours using our collections.

## Example 3 – choosing two distinct colours

Randomly prints out two distinct colours from the collection of colours (making sure that the second colour is never the same as the first random colour selected).

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
define collection ColourCollectionType #FF0000 // Red #00FF00 // Green #0000FF // Blue #000000 // Black #FFFFFF // White end collection // Create our collection define colours = create ColourCollectionType // Select our first colour define colour1 = random( colours ) // Create a new collection that has the first randomly selected colour removed // and then choose our second colour from our new collection define remainingColours = colours - colour1 define colour2 = random( remainingColours ) // Print out our two colours, which will always be different print("Random colour #1: " + colour1 ) print("Random colour #2: " + colour2 ) |

So in this example we can see how using collections is more powerful than using the random( item1, item2, item3, … itemN) function because we can modify the collection of items being passed into the random() function. With the random( item1, item2, item3, … itemN) function the set of items passed to the random function must always be fixed because you type it into the codes. In this case, when choosing the second colour we wouldn’t know what the first randomly selected colour was when we are writing the codes, so that wouldn’t be possible.