Module chance

Chance: A Library for Generating Random Data

Info:

  • Copyright: 2015 Plutono Inc
  • Release: Project Home
  • License: GNU General Public License
  • Author: Eric James Michael Ritz

Core

VERSION The library version number.
chance.core.seed (seed) Seeds the random number generator.
chance.core.random ([m[, n]]) Returns a random number.
chance.core.dataSets Sets of data which some functions choose from.
chance.core.set (key, data) Define or modify a set of data.
chance.core.appendSet (key, data) Add data to an existing data set.
chance.core.fromSet (key) Select random data from an existing data set.

Basic

chance.basic.bool ([flags]) Returns a random boolean.
chance.basic.float () Returns a random floating-point number.
chance.basic.integer ([flags]) Returns a random integer.
chance.basic.natural ([flags]) Returns a random natural number.
chance.basic.character ([flags]) Returns a random character.
chance.basic.string ([flags]) Returns a random string.

Text

chance.text.syllable () Returns a random syllable.
chance.text.word ([flags]) Returns a random word.
chance.text.sentence ([flags]) Generates a random sentence of words via chance.text.word.
chance.text.paragraph ([flags]) Generates a random paragraph via chance.text.sentence.

Person

chance.person.ssn () Generates a random United States Social Security Number.
chance.person.gender ([flags]) Returns a random gender as a string.
chance.person.prefix ([flags]) Returns a random prefix for a name.
chance.person.suffix ([flags]) Returns a random suffix for names.
chance.person.age ([flags]) Returns a random age for a person.

Time

chance.time.hour ([flags]) Returns a random hour.
chance.time.minute () Returns a random minute.
chance.time.second () Returns a random second.
chance.time.millisecond () Returns a random millisecond.
chance.time.year ([flags]) Returns a random year.
chance.time.month () Returns the name of a random month.
chance.time.day ([flags]) Returns a random day of the week.
chance.time.timestamp () Returns a random Unix timestamp.
chance.time.ampm () Returns 'am' or 'pm' for use with times.

Web

chance.web.color ([flags]) Returns a random color for use in HTML and CSS.
chance.web.ip ([flags]) Generates a random IP address.
chance.web.ipv6 () Generates a random IPv6 address.
chance.web.tld () Generate a random top-level domain.
chance.web.domain ([flags]) Generate a random domain.
chance.web.email ([flags]) Returns a random email address.
chance.web.hashtag () Returns a random Twitter hashtag.
chance.web.twitter () Generates a random Twitter handle.
chance.web.uri ([flags]) Generates a random URI.
chance.web.url ([flags]) Generates a random URL.

Poker

chance.poker.card ([flags]) Returns a random Poker card.
chance.poker.deck ([flags]) Returns a deck of Poker cards.
chance.poker.hand ([flags]) Returns a hand of Poker cards.

Miscellaneous

chance.misc.normal ([flags]) Returns a normally-distributed random value.
chance.misc.weighted (values, weights) Randomly selects an item from an array of weighted values.
chance.misc.n (generator, count[, ...]) Create an array of random data from a given generator.
chance.misc.unique (generator, count[, ...]) Creates an array of unique values from a given generator.
chance.misc.hash ([flags]) Create a random hash in hexadecimal.
chance.misc.rpg (notation) Create an array of die rolls using Dungeons and Dragons notation.
chance.misc.d4 () Roll a 4-sided die.
chance.misc.d6 () Roll a 6-sided die.
chance.misc.d8 () Roll an 8-sided die.
chance.misc.d10 () Roll a 10-sided die.
chance.misc.d12 () Roll a 12-sided die.
chance.misc.d20 () Roll a 20-sided die.
chance.misc.d100 () Roll a 100-sided die.

Helpers

chance.helpers.pick (array[, count]) Pick a random element from a given array.
chance.helpers.pick_unique (array, count) Pick a random collection of unique elements from an array.
chance.helpers.shuffle (array) Randomly shuffle the contents of an array.


