Generators¶

Convenience combinators and factories for common types and kind of Generators.

primitive val Generators

Constructors¶

create¶

[Source]

new val create()
: Generators val^

Returns¶

Generators val^

Public Functions¶

unit[T: T]¶

[Source]

Generate a reference to the same value over and over again.

This reference will be of type box->T and not just T as this generator will need to keep a reference to the given value.

fun box unit[T: T](
  t: T,
  do_shrink: Bool val = false)
: Generator[box->T] box

Parameters¶

t: T
do_shrink: Bool val = false

Returns¶

Generator[box->T] box

none[T: None val]¶

[Source]

fun box none[T: None val]()
: Generator[(T | None val)] box

Returns¶

Generator[(T | None val)] box

repeatedly[T: T]¶

[Source]

Generate values by calling the lambda f repeatedly, once for every invocation of generate.

f needs to return an ephemeral type T^, that means in most cases it needs to consume its returned value. Otherwise we would end up with an alias for T which is T!. (e.g. String iso would be returned as String iso!, which aliases as a String tag).

Example:

Generators.repeatedly[Writer]({(): Writer^ =>
  let writer = Writer.>write("consume me, please")
  consume writer
})

fun box repeatedly[T: T](
  f: {(): T^ ?}[T] box)
: Generator[T] box

Parameters¶

f: {(): T^ ?}[T] box

Returns¶

Generator[T] box

seq_of[T: T, S: Seq[T] ref]¶

[Source]

Create a Seq from the values of the given Generator with an optional minimum and maximum size.

Defaults are 0 and 100, respectively.

fun box seq_of[T: T, S: Seq[T] ref](
  gen: Generator[T] box,
  min: USize val = 0,
  max: USize val = 100)
: Generator[S] box

Parameters¶

gen: Generator[T] box
min: USize val = 0
max: USize val = 100

Returns¶

Generator[S] box

