@spec and_then(t(a), (a -> t(b))) :: t(b) when a: value(), b: value()

Use this function to chain generators together when a generator is based on the value emitted by another generator.

In StreamData this funciton is called bind.

fun is a function that takes a value from the given generator and returns a generator.

@spec atom(max_length()) :: t(atom())

Generates alphanumeric atoms.

Warning! Be careful when generating random atoms as the BEAM has a limit on how many atoms can be created and it will crash if that limit is exceeded.

@spec binary(max_length()) :: t(binary())

Generates binaries.

max_length is used to cap the length of the binary. It defaults to :none and is the same as in list_of/2.

@spec boolean() :: t(boolean())

Genereates boolean values.

@spec byte() :: t(byte())

Generates bytes.

A byte is an integer between 0 and 255.

@spec check_all(t(value()), (value() -> nil)) :: :ok

check_all takes a Decorum struct and runs test_fn against the generated values.

This funciton will expand and eventually be called by a macro, but for now it's part of bootsrtapping the property testing functionality.

test_fn should behaive like a normal ExUnit test. It throws an error if a test fails. Use the assert or other test helper macros inside that function.

TODO: Create a Decorum.Error and raise that instead of ExUnit.AssertionError.

@spec constant(value()) :: t(value())

Create a generator that is not random and always returns the same value.

Similar to Enum.filter/2

Filters the generator. Returns only values for which fun returns a truthy value.

Use limit to specify how many times the generator should be called before raising an error.

@spec integer(Range.t()) :: t(integer())

Generates integers in the given range.

Range handling borrowed from StreamData

Shrinks toward zero within the range.

@spec list_of(t(value()), max_length()) :: t([value()])

Generates a list of values produced by the given generator.

max_length is used to cap the length of the list. It defaults to :none.

Uses a biased coin flip to determine if another value should be gerenated or the list should be terminated.

When max_length is a value other than :none, then the probablility of terminating the list increases as the list size approaches max_length.

When max_length is :none the probablility of generating another value is around 7/8.

@spec list_of_length(t(value()), non_neg_integer()) :: t([value()])

Generates a list of values produced by the given generator with a fixed length.

Shrinking will apply to the values within the list, but not the list itself because of the hardcoded length.

@spec map(t(a), (a -> b)) :: t(b) when a: value(), b: value()

Similar to Enum.map/2

Returns a generator where each element is the result of invoking fun on each corresponding element of the given generator.

@spec new(generator_fun(value())) :: t(value())

Helper for creating Decorum structs from a generator function.

@spec one_of([t(value())]) :: t(value())

Randomly selects one of the given generators.

generators must be a list.

@spec prng_values() :: t(non_neg_integer())

Creates a simple generator that outputs the values it gets from the prng.

Values will be 32-bit positive integers.

@spec stream(t(value()), Decorum.PRNG.t()) :: Enumerable.t(value())

Used to run a Decorum generator with a specific PRNG struct.

Takes a Decorum struct and a PRNG struct and returns a lazy Enumerable of generated values.

@spec uniform_integer(non_neg_integer()) :: t(non_neg_integer())

Generates an integer between 0 and max.

Currently only supports 32-bit values and is not truly uniform as the use of rem has a bias towards producing smaller numbers.

@spec zip([t(any())]) :: t(tuple())

Similar to Enum.zip/1

Zips corresponding elements from a finite collection of generators into a generator of tuples.

@spec zip(t(a), t(b)) :: t({a, b}) when a: value(), b: value()

Similar to Enum.zip/2

Zips corresponding elements from two generators into a generator of tuples.