Package io.vavr.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.

See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    apply(Random random)
    Functional interface of this generator.
    default Arbitrary<T>
    Converts this Gen to an Arbitrary
    static Gen<Character>
    choose(char... characters)
    Chooses a char from all chars in the array
    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 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 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 extends Enum<T>>
    Gen<T>
    choose(Class<T> clazz)
    Chooses an enum value from all the enum constants defined in the enumerated type.
    static <T> Gen<T>
    choose(Iterable<T> values)
    Chooses a value from all values in the iterable
    static <T> Gen<T>
    choose(T... values)
    Chooses a value from all values in the array.
    static <T> Gen<T>
    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(Tuple2<Integer,Gen<T>>... generators)
    Chooses one of the given generators according to their frequency.
    static <T> Gen<T>
    frequency(Iterable<Tuple2<Integer,Gen<T>>> generators)
    Chooses one of the given generators according to their frequency.
    default Gen<T>
    intersperse(Gen<T> other)
    Intersperse values from this generator instance with those of another.
    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.
  • Method Details

    • 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 Gen<Character> choose(char... characters)
      Chooses a char from all chars in the array
      Parameters:
      characters - array with the characters to choose from
      Returns:
      A new array 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

      @SafeVarargs 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
    • intersperse

      default Gen<T> intersperse(Gen<T> other)
      Intersperse values from this generator instance with those of another.
      Parameters:
      other - another T generator to accept values from.
      Returns:
      A new T generator
    • 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