Core

These functions provide a random number generator atop which the rest of the library is built, and metadata about the library.
VERSION
The library version number.

This table contains four keys: MAJOR, MINOR, PATCH, and LABEL. The first three are numbers, and the last is a potentially empty string. Calling tostring() on the table will produce an easy-to-read version number such as "1.0.2-rc1", "2.0.0", etc.

The version number follows Semantic Versioning.

  • VERSION
chance.core.seed (seed)
Seeds the random number generator.

This function accepts one parameter: a seed, which it uses to seed the random number generator. The seed must be a number, and providing the same seed must result in chance.core.random producing the same sequence of results. Beyond that there are no restrictions on the implementation of how the seed is used or the underlying random number generation algorithm to be used.

Parameters:

  • seed Number

Returns:

    nil
chance.core.random ([m[, n]])
Returns a random number.

This is the primary function used throughout the library for generating random numbers. Any algorithm for generating random numbers may be used, so long as the implementation of this function adheres to the following restrictions:

1. When called with no arguments the function must return a number in the range of [0, 1).

2. When called with one argument, a number 'm', the function must return a number in the range of [1, m].

3. When called with two arguments, numbers 'm' and 'n', the function must return a number in the range of [m, n]. If 'n' is less than or equal to 'm' then the function simply returns 'm'.

Note that this is the same behavior as math.random() from Lua's standard library.

Parameters:

  • m (optional)
  • n (optional)

Returns:

    Number

See also:

Usage:

  • chance.core.random() == 0.8273
  • chance.core.random(10) == 7
  • chance.core.random(8, 12) == 8
chance.core.dataSets
Sets of data which some functions choose from.

Many functions select random data from a predefined source. For example, chance.time.month randomly picks a name from an existing list of names. This table contains all of those types of predefined sets of data. Developers can modify or add new sets of data by using the chance.core.set function.

The keys for this table must strings, which name the data set.

The values must either be arrays (which can contain any types of values), or a single function. If the value is a function then the library treats it as a generator for that data set, i.e. the library will invoke that function expecting it to return the appropriate type of random data. The function will receive no arguments.

Fields:

  • dataSets

See also:

chance.core.set (key, data)
Define or modify a set of data.

This function creates a new set of data or replaces an existing one. The key parameter must be a string naming the data set. The data parameter must be either a table of data, which can be of any type, or must be a function. If it is a function then the library treats it as a generator and will invoke that function with no arguments whenever random data is requested from that set.

Parameters:

Returns:

    nil

See also:

chance.core.appendSet (key, data)
Add data to an existing data set.

See the documentation on chance.core.set for details on the key parameter. The data must be a table of values which the function will add to the existing data set. This does not work for data sets that have generator functions for their values.

Parameters:

Returns:

    nil

See also:

chance.core.fromSet (key)
Select random data from an existing data set.

See the documentation on chance.core.set for details on the restrictions and semantics of the key parameter.

Parameters:

Returns:

    Random data of potentially any type, or nil if there is no data set for the given key

See also:

Basic

These are functions that generate simple types of data such as booleans and numbers.
chance.basic.bool ([flags])
Returns a random boolean.

If given no arguments the function has a 50/50 chance of returning true or false. However, an optional table argument can specify the probability of returning true, expressing the probability as a percentage by using an integer in the range [1, 100].

Parameters:

  • flags (optional)

Returns:

    true or false

Usage:

  • fifty_fifty = chance.basic.bool()
  • ten_percent_true = chance.basic.bool { probability = 10 }
chance.basic.float ()
Returns a random floating-point number.

The number will be in the range of zero (inclusive) to one (exclusive), like random number generating functions in many programming languages.

Returns:

    number
chance.basic.integer ([flags])
Returns a random integer.

By default the function returns an integer between smallest and the largest integers Lua allows on the given platform. An optional table can provide inclusive "min" and "max" limits, which have the default values -2^16 and 2^16, respectively.

