javaslang.test

Interface Gen<T>

Type Parameters:

T - type of generated objects

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface Gen<T>

Generators are the building blocks for providing arbitrary objects.

To ease the creation of Arbitraries, Gen is a FunctionalInterface which extends Function<Random, T>.

Gen objects are obtained via one of the methods choose, fail, frequency, of and oneOf.

Given Gen objects may be transformed using one of the methods filter, map and flatMap.

A simple way to obtain an Arbitrary of a Gen is to call arbitrary(). This will ignore the size hint of Arbitrary.

Since:

1.2.0

Author:

Daniel Dietrich

See Also:

Arbitrary

Field Summary

Fields

Modifier and Type	Field and Description
static int	FILTER_THRESHOLD

Method Summary

Modifier and Type	Method and Description
T	apply(Random random) Functional interface of this generator.
default Arbitrary<T>	arbitrary() Converts this Gen to an Arbitrary
static Gen<Character>	choose(char min, char max) Chooses a char between min and max, bounds inclusive and chars distributed according to the underlying random number generator.
static <T extends Enum<T>> Gen<T>	choose(Class<T> clazz) Chooses an enum value from all the enum constants defined in the enumerated type.
static Gen<Double>	choose(double min, double max) Chooses a double between min and max, bounds inclusive and numbers distributed according to the distribution of the underlying random number generator.
static Gen<Integer>	choose(int min, int max) Chooses an int between min and max, bounds inclusive and numbers distributed according to the distribution of the underlying random number generator.
static <T> Gen<T>	choose(Iterable<T> values) Chooses a value from all values in the iterable
static Gen<Long>	choose(long min, long max) Chooses a long between min and max, bounds inclusive and numbers distributed according to the distribution of the underlying random number generator.
static <T> Gen<T>	choose(T[] values) Chooses a value from all values in the array.
static <T> Gen<T>	fail() A failing generator which throws a RuntimeException("failed").
static <T> Gen<T>	fail(String message) A failing generator which throws a RuntimeException.
default Gen<T>	filter(Predicate<? super T> predicate) Returns a generator based on this generator which produces values that fulfill the given predicate.
default <U> Gen<U>	flatMap(Function<? super T,? extends Gen<? extends U>> mapper) Maps generated Ts to Us.
static <T> Gen<T>	frequency(Iterable<Tuple2<Integer,Gen<T>>> generators) Chooses one of the given generators according to their frequency.
static <T> Gen<T>	frequency(Tuple2<Integer,Gen<T>>... generators) Chooses one of the given generators according to their frequency.
default <U> Gen<U>	map(Function<? super T,? extends U> mapper) Maps generated Ts to Us.
static <T> Gen<T>	of(T t) A generator which constantly returns t.
static <T> Gen<T>	of(T seed, Function<? super T,? extends T> next)
static <T> Gen<T>	oneOf(Gen<T>... generators) Randomly chooses one of the given generators.
static <T> Gen<T>	oneOf(Iterable<Gen<T>> generators) Randomly chooses one of the given generators.
default Gen<T>	peek(Consumer<? super T> action)
default <U> U	transform(Function<? super Gen<T>,? extends U> f) Transforms this Gen.

Field Detail

FILTER_THRESHOLD

static final int FILTER_THRESHOLD

See Also:

Constant Field Values

Method Detail

apply

T apply(Random random)

Functional interface of this generator.

Parameters:

random - a random number generator

Returns:

A generated value of type T.

of

static <T> Gen<T> of(T t)

A generator which constantly returns t.

Type Parameters:

T - Type of t.

Parameters:

t - A value.

Returns:

A new T generator

of

static <T> Gen<T> of(T seed,
                     Function<? super T,? extends T> next)

choose

static Gen<Integer> choose(int min,
                           int max)

Chooses an int between min and max, bounds inclusive and numbers distributed according to the distribution of the underlying random number generator.

Note: min and max are internally swapped if min > max.

Parameters:

min - lower bound

max - upper bound

Returns:

A new int generator

choose

static Gen<Long> choose(long min,
                        long max)

Chooses a long between min and max, bounds inclusive and numbers distributed according to the distribution of the underlying random number generator.

Note: min and max are internally swapped if min > max.

Parameters:

min - lower bound

max - upper bound

Returns:

A new long generator

choose

static Gen<Double> choose(double min,
                          double max)

Chooses a double between min and max, bounds inclusive and numbers distributed according to the distribution of the underlying random number generator.

