Improve doc for Gen.pick #417
Conversation
doc/UserGuide.md
Outdated
|
|
||
| Note that `Gen.someOf`, `Gen.atLeastOne`, and `Gen.pick` only randomly | ||
| select elements, they do not generate permutations of the selected | ||
| elements in different orders. Selection is random, but the order is |
There was a problem hiding this comment.
Observed behavior of pick is that pick(2, 1 to 10) generates (for large samples) 73 distinct 2-lists, out of a total of 90 possible. 73 < 90 is consistent with the remark that pick does not, in general, permute all its results.
But since there are only 45 (=10*9/2) distinct 2-sets from (1 to 10), 73 > 45 implies that pick does permute some of its results, so the order is not deterministic. For instance List(4, 5) and List(5, 4) are both generated by pick(2, 1 to 10).
There was a problem hiding this comment.
True, using the word "deterministic" is confusing. I'll remove it.
ashawley
force-pushed
the
doc-shuffle-pick
branch
from
193ad44 to
e9dcb28
Compare
ashawley
force-pushed
the
doc-shuffle-pick
branch
from
e9dcb28 to
4149432
Compare
Gen.pick, Gen.someOf, and Gen.atLeastOne will give a randomly chosen subset of elements, but not in a random order. This is because Gen.pick is implemented with reservoir sampling but without a shuffle operation. Adding shuffling might be possible, but it could impact performance and would violate the "do one thing well" principle of Gen.pick. For now, just document the situation that results aren't permuted in the User Guide and in the API docs.
ashawley
force-pushed
the
doc-shuffle-pick
branch
from
4149432 to
f31c3ed
Compare
|
This issue came up again in the Gitter channel, yesterday. The Scaladoc changes won't help right away, not until a new release is published, but the User Guide would be updated right away. The latter probably has a better chance of getting noticed. |
This is in response to concerns raised about
Gen.pickin #355.Gen.pick,Gen.someOf, andGen.atLeastOnewill give a randomly chosen subset of elements, but not in a random order. This is becauseGen.pickis implemented with reservoir sampling but without a shuffle operation. Adding shuffling might be possible, but it could impact performance and would violate the "do one thing well" principle ofGen.pick.For now, just document the situation that results aren't permuted in the User Guide and in the API docs.