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:
    Arbitrary
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      T apply​(java.util.Random random)
      Functional interface of this generator.
      default Arbitrary<T> arbitrary()
      Converts this Gen to an Arbitrary
      static Gen<java.lang.Character> choose​(char... characters)
      Chooses a char from all chars in the array
      static Gen<java.lang.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<java.lang.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<java.lang.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<java.lang.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 java.lang.Enum<T>>
      Gen<T>
      choose​(java.lang.Class<T> clazz)
      Chooses an enum value from all the enum constants defined in the enumerated type.
      static <T> Gen<T> choose​(java.lang.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> fail()
      A failing generator which throws a RuntimeException("failed").
      static <T> Gen<T> fail​(java.lang.String message)
      A failing generator which throws a RuntimeException.
      default Gen<T> filter​(java.util.function.Predicate<? super T> predicate)
      Returns a generator based on this generator which produces values that fulfill the given predicate.
      default <U> Gen<U> flatMap​(java.util.function.Function<? super T,​? extends Gen<? extends U>> mapper)
      Maps generated Ts to Us.
      static <T> Gen<T> frequency​(Tuple2<java.lang.Integer,​Gen<T>>... generators)
      Chooses one of the given generators according to their frequency.
      static <T> Gen<T> frequency​(java.lang.Iterable<Tuple2<java.lang.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​(java.util.function.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, java.util.function.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​(java.lang.Iterable<Gen<T>> generators)
      Randomly chooses one of the given generators.
      default Gen<T> peek​(java.util.function.Consumer<? super T> action)  
      default <U> U transform​(java.util.function.Function<? super Gen<T>,​? extends U> f)
      Transforms this Gen.
    • Method Detail

      • apply

        T apply​(java.util.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,
                             java.util.function.Function<? super T,​? extends T> next)
      • choose

        static Gen<java.lang.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<java.lang.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<java.lang.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:
        java.lang.IllegalArgumentException - if min or max is infinite, min or max is not a number (NaN)
      • choose

        static Gen<java.lang.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<java.lang.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 java.lang.Enum<T>> Gen<T> choose​(java.lang.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​(java.lang.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​(java.lang.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<java.lang.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:
        java.lang.NullPointerException - if generators is null
        java.lang.IllegalArgumentException - if generators doesn't contain any generator with positive frequency
      • frequency

        static <T> Gen<T> frequency​(java.lang.Iterable<Tuple2<java.lang.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:
        java.lang.NullPointerException - if generators is null
        java.lang.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:
        java.lang.NullPointerException - if generators is null
        java.lang.IllegalArgumentException - if generators is empty
      • oneOf

        static <T> Gen<T> oneOf​(java.lang.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:
        java.lang.NullPointerException - if generators is null
        java.lang.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​(java.util.function.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​(java.util.function.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​(java.util.function.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​(java.util.function.Consumer<? super T> action)
      • transform

        default <U> U transform​(java.util.function.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:
        java.lang.NullPointerException - if f is null