Note: min and max are internally swapped if min > max.

Parameters:

min - lower bound

max - upper bound

Returns:

A new double generator

Throws:

IllegalArgumentException - if min or max is infinite, min or max is not a number (NaN)

choose

static Gen<Character> choose(char min,
                             char max)

Chooses a char between min and max, bounds inclusive and chars distributed according to the underlying random number generator.

Note: min and max are internally swapped if min > max.

Parameters:

min - lower bound

max - upper bound

Returns:

A new char generator

choose

static <T extends Enum<T>> Gen<T> choose(Class<T> clazz)

Chooses an enum value from all the enum constants defined in the enumerated type.

Type Parameters:

T - type of enum constants

Parameters:

clazz - Enum class

Returns:

A new enum generator

choose

static <T> Gen<T> choose(T[] values)

Chooses a value from all values in the array.

Type Parameters:

T - value type

Parameters:

values - array with the values to choose from

Returns:

A new array generator

choose

static <T> Gen<T> choose(Iterable<T> values)

Chooses a value from all values in the iterable

Type Parameters:

T - value type

Parameters:

values - iterable with the values to choose from.

Returns:

A new iterable generator

fail

static <T> Gen<T> fail()

A failing generator which throws a RuntimeException("failed").

Type Parameters:

T - Type of values theoretically generated.

Returns:

A new generator which always fails with the message "failed"

fail

static <T> Gen<T> fail(String message)

A failing generator which throws a RuntimeException.

Type Parameters:

T - Type of values theoretically generated.

Parameters:

message - Message thrown.

Returns:

A new generator which always fails with the given message

frequency

@SafeVarargs
static <T> Gen<T> frequency(Tuple2<Integer,Gen<T>>... generators)

Chooses one of the given generators according to their frequency. Only generators with positive frequencies are used in returned generator.

Type Parameters:

T - Type to be generated

Parameters:

generators - A non-empty array of Tuples (frequency, generator)

Returns:

A new T generator

Throws:

NullPointerException - if generators is null

IllegalArgumentException - if generators doesn't contain any generator with positive frequency

frequency

static <T> Gen<T> frequency(Iterable<Tuple2<Integer,Gen<T>>> generators)

Chooses one of the given generators according to their frequency. Only generators with positive frequencies ares used in returned generator.

Type Parameters:

T - Type to be generated

Parameters:

generators - A non-empty traversable of Tuples (frequency, generator)

Returns:

A new T generator

Throws:

NullPointerException - if generators is null

IllegalArgumentException - if generators doesn't contain any generator with positive frequency

oneOf

@SafeVarargs
static <T> Gen<T> oneOf(Gen<T>... generators)

Randomly chooses one of the given generators.

Type Parameters:

T - Type to be generated

Parameters:

generators - A non-empty array of generators

Returns:

A new T generator

Throws:

NullPointerException - if generators is null

IllegalArgumentException - if generators is empty

oneOf

static <T> Gen<T> oneOf(Iterable<Gen<T>> generators)

Randomly chooses one of the given generators.

Type Parameters:

T - Type to be generated

Parameters:

generators - A non-empty Iterable of generators

Returns:

A new T generator

Throws:

NullPointerException - if generators is null

IllegalArgumentException - if generators is empty

arbitrary

default Arbitrary<T> arbitrary()

Converts this Gen to an Arbitrary

Returns:

An arbitrary which returns this generator regardless of the provided size hint n

filter

default Gen<T> filter(Predicate<? super T> predicate)

Returns a generator based on this generator which produces values that fulfill the given predicate.

Parameters:

predicate - A predicate

Returns:

A new generator

flatMap

default <U> Gen<U> flatMap(Function<? super T,? extends Gen<? extends U>> mapper)

Maps generated Ts to Us.

Type Parameters:

U - Type of generated objects of the new generator

Parameters:

mapper - A function that maps a generated T to a new generator which generates objects of type U.

Returns:

A new generator

map

default <U> Gen<U> map(Function<? super T,? extends U> mapper)

Maps generated Ts to Us.

Type Parameters:

U - Type of the mapped object

Parameters:

mapper - A function that maps a generated T to an object of type U.

Returns:

A new generator

peek

default Gen<T> peek(Consumer<? super T> action)

transform

default <U> U transform(Function<? super Gen<T>,? extends U> f)

Transforms this Gen.

Type Parameters:

U - Type of transformation result

Parameters:

f - A transformation

Returns:

An instance of type U

Throws:

NullPointerException - if f is null