Parameters:

  • flags (optional)

Returns:

    int

Usage:

  • x = chance.basic.integer()
  • y = chance.basic.integer { max = 50 }
  • z = chance.basic.integer { min = 1, max = 20 }
chance.basic.natural ([flags])
Returns a random natural number.

By default the function returns a number between zero and positive inifinity. But it accepts an optional table of flags which can define inclusive "min" and "max" ranges for the result. Minimum values less than zero are rounded up to zero.

Parameters:

  • flags (optional)

Returns:

    int

See also:

chance.basic.character ([flags])
Returns a random character.

This functions returns a random character which will be either a digit or a letter, lower-case and upper-case.

The function accepts a table of optional flags. The "pool" flag can be a string from which the function will select a character. Or one can use the "group" flag to receive a random character from a specific group of characters. The acceptable group names are "lower", "upper", "letter" (case-insensitive), "digit", and "all" (the default). If the function receives both "pool" and "group" then "pool" takes precedence and "group" is ignored.

Parameters:

  • flags (optional)

Returns:

    string

Usage:

  • anything = chance.basic.character()
  • anything = chance.basic.character { group = "all" }
  • vowel = chance.basic.character { pool = "aeiou" }
  • capital = chance.basic.character { group = "upper" }
chance.basic.string ([flags])
Returns a random string.

This function will return a string of random characters, with a random length of five to twenty characters. The optional flags table can set "length" explicitly. It also accepts a "group" flag which determines what kind of characters appear in the string.

Parameters:

  • flags (optional)

Returns:

    string

See also:

Usage:

  • chance.basic.string() == "c0Ab3le8"
  • chance.basic.string { length = 3 } == "NIN"
  • chance.basic.string { group = "digit" } = "8374933749"

Text

These are functions for generating random text.
chance.text.syllable ()
Returns a random syllable.

This functions returns a randomly generated syllable that will be between two to six characters in length. It uses the syllables data set, which contains a collection of consonants and vowels used to create the syllable. Each syllable will contain between two to six characters.

Returns:

    string

See also:

Usage:

    chance.text.syllable() == "peep"
chance.text.word ([flags])
Returns a random word.

The word, by default, will contain one to three syllables. However, the optional flag syllables can specify exactly how many syllables to use in the word. Note that "syllable" in this context means anything which chance.text.syllable will return.

Parameters:

  • flags (optional)

Returns:

    string

See also:

Usage:

  • chance.text.word() == "beepbop"
  • chance.text.word { syllables = 4 } == "thadoobgerlu"
chance.text.sentence ([flags])
Generates a random sentence of words via chance.text.word.

This function returns a sentence of random words, between twelve to eighteen words by default. The optional words flag allows controling exactly how many words appear in the sentence. The first word in the sentence will be capitalized and the sentence will end with a period.

Parameters:

  • flags (optional)

Returns:

    string

See also:

Usage:

    chance.text.sentence { words = 3 } == "Hob the rag."
chance.text.paragraph ([flags])
Generates a random paragraph via chance.text.sentence.

This function returns a paragraph of random sentences, created by calling chance.text.sentence. By default the paragraph will contain three to seven sentences. However, the optional integer flag sentences controls exactly how many sentences to create for the paragraph.

Parameters:

  • flags (optional)

Returns:

    string

See also:

Person

These are functions for generating random data about people.
chance.person.ssn ()
Generates a random United States Social Security Number.

This function generates a random United States Social Security Number and returns it as a string, AAA-GG-SSSS, where the digits represent the Area, Group, and Serial numbers, respectively. The function will not return all zeros for any part of the number, nor will the Area ever be '666' or '900-999', per the standards on Social Security Numbers.

Returns:

    string

Usage:

    chance.person.ssn() == "343-74-0571"
chance.person.gender ([flags])
Returns a random gender as a string.

One can classify gender in a number of ways. The most traditional form is the binary division of 'male' and 'female'; if the function is given the optional flag binary = true then it will return either "Male" or "Female".

