From 41246df83506ca606ab9ce96436596750a011ea4 Mon Sep 17 00:00:00 2001 From: Mitchell Yuwono Date: Mon, 21 Mar 2022 20:28:21 +1100 Subject: [PATCH] modify documentation for merging --- documentation/docs/proptest/genops.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/documentation/docs/proptest/genops.md b/documentation/docs/proptest/genops.md index 50154bcacca..0879d7bd7d9 100644 --- a/documentation/docs/proptest/genops.md +++ b/documentation/docs/proptest/genops.md @@ -54,23 +54,27 @@ val dependentArbs: Arb = Arb.of("foo", "bar").flatMap { prefix -> ## Merging -Two generators can be merged together, so that elements 0, 2, 4, ... are taken from the first generator, and elements 1, 3, 5, ... are taken from the second generator. +Two generators can be merged together, so that the resulting elements are equally sampled from both generators. ```kotlin val merged = arbA.merge(arbB) ``` -So with the following example: +So with the following example would have an equal chance to yield either `"a"` or `"b"` on each random sample: ```kotlin val a = arbitrary { "a" } val b = arbitrary { "b" } val ab = a.merge(b) -ab.take(10).forEach { println(it) } -``` -Would ouput `ababababab` +println(ab.take(1000).groupingBy { it }.eachCount()) +// {a=493, b=507} +``` +For merging more than two arbitraries, `Arb.choice` or `Arb.choose` might be more appropriate. For instance we can use: +- `Arb.choice(arbA, arbB, arbC)` for uniform sampling between `arbA`, `arbB` and `arbC`, +- or `Arb.choose(4 to arbA, 1 to arbB, 5 to arbC)` for a more granular control of frequency of each arbitrary. + In this example `arbA`, `arbB`, and `arbC` will be sampled 40%, 10%, and 50% of the time, respectively. ## Bind