Struct VariableRangeGenerator 

pub struct VariableRangeGenerator { /* private fields */ }

Generates unsigneds sampled from ranges. A single generator can sample from different ranges of different types.

This struct is created by VariableRangeGenerator::new; see its documentation for more.

Implementations

impl VariableRangeGenerator

pub fn new(seed: Seed) -> Self

Generates unsigneds sampled from ranges. A single generator can sample from different ranges of different types.

If you only need to generate values from a single range, it is slightly more efficient to use random_unsigned_bit_chunks, random_unsigneds_less_than, random_unsigned_range, or random_unsigned_inclusive_range.

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::random::VariableRangeGenerator;
use malachite_base::random::EXAMPLE_SEED;

let mut generator = VariableRangeGenerator::new(EXAMPLE_SEED);
assert_eq!(generator.next_bit_chunk::<u16>(10), 881);
assert_eq!(generator.next_less_than::<u8>(100), 34);
assert_eq!(generator.next_in_range::<u32>(10, 20), 16);
assert_eq!(generator.next_in_inclusive_range::<u64>(10, 20), 14);

pub fn next_bool(&mut self) -> bool

Uniformly generates a bool.

$$ $P(\text{false}) = P(\text{true}) = \frac{1}{2}$. $$

Worst-case complexity

Constant time and additional memory.

Examples

use malachite_base::num::random::VariableRangeGenerator;
use malachite_base::random::EXAMPLE_SEED;

let mut xs = Vec::with_capacity(10);
let mut generator = VariableRangeGenerator::new(EXAMPLE_SEED);
for _ in 0..10 {
    xs.push(generator.next_bool());
}
assert_eq!(
    xs,
    &[true, false, true, false, true, true, true, true, true, false]
);

pub fn next_bit_chunk<T: PrimitiveUnsigned>(&mut self, chunk_size: u64) -> T

Uniformly generates an unsigned integer with up to some number of bits.

$$ P(x) = \begin{cases} 2^{-c} & \text{if} \quad 0 \leq x < 2^c, \\ 0 & \text{if} \quad \text{otherwise,} \end{cases} $$ where $c$ is chunk_size.

Worst-case complexity

$T(n) = O(n)$

$M(n) = O(1)$

where $T$ is time, $M$ is additional memory, and $n$ is chunk_size.

Panics

Panics if chunk_size is zero or greater than the width of the type.

Examples

use malachite_base::num::random::VariableRangeGenerator;
use malachite_base::random::EXAMPLE_SEED;

let mut xs = Vec::with_capacity(10);
let mut generator = VariableRangeGenerator::new(EXAMPLE_SEED);
for _ in 0..10 {
    xs.push(generator.next_bit_chunk::<u8>(3));
}
assert_eq!(xs, &[1, 6, 5, 7, 6, 3, 1, 2, 4, 5]);

pub fn next_less_than<T: PrimitiveUnsigned>(&mut self, limit: T) -> T

Uniformly generates a random unsigned integer less than a positive limit.

$$ P(x) = \begin{cases} \frac{1}{\ell} & \text{if} \quad x < \ell \\ 0 & \text{otherwise} \end{cases} $$ where $\ell$ is limit.

Expected complexity

$T(n) = O(n)$

$M(n) = O(1)$

where $T$ is time, $M$ is additional memory, and $n$ is limit.significant_bits(). Each rejection-sampling trial rejects with probability less than $1/2$, so the expected number of trials is $O(1)$, but the worst case is unbounded.

Panics

Panics if limit is 0.

Examples

use malachite_base::num::random::VariableRangeGenerator;
use malachite_base::random::EXAMPLE_SEED;

let mut xs = Vec::with_capacity(10);
let mut generator = VariableRangeGenerator::new(EXAMPLE_SEED);
for _ in 0..10 {
    xs.push(generator.next_less_than(10u8));
}
assert_eq!(xs, &[1, 7, 5, 4, 6, 4, 2, 8, 1, 7]);

pub fn next_in_range<T: PrimitiveUnsigned>(&mut self, a: T, b: T) -> T

Uniformly generates a random unsigned integer in the half-open interval $[a, b)$.

$a$ must be less than $b$. This function cannot create a range that includes T::MAX; for that, use next_in_inclusive_range.

$$ P(x) = \begin{cases} \frac{1}{b-a} & \text{if} \quad a \leq x < b, \\ 0 & \text{otherwise.} \end{cases} $$

Expected complexity

$T(n) = O(n)$

$M(n) = O(1)$

where $T$ is time, $M$ is additional memory, and $n$ is (b - a).significant_bits(); the worst case is unbounded, as with next_less_than.

Panics

Panics if $a \geq b$.

Examples

use malachite_base::num::random::VariableRangeGenerator;
use malachite_base::random::EXAMPLE_SEED;

let mut xs = Vec::with_capacity(10);
let mut generator = VariableRangeGenerator::new(EXAMPLE_SEED);
for _ in 0..10 {
    xs.push(generator.next_in_range(10u8, 20));
}
assert_eq!(xs, &[11, 17, 15, 14, 16, 14, 12, 18, 11, 17]);

pub fn next_in_inclusive_range<T: PrimitiveUnsigned>(&mut self, a: T, b: T) -> T

Uniformly generates a random unsigned integer in the closed interval $[a, b]$.

$a$ must be less than or equal to $b$.

$$ P(x) = \begin{cases} \frac{1}{b-a+1} & \text{if} \quad a \leq x \leq b, \\ 0 & \text{otherwise.} \end{cases} $$

Expected complexity

$T(n) = O(n)$

$M(n) = O(1)$

where $T$ is time, $M$ is additional memory, and $n$ is the number of significant bits of the range’s width; the worst case is unbounded, as with next_less_than.

Panics

Panics if $a > b$.

Examples

use malachite_base::num::random::VariableRangeGenerator;
use malachite_base::random::EXAMPLE_SEED;

let mut xs = Vec::with_capacity(10);
let mut generator = VariableRangeGenerator::new(EXAMPLE_SEED);
for _ in 0..10 {
    xs.push(generator.next_in_inclusive_range(10u8, 19));
}
assert_eq!(xs, &[11, 17, 15, 14, 16, 14, 12, 18, 11, 17]);

Trait Implementations

impl Clone for VariableRangeGenerator

fn clone(&self) -> VariableRangeGenerator

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VariableRangeGenerator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.