The SHUFFLE function takes the items in any given list and re-orders them randomly.
This function takes any list as input. It outputs another list with all the same items as the first list in a random order.
Declaration
SHUFFLE(list) -> shuffled_list
Parameters
list (required, type: list)
A list containing any number of items. These items can be of any type and do not need to be the same type as each other.
Return Values
shuffled_list (type: list)
The resulting shuffled list with all the items randomly re-ordered.
Examples
The following example takes a list of numbers one through six and puts them in a random order. Note that running the same formula three separate times results in three slightly different outputs. Each time the SHUFFLE function is called upon, it randomizes anew:
SHUFFLE([1, 2, 3, 4, 5, 6]) -> [2, 4, 3, 6, 1, 5]
SHUFFLE([1, 2, 3, 4, 5, 6]) -> [6, 1, 5, 4, 2, 3]
SHUFFLE([1, 2, 3, 4, 5, 6]) -> [3, 2, 4, 6, 5, 1]
The above example, list was hardcoded, but that doesn't need to be the case. For the last example, assume the formula has access to the following list:
example_list = [[1, 2, 3], 1, "hello", "this is a string", {"name":"John"}]
Note that example_list consists of myriad types of values. The first value is a Number (1), the second and third values are strings ("hello" and "this is a string"), the fourth value is a List ( [1, 2, 3] ), and the fifth value is an object ( {"name" : "John"} ). This list was chosen not because it is particularly likely to be encountered it in the wild, but to emphasize that the values listed in list do not at all need to be same type as each other.
The following example takes the disparate items in example_list and shuffles them into a random order. Again, note that running the same formula multiple times results in different ordering:
SHUFFLE(example_list) -> [{"name":"John"}, 1, "hello", "this is a string", [1, 2, 3] ]
SHUFFLE(example_list) -> [1, {"name":"John"}, "this is a string", [1, 2, 3], "hello" ]
SHUFFLE(example_list) -> ["this is a string", "hello", [1, 2, 3], {"name":"John"}, 1 ]