Skip to content

Generators

[Source]

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

primitive val Generators

Constructors

create

[Source]

new val create()
: Generators val^

Returns


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


none[T: None val]

[Source]

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

Returns


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


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

Returns


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

Returns


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

Returns


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

Returns


shuffled_iter[T: T]

[Source]

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

Parameters

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


bool

[Source]

Create a generator of bool values.

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

Returns


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


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


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


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


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


usize

[Source]

Create a generator for USize values.

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

Parameters

Returns


ulong

[Source]

Create a generator for ULong values.

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

Parameters

Returns


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


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


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


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


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


ilong

[Source]

Create a generator for ILong values.

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

Parameters

Returns


isize

[Source]

Create a generator for ISize values.

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

Parameters

Returns


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

Returns


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

Parameters

Returns


ascii_printable

[Source]

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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


eq

[Source]

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

Parameters

Returns


ne

[Source]

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

Parameters

Returns