spinoso_random

Struct Random

source
pub struct Random { /* private fields */ }
Expand description

Random provides an interface to Ruby’s pseudo-random number generator, or PRNG.

The PRNG produces a deterministic sequence of bits which approximate true randomness. The sequence may be represented by integers, floats, or binary strings.

The generator may be initialized with either a system-generated or user-supplied seed value.

PRNGs are currently implemented as a modified Mersenne Twister with a period of 2**19937-1.

This RNG reproduces the same random bytes and floats as MRI. It may differ when returning elements confined to a distribution.

§Examples

Create an RNG with a random seed:

use spinoso_random::{Error, Random};

let mut random = Random::new()?;
let next = random.next_int32();

Create a RNG with a fixed seed:

use spinoso_random::Random;

let seed = 5489_u32;
let mut random = Random::with_seed(seed);
let rand = random.next_int32();

let seed = [627457_u32, 697550, 16438, 41926];
let mut random = Random::with_array_seed(seed);
let rand = random.next_int32();

Implementations§

source§

impl Random

source

pub fn new() -> Result<Self, InitializeError>

Create a new Mersenne Twister random number generator with a randomly generated seed.

This method initializes the Mersenne Twister random number generator with a seed derived from a cryptographically secure source of randomness.

§Examples
use spinoso_random::{Error, Random};

let mut random = Random::new()?;
let next = random.next_int32();
§Errors

If the randomness feature provided by the platform is not present or failed to completely generate a seed, an error is returned. This error should be raised as a Ruby RuntimeError.

source

pub fn with_seed(seed: u32) -> Self

Create a new random number generator using the given seed.

§Examples
use spinoso_random::Random;

let seed = 33;
let mut random = Random::with_seed(seed);
let rand = random.next_int32();
source

pub fn with_array_seed<T>(seed: T) -> Self
where T: IntoIterator<Item = u32>, T::IntoIter: Clone,

Create a new random number generator using the given seed.

§Examples
use spinoso_random::Random;

let seed = [1_u32, 2, 3, 4];
let mut random = Random::with_array_seed(seed);
let rand = random.next_int32();
source

pub fn with_byte_array_seed(seed: [u8; 16]) -> Self

Create a new random number generator using the given seed.

§Examples
use spinoso_random::Random;

let seed = [1_u32, 2, 3, 4];
let mut random = Random::with_array_seed(seed);
let rand = random.next_int32();
source

pub fn next_int32(&mut self) -> u32

Generate next u32 output.

Generates a random number on (0..=0xffffffff)-interval.

u32 is the native output of the generator. This function advances the RNG step counter by one.

§Examples
use spinoso_random::{Error, Random};

let mut random = Random::new()?;
assert_ne!(random.next_int32(), random.next_int32());
source

pub fn next_real(&mut self) -> f64

Generate next f64 output.

Generates a random number on [0,1) with 53-bit resolution.

§Examples
use spinoso_random::{Error, Random};

let mut random = Random::new()?;
assert_ne!(random.next_real(), random.next_real());
source

pub fn fill_bytes(&mut self, dest: &mut [u8])

Fill a buffer with bytes generated from the RNG.

This method generates random u32s (the native output unit of the RNG) until dest is filled.

This method may discard some output bits if dest.len() is not a multiple of 4.

§Examples
use spinoso_random::{Error, Random};

let mut random = Random::new()?;
let mut buf = [0; 32];
random.fill_bytes(&mut buf);
assert_ne!([0; 32], buf);
let mut buf = [0; 31];
random.fill_bytes(&mut buf);
assert_ne!([0; 31], buf);
source

pub fn seed(&self) -> &[u32]

Returns the seed value used to initialize the generator.

This may be used to initialize another generator with the same state at a later time, causing it to produce the same sequence of numbers.

§Examples
use spinoso_random::Random;

let seed = [1_u32, 2, 3, 4];
let random = Random::with_array_seed(seed);
assert_eq!(random.seed(), seed);

Trait Implementations§

source§

impl Clone for Random

source§

fn clone(&self) -> Random

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Random

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Random

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl From<&[u32]> for Random

source§

fn from(seed: &[u32]) -> Self

Converts to this type from the input type.
source§

impl From<[u32; 4]> for Random

source§

fn from(seed: [u32; 4]) -> Self

Converts to this type from the input type.
source§

impl From<[u8; 16]> for Random

source§

fn from(seed: [u8; 16]) -> Self

Converts to this type from the input type.
source§

impl From<u32> for Random

source§

fn from(seed: u32) -> Self

Converts to this type from the input type.
source§

impl Hash for Random

source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
source§

impl PartialEq for Random

source§

