Function malachite_base::iterators::with_special_values

pub fn with_special_values<I: Iterator>(
    seed: Seed, 
    special_values: Vec<I::Item>, 
    p_numerator: u64, 
    p_denominator: u64, 
    xs_gen: &dyn Fn(Seed) -> I
) -> WithSpecialValues<I> where
    I::Item: Clone, 

An iterator that randomly produces another iterator’s values, or produces a random special value from a Vec.

Let $n_p$ be p_numerator, $d_p$ be p_denominator, and let $p=n_p/d_p$.

Every time a value is to be generated, the iterator uniformly samples the special values Vec with probability $p$, or else returns a value from the inner iterator.

If $p > 0$, the output length is infinite. Otherwise, it is the same as the length of xs.

Worst-case complexity per iteration

Constant time and additional memory.

Panics

Panics if special_values is empty, p_denominator is 0, or if p_numerator is greater than p_denominator.

Examples

use malachite_base::iterators::{prefix_to_string, with_special_values};
use malachite_base::num::random::random_primitive_ints;
use malachite_base::random::EXAMPLE_SEED;

assert_eq!(
    prefix_to_string(
        with_special_values(EXAMPLE_SEED, vec![1, 2, 3], 1, 2, &random_primitive_ints::<i16>),
        20,
    ),
    "[3, 1, 3, 2901, 1, -14200, 2, 3, 1, -30997, -8245, -5338, 1, 1, -20007, 3, 1, 1, 1, 1, \
    ...]"
);