gen_sample() draws a uniform ordered sample of exactly size source
positions, without replacement. Its cardinality and sampling range do not
depend on the runner's size. The default draws permutations of the source.
Shrinking moves positions toward the beginning of the source, from left to
right. Each position tries the earliest position unused by its prefix, then
integer bisections toward its current position. Targets already in the prefix
are skipped; targets used later in the sample are swapped. Every child is
lexicographically smaller, with the same cardinality and distinct positions.
The terminal sample consists of the first size source entries in order.
Arguments
- values
An atomic vector or list, optionally named.
NULLis also accepted as an empty source. Classed vectors such as dates and factors must supportlength()and integer[subsetting that preserves their class and returns one entry per position. Arrays and data frames are not supported. Length must be at most.Machine$integer.max.- size
Fixed non-negative sample cardinality, at most
length(values).- min, max
Inclusive non-negative subsequence length bounds, with
min <= max <= length(values).
Details
gen_subsequence() chooses a length uniformly between min and
min(max, min + runner_size), then samples that many positions and sorts
them. It shrinks length toward min first, rebuilding a sample with a captured
seed as in gen_bind(), then shrinks positions. Source order and length
bounds are preserved. Different position shrinks can yield the same sorted
subsequence. Setting min = max = length(values) yields a constant.
Uniqueness concerns positions, not values: duplicated source entries can
appear together. Subsetting with [ preserves names and supported classes;
values themselves are not shrunk. Empty sources allow only empty selections.
Both generators have a list prototype, so gen_vector() nests their results.
For sampling with replacement, compose gen_element() and gen_vector().
References
R's sampling documentation
describes positional sampling and the hash algorithm used for small samples
from large populations. These generators use sample.int() without
constructing a vector of every source position.
The R Hedgehog manual
documents subsequences and sampling as distinct generator domains.
Examples
gen_example(gen_sample(letters, size = 3L))
#> [1] "y" "d" "g"
gen_example(gen_subsequence(letters, max = 5L))
#> character(0)
gen_example(gen_sample(seq_len(100000000L), size = 3L))
#> [1] 66608964 44492929 60941821