fn eq(&self, other: &Random) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl RngCore for Random

source§

fn next_u64(&mut self) -> u64

Generate next u64 output.

This function is implemented by generating two u32s from the RNG and shifting + masking them into a u64 output.

§Examples
use rand_core::RngCore;
use spinoso_random::Random;

let mut random = Random::with_seed(33);
assert_ne!(random.next_u64(), random.next_u64());
source§

fn next_u32(&mut self) -> u32

Generate next u32 output.

u32 is the native output of the generator. This function advances the RNG step counter by one.

§Examples
use rand_core::RngCore;
use spinoso_random::Random;

let mut random = Random::with_seed(33);
assert_ne!(random.next_u32(), random.next_u32());
source§

fn fill_bytes(&mut self, dest: &mut [u8])

Fill a buffer with bytes generated from the RNG.

This method generates random u32s (the native output unit of the RNG) until dest is filled.

This method may discard some output bits if dest.len() is not a multiple of 4.

§Examples
use rand_core::RngCore;
use spinoso_random::Random;

let mut random = Random::with_seed(33);
let mut buf = [0; 32];
random.fill_bytes(&mut buf);
assert_ne!([0; 32], buf);
let mut buf = [0; 31];
random.fill_bytes(&mut buf);
assert_ne!([0; 31], buf);
source§

fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>

Fill a buffer with bytes generated from the RNG.

This method generates random u32s (the native output unit of the RNG) until dest is filled.

This method may discard some output bits if dest.len() is not a multiple of 4.

try_fill_bytes is implemented with fill_bytes and is infallible.

§Examples
use rand_core::{Error, RngCore};
use spinoso_random::Random;

let mut random = Random::with_seed(33);
let mut buf = [0; 32];
random.try_fill_bytes(&mut buf)?;
assert_ne!([0; 32], buf);
let mut buf = [0; 31];
random.try_fill_bytes(&mut buf)?;
assert_ne!([0; 31], buf);
§Errors

This method never returns an error. It is equivalent to calling the infallible fill_bytes method.

source§

impl SeedableRng for Random

source§

fn from_seed(seed: Self::Seed) -> Self

Reseed from four u32s.

§Examples
use rand_core::{RngCore, SeedableRng};
use spinoso_random::Random;

// Default MT seed
let seed = 5489_u128.to_le_bytes();
let mut mt = Random::from_seed(seed);
assert_ne!(mt.next_u32(), mt.next_u32());
source§

type Seed = [u8; 16]

Seed type, which is restricted to types mutably-dereferenceable as u8 arrays (we recommend [u8; N] for some N). Read more
source§

fn seed_from_u64(state: u64) -> Self

Create a new PRNG using a u64 seed. Read more
source§

fn from_rng<R>(rng: R) -> Result<Self, Error>
where R: RngCore,

Create a new PRNG seeded from another Rng. Read more
source§

fn from_entropy() -> Self

Creates a new instance of the RNG seeded via getrandom. Read more
source§

impl Eq for Random

source§

impl StructuralPartialEq for Random

Auto Trait Implementations§

§

impl Freeze for Random

§

impl RefUnwindSafe for Random

§

impl Send for Random

§

impl Sync for Random

§

impl Unpin for Random

§

impl UnwindSafe for Random

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<R> Rng for R
where R: RngCore + ?Sized,

source§

fn gen<T>(&mut self) -> T

Return a random value supporting the Standard distribution. Read more
source§

fn gen_range<T, R>(&mut self, range: R) -> T
where T: SampleUniform, R: SampleRange<T>,

Generate a random value in the given range. Read more
source§

fn sample<T, D>(&mut self, distr: D) -> T
where D: Distribution<T>,

Sample a new value, using the given distribution. Read more
source§

fn sample_iter<T, D>(self, distr: D) -> DistIter<D, Self, T>
where D: Distribution<T>, Self: Sized,

Create an iterator that generates values using the given distribution. Read more
source§

fn fill<T>(&mut self, dest: &mut T)
where T: Fill + ?Sized,

Fill any type implementing Fill with random data Read more
source§

fn try_fill<T>(&mut self, dest: &mut T) -> Result<(), Error>
where T: Fill + ?Sized,

Fill any type implementing Fill with random data Read more
source§

fn gen_bool(&mut self, p: f64) -> bool

Return a bool with a probability p of being true. Read more
source§

fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool

Return a bool with a probability of numerator/denominator of being true. I.e. gen_ratio(2, 3) has chance of 2 in 3, or about 67%, of returning true. If numerator == denominator, then the returned value is guaranteed to be true. If numerator == 0, then the returned value is guaranteed to be false. Read more
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.