Struct rug::rand::ThreadRandState
source · [−]#[repr(transparent)]pub struct ThreadRandState<'a> { /* private fields */ }
Expand description
The state of a random number generator that is suitable for a single thread only.
This is similar to RandState
but can only be used in a single thread.
Examples
use rug::rand::ThreadRandState;
let mut gen = create_generator();
let mut rand = ThreadRandState::new_custom(&mut gen);
let u = rand.bits(32);
println!("32 random bits: {:032b}", u);
Implementations
Creates a new custom random generator.
This is similar to
RandState::new_custom
. The
difference is that this method takes a ThreadRandGen
that does not
have to implement Send
or Sync
.
Examples
use rug::{
rand::{ThreadRandGen, ThreadRandState},
Integer,
};
// dummy pointer field to ensure Seed is not Send and not Sync
struct Seed(*const ());
impl ThreadRandGen for Seed {
fn gen(&mut self) -> u32 {
// not really random
0x8CEF_7310
}
}
let mut seed = Seed(&());
let mut rand = ThreadRandState::new_custom(&mut seed);
let mut i = Integer::from(15);
i.random_below_mut(&mut rand);
println!("0 ≤ {} < 15", i);
assert!(i < 15);
Creates a new custom random generator.
This is similar to
RandState::new_custom_boxed
.
The difference is that this method takes a ThreadRandGen
that does
not have to implement Send
or Sync
.
Examples
use rug::{
rand::{ThreadRandGen, ThreadRandState},
Integer,
};
// dummy pointer field to ensure Seed is not Send and not Sync
struct Seed(*const ());
impl ThreadRandGen for Seed {
fn gen(&mut self) -> u32 {
// not really random
0x8CEF_7310
}
}
let seed = Box::new(Seed(&()));
let mut rand = ThreadRandState::new_custom_boxed(seed);
let mut i = Integer::from(15);
i.random_below_mut(&mut rand);
println!("0 ≤ {} < 15", i);
assert!(i < 15);
Creates a random generator from an initialized GMP random generator.
This is similar to
RandState::from_raw
, but the
object does not need to be thread safe. You can use this method if the
object is thread safe, but in that case
RandState::from_raw
is probably
better as it allows the returned object to be shared and transferred
across threads.
Safety
- The value must be initialized.
- The
randstate_t
type can be considered as a kind of pointer, so there can be multiple copies of it. Since this function takes over ownership, no other copies of the passed value should exist.
Examples
use core::mem::MaybeUninit;
use gmp_mpfr_sys::gmp;
use rug::rand::ThreadRandState;
let mut rand = unsafe {
let mut raw = MaybeUninit::uninit();
gmp::randinit_default(raw.as_mut_ptr());
let raw = raw.assume_init();
// raw is initialized and unique
ThreadRandState::from_raw(raw)
};
let u = rand.bits(32);
println!("32 random bits: {:032b}", u);
// since rand is a ThreadRandState now, deallocation is automatic
Converts a random generator into a GMP random generator.
The returned object should be freed to avoid memory leaks.
This is similar to
RandState::into_raw
, but the
returned object is not thread safe. Notably, it should not be used in
RandState::from_raw
.
Panics
This method panics if the ThreadRandState
object was created using
new_custom
, as the borrow into the custom generator would be
terminated once self
is consumed. This would lead to undefined
behavior if the returned object is used. This method does work with
objects created using new_custom_boxed
.
Examples
use gmp_mpfr_sys::gmp;
use rug::rand::ThreadRandState;
let gen = Box::new(create_generator());
let rand = ThreadRandState::new_custom_boxed(gen);
let mut raw = rand.into_raw();
unsafe {
let u = gmp::urandomb_ui(&mut raw, 32) as u32;
println!("32 random bits: {:032b}", u);
// free object to prevent memory leak
gmp::randclear(&mut raw);
}
Returns a pointer to the inner GMP random generator.
The returned pointer will be valid for as long as self
is valid.
This is similar to
RandState::as_raw
.
Examples
use rug::rand::ThreadRandState;
let mut gen = create_generator();
let mut rand = ThreadRandState::new_custom(&mut gen);
let raw_ptr = rand.as_raw();
// There is not much you can do with an immutable randstate_t pointer.
println!("pointer: {:p}", raw_ptr);
let u = rand.bits(32);
println!("32 random bits: {:032b}", u);
Returns an unsafe mutable pointer to the inner GMP random generator.
The returned pointer will be valid for as long as self
is valid.
This is similar to
RandState::as_raw_mut
.
Examples
use gmp_mpfr_sys::gmp;
use rug::rand::ThreadRandState;
let mut gen = create_generator();
let mut rand = ThreadRandState::new_custom(&mut gen);
let raw_ptr = rand.as_raw_mut();
unsafe {
let u1 = gmp::urandomb_ui(raw_ptr, 32) as u32;
println!("32 random bits: {:032b}", u1);
}
let u2 = rand.bits(32);
println!("another 32 random bits: {:032b}", u2);
Converts a random generator into Box<dyn ThreadRandGen>
if possible.
If the conversion is not possible, Err(self)
is
returned.
This conversion is always possible when the random generator was created
with new_custom_boxed
. It is also possible if the generator was
cloned, directly or indirectly, from another generator that was created
with new_custom
or new_custom_boxed
.
This is similar to
RandState::into_custom_boxed
.
Examples
use rug::rand::{ThreadRandGen, ThreadRandState};
struct Seed;
impl ThreadRandGen for Seed {
fn gen(&mut self) -> u32 {
// not really random
0x8CEF_7310
}
}
let seed = Box::new(Seed);
let rand = ThreadRandState::new_custom_boxed(seed);
let mut back_to_seed = rand.into_custom_boxed().unwrap();
assert_eq!(back_to_seed.gen(), 0x8CEF_7310);
Seeds the random generator.
This is similar to RandState::seed
.
Examples
use rug::{rand::ThreadRandState, Integer};
let mut gen = create_generator_with_seed();
let seed = Integer::from(123456);
let mut rand = ThreadRandState::new_custom(&mut gen);
rand.seed(&seed);
let u1a = rand.bits(32);
let u1b = rand.bits(32);
// reseed with the same seed
rand.seed(&seed);
let u2a = rand.bits(32);
let u2b = rand.bits(32);
assert_eq!(u1a, u2a);
assert_eq!(u1b, u2b);
Generates a random number with the specified number of bits.
This is similar to RandState::bits
.
Panics
Panics if bits
is greater than 32.
Examples
use rug::rand::ThreadRandState;
let mut gen = create_generator();
let mut rand = ThreadRandState::new_custom(&mut gen);
let u = rand.bits(16);
assert!(u < (1 << 16));
println!("16 random bits: {:016b}", u);
Generates a random number below the given boundary value.
This is similar to RandState::below
.
Panics
Panics if the boundary value is zero.
Examples
use rug::rand::ThreadRandState;
let mut gen = create_generator();
let mut rand = ThreadRandState::new_custom(&mut gen);
let u = rand.below(10000);
assert!(u < 10000);
println!("0 ≤ {} < 10000", u);
Trait Implementations
Auto Trait Implementations
impl<'a> !RefUnwindSafe for ThreadRandState<'a>
impl<'a> !Send for ThreadRandState<'a>
impl<'a> !Sync for ThreadRandState<'a>
impl<'a> Unpin for ThreadRandState<'a>
impl<'a> !UnwindSafe for ThreadRandState<'a>
Blanket Implementations
Mutably borrows from an owned value. Read more
Casts the value.
Casts the value.
Casts the value.
OverflowingCasts the value.
Casts the value.
Casts the value.
Casts the value.
UnwrappedCasts the value.
Casts the value.
WrappingCasts the value.