By default, however, the function will return a string from the genders data set.

Parameters:

  • flags (optional)

Returns:

    string

See also:

Usage:

  • chance.person.gender() == "Female"
  • chance.person.gender { binary = true } == "Male"
chance.person.prefix ([flags])
Returns a random prefix for a name.

This function will return a random prefix for a name, e.g. "Mr." or "Prof.", short prefixes by default. The function accepts an optional table of flags, and if the flag type equals "long" then the function returns prefixes such as "Mister" and "Professor". The function uses the prefixes data set.

Parameters:

  • flags (optional)

Returns:

    string

Usage:

  • chance.person.prefix() == "Mrs."
  • chance.person.prefix { type = "long" } == "Doctor"
chance.person.suffix ([flags])
Returns a random suffix for names.

This function will return a random suffix for a name, e.g. "Jr." or "M.D.", short prefixes by default. The function accepts an optional table of flags, and if the flag type equals "long" then the function returns prefixes such as "Junior" and "Juris Doctor". The function uses the suffixes data set.

Parameters:

  • flags (optional)

Returns:

    string

Usage:

  • chance.person.suffix() == "Sr."
  • chance.person.suffix { type = "long" } == "Senior"
chance.person.age ([flags])
Returns a random age for a person.

By default this function return an integer in the range of one and one-hundred twenty. It accepts an optional type flag which must be one of the following strings, which limit the range of the generated age:

  1. "child" = [1, 12]
  2. "teen" = [13, 19]
  3. "adult" = [18, 65]
  4. "senior" = [65, 100]

These ranges are defined in the ages data set, meaning one can use chance.core.set and chance.core.appendSet to redefine the ranges for types and/or add new types.

Parameters:

  • flags (optional)

Returns:

    int

Usage:

  • chance.person.age() == 33
  • chance.person.age { type = "teen" } == 17
  • chance.person.age { type = "adult" } == 40

Time

These are functions for generating random times.
chance.time.hour ([flags])
Returns a random hour.

By default this will return an hour in the range of one to twelve. However, if the optional flag twentyfour is true then the result will be in the range of one to twenty-four.

Parameters:

  • flags (optional)

Returns:

    number

Usage:

  • chance.time.hour() == 3
  • chance.time.hour { twentyfour = true } == 15
chance.time.minute ()
Returns a random minute.

This will return a number in the range of zero to fifty-nine.

Returns:

    number
chance.time.second ()
Returns a random second.

This will return a number in the range of zero to fifty-nine.

Returns:

    number
chance.time.millisecond ()
Returns a random millisecond.

This returns a number in the range of zero to nine-hundred ninety nine.

Returns:

    number
chance.time.year ([flags])
Returns a random year.

By default this function returns a number representing a year in the range of the current year and a century later. For example, calling chance.time.year() in the year 2015 will return a number between 2015 and 2115.

The function accepts an optional table of flags which can have min and max properties to restrict the range of the output. If only min is provided then the maximum range is one century ahead of the minimum, for example chance.time.year { min = 1750 } returns a year between 1750 and 1850. If only max is provided then the minimum is the current year.

Parameters:

  • flags (optional)

Returns:

    number

Usage:

  • chance.time.year() == 2074
  • chance.time.year { min = 1800 } == 1884
  • chance.time.year { max = 2300 } == 2203
  • chance.time.year { min = 1990, max = 2000 } == 1995
chance.time.month ()
Returns the name of a random month.

This function chooses the name of a month from the months data set.

Returns:

    string
chance.time.day ([flags])
Returns a random day of the week.

By default this function will return the name of a day of the week, chosen from the days data set. The function accepts an optional table of flags which control the possible days it returns. The optional boolean flags weekdays and weekends will restrict the output to those types of days.

Parameters:

  • flags (optional)

Returns:

    string

Usage:

  • chance.time.day() == "Monday"
  • chance.time.day { weekends = true } == "Sunday"
  • chance.time.day { weekends = false } == "Thursday"
