Module random 

Available on crate feature rand_distr only.

Random sampling support through rand_distr.

This module is available with the rand_distr crate feature. It implements Distribution for interval types where the sampled backing float is guaranteed to satisfy the interval invariant, and provides adapter distributions for arbitrary float distributions.

StandardUniform samples UnitInterval values from [0, 1) and SignedUnitInterval values from [-1, 1).

use rand::{RngExt, SeedableRng, rngs::StdRng};
use rand_distr::{Distribution, StandardUniform};
use unit_intervals::{SignedUnitInterval, UnitInterval};

let mut rng = StdRng::seed_from_u64(42);

let unit: UnitInterval<f32> = StandardUniform.sample(&mut rng);
let signed: SignedUnitInterval<f64> = rng.random();

assert!(UnitInterval::<f32>::contains(unit.get()));
assert!(SignedUnitInterval::<f64>::contains(signed.get()));

Bounded rand_distr float distributions whose support is inside [0, 1] can also sample UnitInterval values directly.

use rand::{SeedableRng, rngs::StdRng};
use rand_distr::{Beta, Distribution, Open01, OpenClosed01};
use unit_intervals::UnitInterval;

let mut rng = StdRng::seed_from_u64(42);
let beta = Beta::new(2.0_f64, 5.0).unwrap();

let open: UnitInterval<f32> = Open01.sample(&mut rng);
let open_closed: UnitInterval<f64> = OpenClosed01.sample(&mut rng);
let beta_value: UnitInterval<f64> = beta.sample(&mut rng);

assert!(UnitInterval::<f32>::contains(open.get()));
assert!(UnitInterval::<f64>::contains(open_closed.get()));
assert!(UnitInterval::<f64>::contains(beta_value.get()));

Arbitrary float distributions may produce values outside the target interval. Use checked adapters when out-of-range samples should become None, or saturating adapters when they should be clamped.

use rand::{SeedableRng, rngs::StdRng};
use rand_distr::{Distribution, Normal};
use unit_intervals::{
    UnitInterval,
    random::{CheckedUnitIntervalDistribution, SaturatingUnitIntervalDistribution},
};

let normal = Normal::new(0.5_f32, 2.0).unwrap();
let checked = CheckedUnitIntervalDistribution::new(normal);
let saturating = SaturatingUnitIntervalDistribution::new(normal);
let mut rng = StdRng::seed_from_u64(42);

let checked_sample: Option<UnitInterval<f32>> = checked.sample(&mut rng);
let saturating_sample: UnitInterval<f32> = saturating.sample(&mut rng);

assert!(checked_sample.is_none_or(|value| UnitInterval::<f32>::contains(value.get())));
assert!(UnitInterval::<f32>::contains(saturating_sample.get()));

The same adapter pattern is available for SignedUnitInterval.

use rand::{SeedableRng, rngs::StdRng};
use rand_distr::{Distribution, Normal};
use unit_intervals::{
    SignedUnitInterval,
    random::{
        CheckedSignedUnitIntervalDistribution, SaturatingSignedUnitIntervalDistribution,
    },
};

let normal = Normal::new(0.0_f64, 2.0).unwrap();
let checked = CheckedSignedUnitIntervalDistribution::new(normal);
let saturating = SaturatingSignedUnitIntervalDistribution::new(normal);
let mut rng = StdRng::seed_from_u64(42);

let checked_sample: Option<SignedUnitInterval<f64>> = checked.sample(&mut rng);
let saturating_sample: SignedUnitInterval<f64> = saturating.sample(&mut rng);

assert!(checked_sample.is_none_or(|value| SignedUnitInterval::<f64>::contains(value.get())));
assert!(SignedUnitInterval::<f64>::contains(saturating_sample.get()));

Structs

CheckedSignedUnitIntervalDistribution

Adapts an arbitrary distribution over raw floats into checked SignedUnitInterval samples.

CheckedUnitIntervalDistribution

Adapts an arbitrary distribution over raw floats into checked UnitInterval samples.

SaturatingSignedUnitIntervalDistribution

Adapts an arbitrary distribution over raw floats into saturating SignedUnitInterval samples.

SaturatingUnitIntervalDistribution

Adapts an arbitrary distribution over raw floats into saturating UnitInterval samples.