Skip to content

Generator[T: T]

[Source]

A Generator is capable of generating random values of a certain type T given a source of Randomness and knows how to shrink or simplify values of that type.

When testing a property against one or more given Generators, those generators' generate methods are being called many times to generate sample values that are then used to validate the property.

When a failing sample is found, the PonyCheck engine is trying to find a smaller or more simple sample by shrinking it with shrink. If the generator did not provide any shrinked samples as a result of generate, its shrink method is called to obtain simpler results. PonyCheck obtains more shrunken samples until the property is not failing anymore. The last failing sample, which is considered the most simple one, is then reported to the user.

class box Generator[T: T] is
  GenObj[T] box

Implements

Constructors

create

[Source]

new ref create(
  gen: GenObj[T] box)
: Generator[T] ref^

Parameters

Returns

Public Functions

generate

[Source]

Let this generator generate a value given a source of Randomness.

Also allow for returning a value and pre-generated shrink results as a ValueAndShrink[T] instance, a tuple of (T^, Seq[T]). This helps propagating shrink results through all kinds of Generator combinators like filter, map and flat_map.

If implementing a custom Generator based on another one, with a Generator Combinator, you should use shrunken values returned by generate to also return shrunken values based on them.

If generating an example value is costly, it might be more efficient to simply return the generated value and only shrink in big steps or do no shrinking at all. If generating values is lightweight, shrunken values should also be returned.

fun box generate(
  rnd: Randomness ref)
: (T^ | (T^ , Iterator[T^] ref)) ?

Parameters

Returns

shrink

[Source]

Simplify the given value.

As the returned value can also be iso, it needs to be consumed and returned.

It is preferred to already return a ValueAndShrink from generate.

fun box shrink(
  t: T)
: (T^ , Iterator[T^] ref)

Parameters

  • t: T

Returns

generate_value

[Source]

fun box generate_value(
  rnd: Randomness ref)
: T^ ?

Parameters

Returns

  • T^ ?

generate_and_shrink

[Source]

fun box generate_and_shrink(
  rnd: Randomness ref)
: (T^ , Iterator[T^] ref) ?

Parameters

Returns

filter

[Source]

Apply predicate to the values generated by this Generator and only yields values for which predicate returns true.

Example:

let even_i32s =
  Generators.i32()
    .filter(
      {(t) => (t, ((t % 2) == 0)) })

fun box filter(
  predicate: {(T): (T^, Bool)}[T] box)
: Generator[T] box

Parameters

  • predicate: {(T): (T^, Bool)}[T] box

Returns

map[U: U]

[Source]

Apply fn to each value of this iterator and yield the results.

Example:

let single_code_point_string_gen =
  Generators.u32()
    .map[String]({(u) => String.from_utf32(u) })

fun box map[U: U](
  fn: {(T): U^}[T, U] box)
: Generator[U] box

Parameters

  • fn: {(T): U^}[T, U] box

Returns

flat_map[U: U]

[Source]

For each value of this generator, create a generator that is then combined.

fun box flat_map[U: U](
  fn: {(T): Generator[U]}[T, U] box)
: Generator[U] box

Parameters

  • fn: {(T): Generator[U]}[T, U] box

Returns

union[U: U]

[Source]

Create a generator that produces the value of this generator or the other with the same probability, returning a union type of this generator and the other one.

fun box union[U: U](
  other: Generator[U] box)
: Generator[(T | U)] box

Parameters

Returns

iter

[Source]

fun box iter(
  rnd: Randomness ref)
: Iterator[(T^ | (T^ , Iterator[T^] ref))] ref^

Parameters

Returns

value_iter

[Source]

fun box value_iter(
  rnd: Randomness ref)
: Iterator[T^] ref

Parameters

Returns

value_and_shrink_iter

[Source]

fun box value_and_shrink_iter(
  rnd: Randomness ref)
: Iterator[(T^ , Iterator[T^] ref)] ref

Parameters

Returns