Function malachite_nz::natural::random::random_natural_range

pub fn random_natural_range(
    seed: Seed,
    a: Natural,
    b: Natural,
    mean_bits_numerator: u64,
    mean_bits_denominator: u64
) -> RandomNaturalRange 

Generates random Naturals in the half-open interval $[a, b)$.

In general, the Naturals are not generated uniformly; for that, use uniform_random_natural_range. Instead, Naturals with smaller bit lengths are generated more frequently.

The distribution of generated values is parametrized by a number $m$, given by mean_bits_numerator / mean_bits_denominator. It is not actually the mean bit length, though it approaches the mean bit length as $\log (b/a)$ approaches infinity. $m$ must be greater than $a$, but it may be arbitrarily large. The smaller it is, the more quickly the probabilities decrease as bit length increases. The larger it is, the more closely the distribution approaches a uniform distribution over the bit lengths.

Once a bit length is selected, the Natural is chosen uniformly from all Naturals with that bit length that are in $[a, b)$.

To obtain the probability mass function, adjust $b$ and see random_natural_inclusive_range.

The output length is infinite.

Expected complexity per iteration

$T(n) = O(n)$

$M(m) = O(m)$

where $T$ is time, $M$ is additional memory, $n$ is mean_bits_numerator + mean_bits_denominator, and $m$ is b.significant_bits().

Panics

Panics if $a \geq b$, if mean_bits_numerator or mean_bits_denominator are zero, if their ratio is less than or equal to $a$, or if they are too large and manipulating them leads to arithmetic overflow.

Examples

use malachite_base::iterators::prefix_to_string;
use malachite_base::random::EXAMPLE_SEED;
use malachite_nz::natural::random::random_natural_range;
use malachite_nz::natural::Natural;

assert_eq!(
    prefix_to_string(
        random_natural_range(
            EXAMPLE_SEED,
            Natural::from(1000u32),
            Natural::from(1000000000u32),
            20,
            1
        ),
        10
    ),
    "[3254, 4248, 163506, 600542, 5282, 12220, 60088, 1016911, 5772451, 2792610, ...]"
)