Gen (core 4.2 API)

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

All Methods Static Methods Instance Methods Concrete 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.
`Unit`	`foreach(java.lang.Integer i, Rand r, F<A,Unit> f)` Executes a side-effect for each generated result using the given arguments.
`void`	`foreachDoEffect(java.lang.Integer i, Rand r, Effect1<A> 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  Gen 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.
 - foreachDoEffect
```
public void foreachDoEffect(java.lang.Integer i,
 Rand r,
 Effect1<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  Gen bind(F<A,Gen> 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 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 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 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 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 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 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 bind(Gen 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  Gen 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> 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.

Class Gen<A>

Method Summary

Methods inherited from class java.lang.Object

Method Detail

gen

map

filter

foreach

foreachDoEffect

bind

bind

bind

bind

bind

bind

bind

bind

apply

resize

gen

sequence

sequenceN

parameterised

sized

value

choose

choose

fail

join

frequency

elemFrequency

elements

oneOf

listOf

listOf

listOf1

pick

someOf

promote