chance.time.timestamp ()
Returns a random Unix timestamp.

This function returns a random number between zero and the current time as a Unix timestamp, i.e. the number of seconds since January 1st 1970.

This function may not correctly determine the current time on non-POSIX systems.

Returns:

    number
chance.time.ampm ()
Returns 'am' or 'pm' for use with times.

Returns:

    string "am" or "pm"

Web

These are functions for generating random data related to the World Wide Web.
chance.web.color ([flags])
Returns a random color for use in HTML and CSS.

This function returns a random color (as a string) suitable for use in HTML or Cascading Style Sheets. By default the function returns a color in six-digit hex notation, e.g #a034cc. However, the optional flag format can affect the representation of the color via the following values:

  1. hex e.g. #a034cc (Default)
  2. shorthex e.g. #3ca
  3. rgb e.g. rgb(120, 80, 255)

If the flag greyscale is true then the function generates a greyscale color. The flag grayscale (with an 'a') is an acceptable alias.

Parameters:

  • flags (optional)

Returns:

    string

Usage:

  • chance.web.color() == "#a034cc"
  • chance.web.color { format = "shorthex" } == "#eeb"
  • chance.web.color { format = "rgb" } == "rgb(120, 80, 255)"
  • chance.web.color { greyscale = true } == "#3c3c3c"
chance.web.ip ([flags])
Generates a random IP address.

This function generates a random IPv4 address and returns it as a string. By default the four octets can have any value in the range [0,255]. However, the function accepts optional flags that will create addresses of a specific class, or addresses with explicit values for certain octets.

Parameters:

  • flags (optional)

Returns:

    string

See also:

Usage:

  • chance.web.ip() == "132.89.0.200"
  • chance.web.ip { class = "B" } == "190.1.24.30"
  • chance.web.ip { octets = { 192, 128 }} == "192.128.0.1"
chance.web.ipv6 ()
Generates a random IPv6 address.

Returns:

    string

See also:

chance.web.tld ()
Generate a random top-level domain.

This function returns a random top-level domain as a string. It chooses a domain from the tlds data set.

Returns:

    string

Usage:

    chance.web.tld() == "net"
chance.web.domain ([flags])
Generate a random domain.

This function returns a random web domain. By default the domain name contains one to three words and a random top-level domain. The optional flag words controls exactly how many words appear in the domain, and the flag tld will ensure the result uses that specific top-level domain.

Parameters:

  • flags (optional)

Returns:

    string

See also:

Usage:

  • chance.web.domain() == "paroo.net"
  • chance.web.domain { words = 1 } == "fee.gov"
  • chance.web.domain { tld = "co.bh" } == "havashi.co.bh"
chance.web.email ([flags])
Returns a random email address.

This function will return an email address consisting of random words, belonging to a random domain. The optional flag domain can specify the exact domain to use.

Parameters:

  • flags (optional)

Returns:

    string

See also:

Usage:

chance.web.hashtag ()
Returns a random Twitter hashtag.

This function returns a string representing a Twitter hashtag. The string will begin with the '#' character and contain one to three random words.

Returns:

    string

See also:

Usage:

    chance.web.hashtag() == "#namarob"
chance.web.twitter ()
Generates a random Twitter handle.

This function returns a string representing a random Twitter account name. The string will begin with '@' followed by one to five words.

Returns:

    string

See also:

Usage:

    chance.web.twitter() == "@meepboat"
chance.web.uri ([flags])
Generates a random URI.

This function returns a random URI. By default it uses the http protocol, with random names generated for the domain and path. The function accepts a number of optional flags though:

  • domain - Sets an explicit domain name.
  • path - Sets an explicit path.
  • protocol Sets an explicit protocol.
  • extensions - Uses one of the given extensions.

Parameters:

  • flags (optional)

Returns:

    string

See also:

