Function malachite_nz::integer::random::random_integer_range

pub fn random_integer_range(
    seed: Seed,
    a: Integer,
    b: Integer,
    mean_bits_numerator: u64,
    mean_bits_denominator: u64
) -> RandomIntegerRange 

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

In general, the Integers are not generated uniformly; for that, use uniform_random_integer_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 of the values minus $a$ as $\log (b/a)$ approaches infinity. $m$ cannot be 0, and must be greater than the bit length of the smallest integer in the range, 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 Integer is chosen uniformly from all Integers with that bit length that are in $[a, b)$.

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 the bit length of the smallest integer in the range, 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::integer::random::random_integer_range;
use malachite_nz::integer::Integer;

assert_eq!(
    prefix_to_string(
        random_integer_range(
            EXAMPLE_SEED,
            Integer::from(-1000),
            Integer::from(1000000000),
            20,
            1
        ),
        10
    ),
    "[1, 1728664, 434, -30, 5282, 515436476, 2353848, -15, 19, 418, ...]"
)