elm-community / random-extra / Random.Extra

This module provides many common and general-purpose helper functions for core's Random library. You can find even more useful functions for a particular type in the other modules.

Values

bool : Random.Generator Basics.Bool

An unbiased generator of Bool values.

Maps

For map and mapN up through N=5, use the core library.

map6 : (a -> b -> c -> d -> e -> f -> g) -> Random.Generator a -> Random.Generator b -> Random.Generator c -> Random.Generator d -> Random.Generator e -> Random.Generator f -> Random.Generator g

Map a function of six arguments over six generators.

andMap : Random.Generator a -> Random.Generator (a -> b) -> Random.Generator b

Map over any number of generators.

type alias Person = -- some large record

randomPerson : Generator Person
randomPerson =
  map Person genFirstName
    |> andMap genLastName
    |> andMap genBirthday
    |> andMap genPhoneNumber
    |> andMap genAddress
    |> andMap genEmail

New Generators

oneIn : Basics.Int -> Random.Generator Basics.Bool

Produce True one-in-n times on average.

Do not pass a value less then one to this function.

flippedHeads =
    oneIn 2

rolled6 =
    oneIn 6

maybe : Random.Generator Basics.Bool -> Random.Generator a -> Random.Generator (Maybe a)

Produce Just a value on True, and Nothing on False.

You can use bool or oneIn n for the first argument.

result : Random.Generator Basics.Bool -> Random.Generator err -> Random.Generator val -> Random.Generator (Result err val)

Produce an Ok a value on True, and an Err value on False.

You can use bool or oneIn n for the first argument.

choice : a -> a -> Random.Generator a

Choose between two values with equal probability.

type Flip
    = Heads
    | Tails

coinFlip : Generator Flip
coinFlip =
    choice Heads Tails

Note that this function takes values, not generators. That's because it's meant to be a lightweight helper for a specific use. If you need to choose between two generators, use choices [gen1, gen2].

Working with Lists

sequence : List (Random.Generator a) -> Random.Generator (List a)

Start with a list of generators, and turn them into a generator that returns a list.

traverse : (a -> Random.Generator b) -> List a -> Random.Generator (List b)

Apply a function that returns a generator to each element of a list, and turn it into a generator that returns a list.

choices : Random.Generator a -> List (Random.Generator a) -> Random.Generator a

Create a generator that chooses a generator from a list of generators with equal probability.

We guarantee a nonempty list is passed by splitting it into two arguments.

frequency : ( Basics.Float, Random.Generator a ) -> List ( Basics.Float, Random.Generator a ) -> Random.Generator a

Create a generator that chooses a generator from a list of generators based on the provided weight. The likelihood of a given generator being chosen is its weight divided by the total weight (which doesn't have to equal 1).

We guarantee a nonempty list is passed by splitting it into two arguments.

sample : List a -> Random.Generator (Maybe a)

Given a list, choose an element uniformly at random. Nothing is only produced if the list is empty.

type Direction
    = North
    | South
    | East
    | West

direction : Generator Direction
direction =
    sample [ North, South, East, West ]
        |> map (Maybe.withDefault North)

combine : List (Random.Generator a) -> Random.Generator (List a)

Turn a list of generators into a generator of lists.

rangeLengthList : Basics.Int -> Basics.Int -> Random.Generator a -> Random.Generator (List a)

Generate a random list of random length given a minimum length and a maximum length.

Filtered Generators

filter : (a -> Basics.Bool) -> Random.Generator a -> Random.Generator a

Filter a generator so that all generated values satisfy the given predicate.

evens : Generator Int
evens =
    filter (\i -> i % 2 == 0) (int minInt maxInt)

Warning: If the predicate is unsatisfiable, the generator will not terminate, your application will crash with a stack overflow, and you will be sad. You should also avoid predicates that are merely very difficult to satisfy.

badCrashingGenerator =
    filter (\_ -> False) anotherGenerator

likelyCrashingGenerator =
    filter (\i -> i % 2000 == 0) (int minInt maxInt)

andThenN

These functions are like mapN except the function you pass in does not return an exact value, but instead another generator. That means you can take in several random arguments to drive more randomness.

andThen2 : (a -> b -> Random.Generator c) -> Random.Generator a -> Random.Generator b -> Random.Generator c

andThen3 : (a -> b -> c -> Random.Generator d) -> Random.Generator a -> Random.Generator b -> Random.Generator c -> Random.Generator d

andThen4 : (a -> b -> c -> d -> Random.Generator e) -> Random.Generator a -> Random.Generator b -> Random.Generator c -> Random.Generator d -> Random.Generator e

andThen5 : (a -> b -> c -> d -> e -> Random.Generator f) -> Random.Generator a -> Random.Generator b -> Random.Generator c -> Random.Generator d -> Random.Generator e -> Random.Generator f

andThen6 : (a -> b -> c -> d -> e -> f -> Random.Generator g) -> Random.Generator a -> Random.Generator b -> Random.Generator c -> Random.Generator d -> Random.Generator e -> Random.Generator f -> Random.Generator g