fj.test

Class Gen<A>

java.lang.Object

fj.test.Gen<A>

public final class Gen<A>
extends java.lang.Object

A generator for values of the type of the given type parameter (A). Generation of a value accepts a general 'size' argument (integer), a random generator and returns an optional value of the type parameter. Several generators are provided, allowing various forms of composition of generators.

A user typically creates an arbitrary to return a generator using the 'combinator methods' below. For example, suppose a class Person:

class Person {
  final int age;
  final String name;
  final boolean male;

  Person(final int age, final String name, final boolean male) {
    this.age = age;
    this.name = name;
    this.male = male;
  }
}

In a case like this one, a user may create a generator over Person by invoking the bind(F) methods — in this case, bind(Gen , Gen , F) the one that takes two generator arguments}, since the class has one more than two fields (the bind method is invoked on a generator adding the extra one to the count as they are composed). The class fields are of types for which there exist generators (on Arbitrary so those can be used to compose a generator for Person:

static Arbitrary<Person> personArbitrary() {
  final Gen<Person> personGenerator = arbInteger.gen.bind(arbString().gen, arbBoolean().gen,
      // compose the generators
      {int age => {String name => {boolean male => new Person(age, name, male)}}};
  return arbitrary(personGenerator);
}

The example above uses Java 7 closure syntax. Here is the same example using objects instead:

static Arbitrary<Person> personArbitrary() {
  final Gen<Person> personGenerator = arbInteger.gen.bind(arbString.gen, arbBoolean.gen,
      // compose the generators
      new F<Integer, F<String, F<Boolean, Person>>>() {
        public F<String, F<Boolean, Person>> f(final Integer age) {
          return new F<String, F<Boolean, Person>>() {
            public F<Boolean, Person> f(final String name) {
              return new F<Boolean, Person>() {
                public Person f(final Boolean male) {
                  return new Person(age, name, male);
                }
              };
            }
          };
        }
      });
  return arbitrary(personGenerator);
}

Method Summary

Methods

Modifier and Type	Method and Description
<B> Gen<B>	apply(Gen<F<A,B>> gf) Function application within this generator to produce a new generator.
<B> Gen<B>	bind(F<A,Gen<B>> f) Binds the given function across this generator to produce a new generator.
<B,C> Gen<C>	bind(Gen<B> gb, F<A,F<B,C>> f) Binds the given function across this generator and the given generator to produce a new generator.
<B,C,D> Gen<D>	bind(Gen<B> gb, Gen<C> gc, F<A,F<B,F<C,D>>> f) Binds the given function across this generator and the given generators to produce a new generator.
<B,C,D,E> Gen<E>	bind(Gen<B> gb, Gen<C> gc, Gen<D> gd, F<A,F<B,F<C,F<D,E>>>> f) Binds the given function across this generator and the given generators to produce a new generator.
<B,C,D,E,F$> Gen<F$>	bind(Gen<B> gb, Gen<C> gc, Gen<D> gd, Gen<E> ge, F<A,F<B,F<C,F<D,F<E,F$>>>>> f) Binds the given function across this generator and the given generators to produce a new generator.
<B,C,D,E,F$,G> Gen<G>	bind(Gen<B> gb, Gen<C> gc, Gen<D> gd, Gen<E> ge, Gen<F$> gf, F<A,F<B,F<C,F<D,F<E,F<F$,G>>>>>> f) Binds the given function across this generator and the given generators to produce a new generator.
<B,C,D,E,F$,G,H> Gen<H>	bind(Gen<B> gb, Gen<C> gc, Gen<D> gd, Gen<E> ge, Gen<F$> gf, Gen<G> gg, F<A,F<B,F<C,F<D,F<E,F<F$,F<G,H>>>>>>> f) Binds the given function across this generator and the given generators to produce a new generator.
<B,C,D,E,F$,G,H,I> Gen<I>	bind(Gen<B> gb, Gen<C> gc, Gen<D> gd, Gen<E> ge, Gen<F$> gf, Gen<G> gg, Gen<H> gh, F<A,F<B,F<C,F<D,F<E,F<F$,F<G,F<H,I>>>>>>>> f) Binds the given function across this generator and the given generators to produce a new generator.
static Gen<java.lang.Double>	choose(double from, double to) Returns a generator that produces values between the given range (inclusive).
static Gen<java.lang.Integer>	choose(int from, int to) Returns a generator that produces values between the given range (inclusive).
static <A> Gen<A>	elements(A... as) Returns a generator that produces values from the given arguments.
static <A> Gen<A>	elemFrequency(List<P2<java.lang.Integer,A>> as) Returns a generator that produces values from the given frequency and value pairs.
static <A> Gen<A>	fail() Returns a generator that never returns a value.
Gen<A>	filter(F<A,java.lang.Boolean> f) Returns a generator that produces values that meet the given predicate.
void	foreach(java.lang.Integer i, Rand r, Effect<A> f) Executes a side-effect for each generated result using the given arguments.
Unit	foreach(java.lang.Integer i, Rand r, F<A,Unit> f) Executes a side-effect for each generated result using the given arguments.
static <A> Gen<A>	frequency(List<P2<java.lang.Integer,Gen<A>>> gs) Returns a generator that uses values from the given frequency and generator pairs.
static <A> Gen<A>	gen(F<java.lang.Integer,F<Rand,A>> f) Returns a generator that uses the given function.
A	gen(int i, Rand r) Applies the given size and random generator to produce a value.
static <A> Gen<A>	join(Gen<Gen<A>> g) Joins the generator of generators through a bind(F) operation.
static <A> Gen<List<A>>	listOf(Gen<A> g) Returns a generator of lists whose values come from the given generator.
static <A> Gen<List<A>>	listOf(Gen<A> g, int x) Returns a generator of lists whose values come from the given generator.
static <A> Gen<List<A>>	listOf1(Gen<A> g) Returns a generator of lists whose values come from the given generator.
<B> Gen<B>	map(F<A,B> f) Maps the given function across this generator.
static <A> Gen<A>	oneOf(List<Gen<A>> gs) Returns a generator that produces values from one of the given generators on subsequent requests.
static <A> Gen<A>	parameterised(F<java.lang.Integer,F<Rand,Gen<A>>> f) Constructs a generator that can access its construction arguments — size and random generator.
static <A> Gen<List<A>>	pick(int n, List<A> as) Returns a generator of lists that picks the given number of elements from the given list.
static <A,B> Gen<F<A,B>>	promote(F<A,Gen<B>> f) Promotes the given function to a generator for functions.
Gen<A>	resize(int s) Resizes this generator with the given size.
static <A> Gen<List<A>>	sequence(List<Gen<A>> gs) Sequence the given generators through a bind(F) operation.
static <A> Gen<List<A>>	sequenceN(int n, Gen<A> g) Sequences the given generator the given number of times through a bind(F) operation.
static <A> Gen<A>	sized(F<java.lang.Integer,Gen<A>> f) Constructs a generator that can access its size construction arguments.
static <A> Gen<List<A>>	someOf(List<A> as) Returns a generator of lists that produces some of the values of the given list.
static <A> Gen<A>	value(A a) Returns a generator that always produces the given value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

gen

public A gen(int i,
    Rand r)

Applies the given size and random generator to produce a value.

Parameters:

i - The size to use to produce the value.

r - The random generator to use to produce the value..

Returns:

A generated value.

map

public <B> Gen<B> map(F<A,B> f)

Maps the given function across this generator.

Parameters:

f - The function to map across this generator.

Returns:

A new generator after applying the mapping function.

filter

public Gen<A> filter(F<A,java.lang.Boolean> f)

Returns a generator that produces values that meet the given predicate.

Parameters:

f - The predicate to meet for the values produced by the generator.

Returns:

A generator that produces values that meet the given predicate.

foreach

public Unit foreach(java.lang.Integer i,
           Rand r,
           F<A,Unit> f)

Executes a side-effect for each generated result using the given arguments.

Parameters:

i - The size to generate the result to apply the side-effect to.

r - The random generator to generate the result to apply the side-effect to.

f - The side-effect to execute on the generated value.

Returns:

The unit value.

foreach

public void foreach(java.lang.Integer i,
           Rand r,
           Effect<A> f)

Executes a side-effect for each generated result using the given arguments.

Parameters:

i - The size to generate the result to apply the side-effect to.

r - The random generator to generate the result to apply the side-effect to.

f - The side-effect to execute on the generated value.

bind

public <B> Gen<B> bind(F<A,Gen<B>> f)

Binds the given function across this generator to produce a new generator.

Parameters:

f - The function to bind across this generator.

Returns:

A new generator after binding the given function.

bind

public <B,C> Gen<C> bind(Gen<B> gb,
                F<A,F<B,C>> f)

Binds the given function across this generator and the given generator to produce a new generator.

Parameters:

gb - The second generator to bind the given function across.

f - The function to bind across this generator and the given generator.

Returns:

A new generator after binding the given function.

bind

public <B,C,D> Gen<D> bind(Gen<B> gb,
                  Gen<C> gc,
                  F<A,F<B,F<C,D>>> f)

Binds the given function across this generator and the given generators to produce a new generator.

Parameters:

gb - The second generator to bind the given function across.

gc - The third generator to bind the given function across.

f - The function to bind across this generator and the given generators.

Returns:

A new generator after binding the given function.

bind

public <B,C,D,E> Gen<E> bind(Gen<B> gb,
                    Gen<C> gc,
                    Gen<D> gd,
                    F<A,F<B,F<C,F<D,E>>>> f)

Binds the given function across this generator and the given generators to produce a new generator.

Parameters:

gb - The second generator to bind the given function across.

gc - The third generator to bind the given function across.

gd - The fourth generator to bind the given function across.

f - The function to bind across this generator and the given generators.

Returns:

A new generator after binding the given function.

bind

public <B,C,D,E,F$> Gen<F$> bind(Gen<B> gb,
                        Gen<C> gc,
                        Gen<D> gd,
                        Gen<E> ge,
                        F<A,F<B,F<C,F<D,F<E,F$>>>>> f)

Binds the given function across this generator and the given generators to produce a new generator.

Parameters:

gb - The second generator to bind the given function across.

gc - The third generator to bind the given function across.

gd - The fourth generator to bind the given function across.

ge - The fifth generator to bind the given function across.

f - The function to bind across this generator and the given generators.

Returns:

A new generator after binding the given function.

bind

public <B,C,D,E,F$,G> Gen<G> bind(Gen<B> gb,
                         Gen<C> gc,
                         Gen<D> gd,
                         Gen<E> ge,
                         Gen<F$> gf,
                         F<A,F<B,F<C,F<D,F<E,F<F$,G>>>>>> f)

Binds the given function across this generator and the given generators to produce a new generator.

Parameters:

gb - The second generator to bind the given function across.

gc - The third generator to bind the given function across.

gd - The fourth generator to bind the given function across.

ge - The fifth generator to bind the given function across.

gf - The sixth generator to bind the given function across.

f - The function to bind across this generator and the given generators.

Returns:

A new generator after binding the given function.

bind

public <B,C,D,E,F$,G,H> Gen<H> bind(Gen<B> gb,
                           Gen<C> gc,
                           Gen<D> gd,
                           Gen<E> ge,
                           Gen<F$> gf,
                           Gen<G> gg,
                           F<A,F<B,F<C,F<D,F<E,F<F$,F<G,H>>>>>>> f)

Binds the given function across this generator and the given generators to produce a new generator.

Parameters:

gb - The second generator to bind the given function across.

gc - The third generator to bind the given function across.

gd - The fourth generator to bind the given function across.

ge - The fifth generator to bind the given function across.

gf - The sixth generator to bind the given function across.

gg - The seventh generator to bind the given function across.

f - The function to bind across this generator and the given generators.

Returns:

A new generator after binding the given function.

bind

public <B,C,D,E,F$,G,H,I> Gen<I> bind(Gen<B> gb,
                             Gen<C> gc,
                             Gen<D> gd,
                             Gen<E> ge,
                             Gen<F$> gf,
                             Gen<G> gg,
                             Gen<H> gh,
                             F<A,F<B,F<C,F<D,F<E,F<F$,F<G,F<H,I>>>>>>>> f)

Binds the given function across this generator and the given generators to produce a new generator.

Parameters:

gb - The second generator to bind the given function across.

gc - The third generator to bind the given function across.

gd - The fourth generator to bind the given function across.

ge - The fifth generator to bind the given function across.

gf - The sixth generator to bind the given function across.

gg - The seventh generator to bind the given function across.

gh - The eighth generator to bind the given function across.

f - The function to bind across this generator and the given generators.

Returns:

A new generator after binding the given function.

apply

public <B> Gen<B> apply(Gen<F<A,B>> gf)

Function application within this generator to produce a new generator.

Parameters:

gf - The generator over the function to apply to this generator.

Returns:

A new generator after function application.

resize

public Gen<A> resize(int s)

Resizes this generator with the given size.

Parameters:

s - The new size of the generator.

Returns:

A new generator that uses the given size.

gen

public static <A> Gen<A> gen(F<java.lang.Integer,F<Rand,A>> f)

Returns a generator that uses the given function.

Parameters:

f - The function to use for this generator.

Returns:

A new generator that uses the given function.

sequence

public static <A> Gen<List<A>> sequence(List<Gen<A>> gs)

Sequence the given generators through a bind(F) operation.

Parameters:

gs - The generators to sequence.

Returns:

A generator of lists after sequencing the given generators.

sequenceN

public static <A> Gen<List<A>> sequenceN(int n,
                         Gen<A> g)

Sequences the given generator the given number of times through a bind(F) operation.

Parameters:

n - The number of times to sequence the given generator.

g - The generator sequence.

Returns:

A generator of lists after sequencing the given generator.

parameterised

public static <A> Gen<A> parameterised(F<java.lang.Integer,F<Rand,Gen<A>>> f)

Constructs a generator that can access its construction arguments — size and random generator.

Parameters:

f - The function that constructs the generator with its arguments.

Returns:

A new generator.

sized

public static <A> Gen<A> sized(F<java.lang.Integer,Gen<A>> f)

Constructs a generator that can access its size construction arguments.

Parameters:

f - The function that constructs the generator with its size argument.

Returns:

A new generator.

value

public static <A> Gen<A> value(A a)

Returns a generator that always produces the given value.

Parameters:

a - The value to always produce.

Returns:

A generator that always produces the given value.

choose

public static Gen<java.lang.Integer> choose(int from,
                            int to)

Returns a generator that produces values between the given range (inclusive).

Parameters:

from - The value for the generator to produce values from.

to - The value for the generator to produce values from.

Returns:

A generator that produces values between the given range (inclusive).

choose

public static Gen<java.lang.Double> choose(double from,
                           double to)

Returns a generator that produces values between the given range (inclusive).

Parameters:

from - The value for the generator to produce values from.

to - The value for the generator to produce values from.

Returns:

A generator that produces v

fail

public static <A> Gen<A> fail()

Returns a generator that never returns a value.

Returns:

A generator that never returns a value.

join

public static <A> Gen<A> join(Gen<Gen<A>> g)

Joins the generator of generators through a bind(F) operation.

Parameters:

g - The generator of generators to join.

Returns:

A new generator after joining the given generator.

frequency

public static <A> Gen<A> frequency(List<P2<java.lang.Integer,Gen<A>>> gs)

Returns a generator that uses values from the given frequency and generator pairs. The returned generator will produce values from the generator in a pair with a higher frequency than a lower frequency generator.

Parameters:

gs - The pairs of frequency and generator from which to return values in the returned generator.

Returns:

A new generator that uses the given pairs of frequency and generator.

elemFrequency

public static <A> Gen<A> elemFrequency(List<P2<java.lang.Integer,A>> as)

Returns a generator that produces values from the given frequency and value pairs. The returned generator will produce the value with a higher frequency than a lower one.

Parameters:

as - The pairs of frequency and value from which to produce values.

Returns:

A new generator that uses the given pairs of frequency and value.

elements

public static <A> Gen<A> elements(A... as)

Returns a generator that produces values from the given arguments.

Parameters:

as - The values that the returned generator may produce.

Returns:

A generator that produces values from the given arguments.

oneOf

public static <A> Gen<A> oneOf(List<Gen<A>> gs)

Returns a generator that produces values from one of the given generators on subsequent requests.

Parameters:

gs - The list of generators to produce a value from.

Returns:

A generator that produces values from one of the given generators on subsequent requests.

listOf

public static <A> Gen<List<A>> listOf(Gen<A> g,
                      int x)

Returns a generator of lists whose values come from the given generator.

Parameters:

g - The generator to produce values from for the returned generator.

x - An adjuster of size to apply to the given generator when producing values.

Returns:

A generator of lists whose values come from the given generator.

listOf

public static <A> Gen<List<A>> listOf(Gen<A> g)

Returns a generator of lists whose values come from the given generator.

Parameters:

g - The generator to produce values from for the returned generator.

Returns:

A generator of lists whose values come from the given generator.

listOf1

public static <A> Gen<List<A>> listOf1(Gen<A> g)

Returns a generator of lists whose values come from the given generator.

Parameters:

g - The generator to produce values from for the returned generator.

Returns:

A generator of lists whose values come from the given generator.

pick

public static <A> Gen<List<A>> pick(int n,
                    List<A> as)

Returns a generator of lists that picks the given number of elements from the given list. If the given number is less than zero or greater than the length of the given list, then the returned generator will never produce a value.

Parameters:

n - The number of elements to pick from the given list.

as - The list from which to pick elements.

Returns:

A generator of lists that picks the given number of elements from the given list.

someOf

public static <A> Gen<List<A>> someOf(List<A> as)

Returns a generator of lists that produces some of the values of the given list.

Parameters:

as - The list from which to pick values.

Returns:

A generator of lists that produces some of the values of the given list.

promote

public static <A,B> Gen<F<A,B>> promote(F<A,Gen<B>> f)

Promotes the given function to a generator for functions.

Parameters:

f - The function to promote to a generator of functions.

Returns:

A generator for functions.