iso_seq_of[T: Any #send, S: Seq[T] iso]¶

[Source]

Generate a Seq[T] where T must be sendable (i.e. it must have a reference capability of either tag, val, or iso).

The constraint of the elements being sendable stems from the fact that there is no other way to populate the iso seq if the elements might be non-sendable (i.e. ref), as then the seq would leak references via its elements.

fun box iso_seq_of[T: Any #send, S: Seq[T] iso](
  gen: Generator[T] box,
  min: USize val = 0,
  max: USize val = 100)
: Generator[S] box

Parameters¶

gen: Generator[T] box
min: USize val = 0
max: USize val = 100

Returns¶

Generator[S] box

array_of[T: T]¶

[Source]

fun box array_of[T: T](
  gen: Generator[T] box,
  min: USize val = 0,
  max: USize val = 100)
: Generator[Array[T] ref] box

Parameters¶

gen: Generator[T] box
min: USize val = 0
max: USize val = 100

Returns¶

Generator[Array[T] ref] box

shuffled_array_gen[T: T]¶

[Source]

fun box shuffled_array_gen[T: T](
  gen: Generator[Array[T] ref] box)
: Generator[Array[T] ref] box

Parameters¶

gen: Generator[Array[T] ref] box

Returns¶

Generator[Array[T] ref] box

shuffled_iter[T: T]¶

[Source]

fun box shuffled_iter[T: T](
  array: Array[T] ref)
: Generator[Iterator[this->T!] ref] box

Parameters¶

array: Array[T] ref

Returns¶

Generator[Iterator[this->T!] ref] box

list_of[T: T]¶

[Source]

fun box list_of[T: T](
  gen: Generator[T] box,
  min: USize val = 0,
  max: USize val = 100)
: Generator[List[T] ref] box

Parameters¶

gen: Generator[T] box
min: USize val = 0
max: USize val = 100

Returns¶

Generator[List[T] ref] box

set_of[T: (Hashable #read & Equatable[T] #read)]¶

[Source]

Create a generator for Set filled with values of the given generator gen. The returned sets will have a size up to max, but tend to have fewer than max depending on the source generator gen.

E.g. if the given generator is for U8 values and max is set to 1024, the set will only ever be of size 256 max.

Also for efficiency purposes and to not loop forever, this generator will only try to add at most max values to the set. If there are duplicates, the set won't grow.

fun box set_of[T: (Hashable #read & Equatable[T] #read)](
  gen: Generator[T] box,
  max: USize val = 100)
: Generator[HashSet[T, HashEq[T] val] ref] box

Parameters¶

gen: Generator[T] box
max: USize val = 100

Returns¶

Generator[HashSet[T, HashEq[T] val] ref] box

set_is_of[T: T]¶

[Source]

Create a generator for SetIs filled with values of the given generator gen. The returned SetIs will have a size up to max, but tend to have fewer entries depending on the source generator gen.

E.g. if the given generator is for U8 values and max is set to 1024 the set will only ever be of size 256 max.

Also for efficiency purposes and to not loop forever, this generator will only try to add at most max values to the set. If there are duplicates, the set won't grow.

fun box set_is_of[T: T](
  gen: Generator[T] box,
  max: USize val = 100)
: Generator[HashSet[T, HashIs[T!] val] ref] box

Parameters¶

gen: Generator[T] box
max: USize val = 100

Returns¶

Generator[HashSet[T, HashIs[T!] val] ref] box

map_of[K: (Hashable #read & Equatable[K] #read), V: V]¶

[Source]

Create a generator for Map from a generator of key-value tuples. The generated maps will have a size up to max, but tend to have fewer entries depending on the source generator gen.

If the generator generates key-value pairs with duplicate keys (based on structural equality), the pair that is generated later will overwrite earlier entries in the map.

fun box map_of[K: (Hashable #read & Equatable[K] #read), V: V](
  gen: Generator[(K , V)] box,
  max: USize val = 100)
: Generator[HashMap[K, V, HashEq[K] val] ref] box

Parameters¶

gen: Generator[(K , V)] box
max: USize val = 100

Returns¶

Generator[HashMap[K, V, HashEq[K] val] ref] box

map_is_of[K: K, V: V]¶

[Source]

Create a generator for MapIs from a generator of key-value tuples. The generated maps will have a size up to max, but tend to have fewer entries depending on the source generator gen.

If the generator generates key-value pairs with duplicate keys (based on identity), the pair that is generated later will overwrite earlier entries in the map.

fun box map_is_of[K: K, V: V](
  gen: Generator[(K , V)] box,
  max: USize val = 100)
: Generator[HashMap[K, V, HashIs[K] val] ref] box

Parameters¶

gen: Generator[(K , V)] box
max: USize val = 100

Returns¶

Generator[HashMap[K, V, HashIs[K] val] ref] box

one_of[T: T]¶

[Source]

Generate a random value from the given ReadSeq. This generator will generate nothing if the given xs is empty.

Generators created with this method do not support shrinking. If do_shrink is set to true, it will return the same value for each shrink round. Otherwise it will return nothing.

fun box one_of[T: T](
  xs: ReadSeq[T] box,
  do_shrink: Bool val = false)
: Generator[box->T] box

Parameters¶

xs: ReadSeq[T] box
do_shrink: Bool val = false

Returns¶

Generator[box->T] box

one_of_safe[T: T]¶

[Source]

Version of one_of that will error if xs is empty.

fun box one_of_safe[T: T](
  xs: ReadSeq[T] box,
  do_shrink: Bool val = false)
: Generator[box->T] box ?

Parameters¶

xs: ReadSeq[T] box
do_shrink: Bool val = false

Returns¶

Generator[box->T] box ?

frequency[T: T]¶

[Source]

Choose a value of one of the given Generators, while controlling the distribution with the associated weights.

The weights are of type USize and control how likely a value is chosen. The likelihood of a value v to be chosen is weight_v / weights_sum. If all weighted_generators have equal size the distribution will be uniform.

Example of a generator to output odd U8 values twice as likely as even ones:

Generators.frequency[U8]([
  (1, Generators.u8().filter({(u) => (u, (u % 2) == 0 }))
  (2, Generators.u8().filter({(u) => (u, (u % 2) != 0 }))
])

fun box frequency[T: T](
  weighted_generators: ReadSeq[(USize val , Generator[T] box)] box)
: Generator[T] box

Parameters¶

weighted_generators: ReadSeq[(USize val , Generator[T] box)] box

Returns¶

Generator[T] box

frequency_safe[T: T]¶

[Source]

Version of frequency that errors if the given weighted_generators is empty.

fun box frequency_safe[T: T](
  weighted_generators: ReadSeq[(USize val , Generator[T] box)] box)
: Generator[T] box ?

Parameters¶

weighted_generators: ReadSeq[(USize val , Generator[T] box)] box

Returns¶

Generator[T] box ?

zip2[T1: T1, T2: T2]¶

[Source]

Zip two generators into a generator of a 2-tuple containing the values generated by both generators.

fun box zip2[T1: T1, T2: T2](
  gen1: Generator[T1] box,
  gen2: Generator[T2] box)
: Generator[(T1 , T2)] box

Parameters¶

gen1: Generator[T1] box
gen2: Generator[T2] box

Returns¶

Generator[(T1 , T2)] box

zip3[T1: T1, T2: T2, T3: T3]¶

[Source]

Zip three generators into a generator of a 3-tuple containing the values generated by those three generators.

fun box zip3[T1: T1, T2: T2, T3: T3](
  gen1: Generator[T1] box,
  gen2: Generator[T2] box,
  gen3: Generator[T3] box)
: Generator[(T1 , T2 , T3)] box

Parameters¶

gen1: Generator[T1] box
gen2: Generator[T2] box
gen3: Generator[T3] box

Returns¶

Generator[(T1 , T2 , T3)] box

zip4[T1: T1, T2: T2, T3: T3, T4: T4]¶

[Source]

Zip four generators into a generator of a 4-tuple containing the values generated by those four generators.

fun box zip4[T1: T1, T2: T2, T3: T3, T4: T4](
  gen1: Generator[T1] box,
  gen2: Generator[T2] box,
  gen3: Generator[T3] box,
  gen4: Generator[T4] box)
: Generator[(T1 , T2 , T3 , T4)] box

Parameters¶

gen1: Generator[T1] box
gen2: Generator[T2] box
gen3: Generator[T3] box
gen4: Generator[T4] box

Returns¶

Generator[(T1 , T2 , T3 , T4)] box

map2[T1: T1, T2: T2, T3: T3]¶

[Source]

Convenience combinator for mapping 2 generators into 1.

fun box map2[T1: T1, T2: T2, T3: T3](
  gen1: Generator[T1] box,
  gen2: Generator[T2] box,
  fn: {(T1, T2): T3^}[T1, T2, T3] ref)
: Generator[T3] box

Parameters¶

gen1: Generator[T1] box
gen2: Generator[T2] box
fn: {(T1, T2): T3^}[T1, T2, T3] ref

Returns¶

Generator[T3] box

map3[T1: T1, T2: T2, T3: T3, T4: T4]¶

[Source]

Convenience combinator for mapping 3 generators into 1.

fun box map3[T1: T1, T2: T2, T3: T3, T4: T4](
  gen1: Generator[T1] box,
  gen2: Generator[T2] box,
  gen3: Generator[T3] box,
  fn: {(T1, T2, T3): T4^}[T1, T2, T3, T4] ref)
: Generator[T4] box

Parameters¶

gen1: Generator[T1] box
gen2: Generator[T2] box
gen3: Generator[T3] box
fn: {(T1, T2, T3): T4^}[T1, T2, T3, T4] ref

Returns¶

Generator[T4] box

map4[T1: T1, T2: T2, T3: T3, T4: T4, T5: T5]¶

[Source]

Convenience combinator for mapping 4 generators into 1.

fun box map4[T1: T1, T2: T2, T3: T3, T4: T4, T5: T5](
  gen1: Generator[T1] box,
  gen2: Generator[T2] box,
  gen3: Generator[T3] box,
  gen4: Generator[T4] box,
  fn: {(T1, T2, T3, T4): T5^}[T1, T2, T3, T4, T5] ref)
: Generator[T5] box

Parameters¶

gen1: Generator[T1] box
gen2: Generator[T2] box
gen3: Generator[T3] box
gen4: Generator[T4] box
fn: {(T1, T2, T3, T4): T5^}[T1, T2, T3, T4, T5] ref

Returns¶

Generator[T5] box

bool¶

[Source]

Create a generator of bool values.

fun box bool()
: Generator[Bool val] box

Returns¶

Generator[Bool val] box

u8¶

[Source]

Create a generator for U8 values.

fun box u8(
  min: U8 val = call,
  max: U8 val = call)
: Generator[U8 val] box

Parameters¶

min: U8 val = call
max: U8 val = call

Returns¶

Generator[U8 val] box

u16¶

[Source]

create a generator for U16 values

fun box u16(
  min: U16 val = call,
  max: U16 val = call)
: Generator[U16 val] box

Parameters¶

min: U16 val = call
max: U16 val = call

Returns¶

Generator[U16 val] box

u32¶

[Source]

Create a generator for U32 values.

fun box u32(
  min: U32 val = call,
  max: U32 val = call)
: Generator[U32 val] box

Parameters¶

min: U32 val = call
max: U32 val = call

Returns¶

Generator[U32 val] box

u64¶

[Source]

Create a generator for U64 values.

fun box u64(
  min: U64 val = call,
  max: U64 val = call)
: Generator[U64 val] box

Parameters¶

min: U64 val = call
max: U64 val = call

Returns¶

Generator[U64 val] box

u128¶

[Source]

Create a generator for U128 values.

fun box u128(
  min: U128 val = call,
  max: U128 val = call)
: Generator[U128 val] box

Parameters¶

min: U128 val = call
max: U128 val = call

Returns¶

Generator[U128 val] box

usize¶

[Source]

Create a generator for USize values.

fun box usize(
  min: USize val = call,
  max: USize val = call)
: Generator[USize val] box

Parameters¶

min: USize val = call
max: USize val = call

Returns¶

Generator[USize val] box

ulong¶

[Source]

Create a generator for ULong values.

fun box ulong(
  min: ULong val = call,
  max: ULong val = call)
: Generator[ULong val] box

Parameters¶

min: ULong val = call
max: ULong val = call

Returns¶

Generator[ULong val] box

i8¶

[Source]

Create a generator for I8 values.

fun box i8(
  min: I8 val = call,
  max: I8 val = call)
: Generator[I8 val] box

Parameters¶

min: I8 val = call
max: I8 val = call

Returns¶

Generator[I8 val] box

i16¶

[Source]

Create a generator for I16 values.

fun box i16(
  min: I16 val = call,
  max: I16 val = call)
: Generator[I16 val] box

Parameters¶

min: I16 val = call
max: I16 val = call

Returns¶

Generator[I16 val] box

i32¶

[Source]

Create a generator for I32 values.

fun box i32(
  min: I32 val = call,
  max: I32 val = call)
: Generator[I32 val] box

Parameters¶

min: I32 val = call
max: I32 val = call

Returns¶

Generator[I32 val] box

i64¶

[Source]

Create a generator for I64 values.

fun box i64(
  min: I64 val = call,
  max: I64 val = call)
: Generator[I64 val] box

Parameters¶

min: I64 val = call
max: I64 val = call

Returns¶

Generator[I64 val] box

i128¶

[Source]

Create a generator for I128 values.

fun box i128(
  min: I128 val = call,
  max: I128 val = call)
: Generator[I128 val] box

Parameters¶

min: I128 val = call
max: I128 val = call

Returns¶

Generator[I128 val] box

ilong¶

[Source]

Create a generator for ILong values.

fun box ilong(
  min: ILong val = call,
  max: ILong val = call)
: Generator[ILong val] box

Parameters¶

min: ILong val = call
max: ILong val = call

Returns¶

Generator[ILong val] box

isize¶

[Source]

Create a generator for ISize values.

fun box isize(
  min: ISize val = call,
  max: ISize val = call)
: Generator[ISize val] box

Parameters¶

min: ISize val = call
max: ISize val = call

Returns¶

Generator[ISize val] box

byte_string¶

[Source]

Create a generator for strings generated from the bytes returned by the generator gen, with a minimum length of min (default: 0) and a maximum length of max (default: 100).

fun box byte_string(
  gen: Generator[U8 val] box,
  min: USize val = 0,
  max: USize val = 100)
: Generator[String val] box

Parameters¶

gen: Generator[U8 val] box
min: USize val = 0
max: USize val = 100

Returns¶

Generator[String val] box

ascii¶

[Source]

Create a generator for strings withing the given range, with a minimum length of min (default: 0) and a maximum length of max (default: 100).

fun box ascii(
  min: USize val = 0,
  max: USize val = 100,
  range: (ASCIINUL val | ASCIIDigits val | ASCIIWhiteSpace val | 
    ASCIIPunctuation val | ASCIILettersLower val | ASCIILettersUpper val | 
    ASCIILetters val | ASCIIPrintable val | ASCIINonPrintable val | 
    ASCIIAll val | ASCIIAllWithNUL val) = reference)
: Generator[String val] box

Create a generator for strings of printable ASCII characters, with a minimum length of min (default: 0) and a maximum length of max (default: 100).

fun box ascii_printable(
  min: USize val = 0,
  max: USize val = 100)
: Generator[String val] box

Parameters¶

min: USize val = 0
max: USize val = 100

Returns¶

Generator[String val] box

ascii_numeric¶

[Source]

Create a generator for strings of numeric ASCII characters, with a minimum length of min (default: 0) and a maximum length of max (default: 100).

fun box ascii_numeric(
  min: USize val = 0,
  max: USize val = 100)
: Generator[String val] box

Parameters¶

min: USize val = 0
max: USize val = 100

Returns¶

Generator[String val] box

ascii_letters¶

[Source]

Create a generator for strings of ASCII letters, with a minimum length of min (default: 0) and a maximum length of max (default: 100).

fun box ascii_letters(
  min: USize val = 0,
  max: USize val = 100)
: Generator[String val] box

Parameters¶

min: USize val = 0
max: USize val = 100

Returns¶

Generator[String val] box

utf32_codepoint_string¶

[Source]

Create a generator for strings from a generator of unicode codepoints, with a minimum length of min codepoints (default: 0) and a maximum length of max codepoints (default: 100).

Note that the byte length of the generated string can be up to 4 times the size in code points.

fun box utf32_codepoint_string(
  gen: Generator[U32 val] box,
  min: USize val = 0,
  max: USize val = 100)
: Generator[String val] box

Parameters¶

gen: Generator[U32 val] box
min: USize val = 0
max: USize val = 100

Returns¶

Generator[String val] box

unicode¶

[Source]

Create a generator for unicode strings, with a minimum length of min codepoints (default: 0) and a maximum length of max codepoints (default: 100).

Note that the byte length of the generated string can be up to 4 times the size in code points.

fun box unicode(
  min: USize val = 0,
  max: USize val = 100)
: Generator[String val] box

Parameters¶

min: USize val = 0
max: USize val = 100

Returns¶

Generator[String val] box

unicode_bmp¶

[Source]

Create a generator for unicode strings from the basic multilingual plane only, with a minimum length of min codepoints (default: 0) and a maximum length of max codepoints (default: 100).

Note that the byte length of the generated string can be up to 4 times the size in code points.

fun box unicode_bmp(
  min: USize val = 0,
  max: USize val = 100)
: Generator[String val] box

Parameters¶

min: USize val = 0
max: USize val = 100

Returns¶

Generator[String val] box

eq¶

[Source]

fun box eq(
  that: Generators val)
: Bool val

Parameters¶

that: Generators val

Returns¶

Bool val

ne¶

[Source]

fun box ne(
  that: Generators val)
: Bool val

Parameters¶

that: Generators val

Returns¶

Bool val