Usage:

  • chance.web.uri() == "http://foobar.net/baz"
  • chance.web.uri { domain = "example.com" } == "http://example.com/wee"
  • chance.web.uri { path = "foo/bar" } == "http://narofu.edu/foo/bar"
  • chance.web.uri { extensions = { "png", "gif" }} == "http://benhoo.gov/dao.png"
  • chance.web.uri { protocol = "ftp" } == "ftp://fufoo.net/veto"
chance.web.url ([flags])
Generates a random URL.

This function is an alias for chance.web.uri.

Parameters:

  • flags (optional)

Returns:

    string

Poker

These are functions for generating random data related to the card game Poker and its variants.
chance.poker.card ([flags])
Returns a random Poker card.

The functions returns a table representing a random Poker card. The table will have two keys:

  1. rank: A number in the range of [2, 10], or the strings "Jack", "Queen", "King", "Ace", and "Joker".
  2. suit: A string with the possible values of "Spade", "Heart", "Club", and "Diamond".

The function accepts an optional table of flags:

If the joker flag has a boolean false value then the function will never return the Joker.

The rank and suit flags accept values to use explicitly for the rank and suit of the generated card.

Parameters:

  • flags (optional)

Returns:

    table card

Usage:

  • chance.poker.card() == { rank = 4, suit = "Club" }
  • chance.poker.card { rank = "Jack" } == { rank = "Jack", suit = "Heart" }
  • chance.poker.card { suit = "Spade" } == { rank = 10, suit = "Spade" }
  • chance.poker.card { joker = false } == { rank = 5, suit = "Diamond" }
chance.poker.deck ([flags])
Returns a deck of Poker cards.

This function returns a table representing a deck of Poker cards. By default the deck contains 52 cards, i.e. it does not include the Joker. However, if the optional joker flag is present and has a boolean true value then the deck will include the Joker, for a total of 53 cards.

Parameters:

  • flags (optional)

Returns:

    table deck

See also:

Usage:

  • local deck = chance.poker.deck(); #deck == 52
  • local deck = chance.poker.deck { joker = true }; #deck == 53
chance.poker.hand ([flags])
Returns a hand of Poker cards.

By default this function returns a table with five elements, cards generated by calling the chance.poker.card function. The hand will contain unique cards. And the function will contain cards from the standard deck created by chance.poker.deck.

If given the optional flag cards then the function will return a hand containing that number of cards. If given the optional flag deck then it will select cards from that deck, which must be a table of cards, like the kind that chance.poker.deck will create.

Parameters:

  • flags (optional)

Returns:

    table hand

See also:

Miscellaneous

These are functions for generating data which does not easily fall under any other category.
chance.misc.normal ([flags])
Returns a normally-distributed random value.

By default the function returns a value with a mean of zero and a standard deviation of one. However, the optional flags mean and deviation can provide different values to use for each.

Parameters:

  • flags (optional)

Returns:

    number

Usage:

  • chance.misc.normal() == 0.2938473
  • chance.misc.normal { mean = 100 } == 99.172493
  • chance.misc.normal { mean = 100, deviation = 15 } == 85.83741
chance.misc.weighted (values, weights)
Randomly selects an item from an array of weighted values.

This function accepts two arrays: the first a table of values to select from, and the second a table of numbers indicating the weight for each value, i.e. the probability the function will select that value. If the two arguments are not tables of the same length then the function returns nil.

Parameters:

Returns:

    A element from the values array

Usage:

     chance.misc.weighted({"a", "b"}, {100, 1})
 -- This will return "a" one-hundred times more often than
 -- it will return "b".
chance.misc.n (generator, count[, ...])
Create an array of random data from a given generator.

This function requires two arguments: a function which generates random data, and a number. The function will invoke the generator that number of times and return an array of that size containing whatever random data comes out of the generator. Effectively this function acts as a shortcut for writing a for-loop that calls a chance.*() function a certain number of times while collecting the results into an array.

Any additional arguments will be given to the generator function on each invocation.

