gen_sample: Sample source positions without replacement

In s7contract: Behavioral Contracts and Generative Laws for 'S7'

Sample source positions without replacement

Description

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.

Usage

gen_sample(values, size = length(values))

gen_subsequence(values, min = 0L, max = length(values))

Arguments

values	An atomic vector or list, optionally named. NULL is also accepted as an empty source. Classed vectors such as dates and factors must support length() 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().

Value

An S7 generator.

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))
gen_example(gen_subsequence(letters, max = 5L))
gen_example(gen_sample(seq_len(100000000L), size = 3L))

s7contract documentation built on Sept. 10, 2026, 1:09 a.m.