Parameters:

  • generator A function that returns random data.
  • count The number of times to call the generator.
  • ... Additional arguments passed to the generator. (optional)

Returns:

    table

Usage:

  • switches = chance.misc.n(chance.basic.bool, 3)
  • numbers = chance.misc.n(chance.basic.natural, 10, { max = 100 })
chance.misc.unique (generator, count[, ...])
Creates an array of unique values from a given generator.

This function is similar to chance.misc.n in that it accepts a generator function, often another chance function, and a number of items to generate. The function will return an array containing that many items, randomly generated by the given function. However, unlike chance.misc.n, the items in the array are guaranteed to be unique.

Any additional arguments will be given to the generator function on each invocation.

Parameters:

  • generator A function that returns random data.
  • count The number of times to call the generator.
  • ... Additional arguments passed to the generator. (optional)

Returns:

    table

Usage:

  • chance.misc.unique(chance.time.month, 3) == { "May", "February", "April" }
  • chance.misc.unique(chance.basic.character, 2, { pool = "aeiou" }) == { "e", "u" }
chance.misc.hash ([flags])
Create a random hash in hexadecimal.

This function returns a string representing a hash as a hexadecimal number. By default the function returns a number with 40 digits (i.e. a string with 40 characters), but the optional flag digits can specify exactly how many digits the hash will have.

Parameters:

  • flags (optional)

Returns:

    string

Usage:

  • chance.misc.hash() == "9f3cbf2466d865d82310b9b1e785401556daedce"
  • chance.misc.hash { digits = 8 } == "5d82310b"
chance.misc.rpg (notation)
Create an array of die rolls using Dungeons and Dragons notation.

This function returns an array of random numbers simulating the results of rolling dice of the kind found in most table-top RPGs such as Dungeons and Dragons. The argument to the function must be a string of the form #d# (case-insensitive) where each # is a number; the first represents the number of rolls to make, and the second represents the number of sides on the die, e.g. 3d6 returns an array with three numbers, each being the result of rolling a six-sided die.

Parameters:

  • notation

Returns:

    table The values of each die roll.

Usage:

  • chance.misc.rpg("1d8") == {4}
  • chance.misc.rpg("3d20") == {10, 4, 17}
chance.misc.d4 ()
Roll a 4-sided die.

Returns:

    number
chance.misc.d6 ()
Roll a 6-sided die.

Returns:

    number
chance.misc.d8 ()
Roll an 8-sided die.

Returns:

    number
chance.misc.d10 ()
Roll a 10-sided die.

Returns:

    number
chance.misc.d12 ()
Roll a 12-sided die.

Returns:

    number
chance.misc.d20 ()
Roll a 20-sided die.

Returns:

    number
chance.misc.d100 ()
Roll a 100-sided die.

Returns:

    number

Helpers

These are functions that help select random data from existing sources or define new random content generation functions.
chance.helpers.pick (array[, count])
Pick a random element from a given array.

This function takes a table with numeric keys and randomly returns a value assigned to one of those keys. The function optionally accepts an integer count which, if given, will return a new table containing that many values.

Parameters:

  • array
  • count (optional)

Returns:

    A single value from array or a table of the size count containing random values from array.
chance.helpers.pick_unique (array, count)
Pick a random collection of unique elements from an array.

This function is like chance.helpers.pick except that the count parameter is mandatory and the array that the function returns will not have any duplicate elements.

Parameters:

  • array table
  • count number

Returns:

    table

See also:

chance.helpers.shuffle (array)
Randomly shuffle the contents of an array.

This function takes an array, i.e. a table with only numeric indices, and returns a new table of the same size and with those same elements except in a random order. Naturally there is the possibility that the shuffled array will be randomly, coincidentally equal to the original.

Parameters:

  • array

Returns:

    table

Usage:

    chance.helpers.shuffle {"foo", "bar", "baz"} == {"bar", "foo", "baz"}
generated by LDoc 1.4.3 Last updated 2015-09-01 20:20:45