@@ -482,13 +482,17 @@ pub trait Rng {
482
482
Ok ( self . fill_bytes ( dest) )
483
483
}
484
484
485
- /// Fill `dest` entirely with random data.
486
- ///
487
- /// This method provides a convenient way to fill a slice with random data .
485
+ /// Fill `dest` entirely with random bytes, where `dest` is any type
486
+ /// supporting [`AsByteSliceMut`], namely slices over primitive integer
487
+ /// types (`i8`, `i16`, `u32`, etc.) .
488
488
///
489
489
/// On big-endian platforms this performs byte-swapping to ensure
490
490
/// portability of results from reproducible generators.
491
491
///
492
+ /// This uses [`fill_bytes`] internally which may handle some RNG errors
493
+ /// implicitly (e.g. waiting if the OS generator is not ready), but panics
494
+ /// on other errors. See also [`try_fill`] which returns errors.
495
+ ///
492
496
/// # Example
493
497
///
494
498
/// ```rust
@@ -498,21 +502,25 @@ pub trait Rng {
498
502
/// thread_rng().try_fill(&mut arr[..]);
499
503
/// ```
500
504
///
501
- /// [`ErrorKind`]: enum.ErrorKind.html
505
+ /// [`fill_bytes`]: trait.Rng.html#method.fill_bytes
506
+ /// [`try_fill`]: trait.Rng.html#method.try_fill
507
+ /// [`AsByteSliceMut`]: trait.AsByteSliceMut.html
502
508
fn fill < T : AsByteSliceMut + ?Sized > ( & mut self , dest : & mut T ) where Self : Sized {
503
509
self . fill_bytes ( dest. as_byte_slice_mut ( ) ) ;
504
510
dest. to_le ( ) ;
505
511
}
506
512
507
- /// Fill `dest` entirely with random data.
508
- ///
509
- /// This method provides a convenient way to fill a slice with random data .
513
+ /// Fill `dest` entirely with random bytes, where `dest` is any type
514
+ /// supporting [`AsByteSliceMut`], namely slices over primitive integer
515
+ /// types (`i8`, `i16`, `u32`, etc.) .
510
516
///
511
517
/// On big-endian platforms this performs byte-swapping to ensure
512
518
/// portability of results from reproducible generators.
513
519
///
514
- /// Errors are forwarded from their source. In some cases errors may be
515
- /// resolvable; see [`ErrorKind`] and documentation for the RNG in use.
520
+ /// This uses [`try_fill_bytes`] internally and forwards all RNG errors. In
521
+ /// some cases errors may be resolvable; see [`ErrorKind`] and
522
+ /// documentation for the RNG in use. If you do not plan to handle these
523
+ /// errors you may prefer to use [`fill`].
516
524
///
517
525
/// # Example
518
526
///
@@ -530,6 +538,9 @@ pub trait Rng {
530
538
/// ```
531
539
///
532
540
/// [`ErrorKind`]: enum.ErrorKind.html
541
+ /// [`try_fill_bytes`]: trait.Rng.html#method.try_fill_bytes
542
+ /// [`fill`]: trait.Rng.html#method.fill
543
+ /// [`AsByteSliceMut`]: trait.AsByteSliceMut.html
533
544
fn try_fill < T : AsByteSliceMut + ?Sized > ( & mut self , dest : & mut T ) -> Result < ( ) , Error > where Self : Sized {
534
545
self . try_fill_bytes ( dest. as_byte_slice_mut ( ) ) ?;
535
546
dest. to_le ( ) ;
@@ -756,6 +767,11 @@ impl<R: ?Sized> Rng for Box<R> where R: Rng {
756
767
}
757
768
758
769
/// Trait for casting types to byte slices
770
+ ///
771
+ /// This is used by the [`fill`] and [`try_fill`] methods.
772
+ ///
773
+ /// [`fill`]: trait.Rng.html#method.fill
774
+ /// [`try_fill`]: trait.Rng.html#method.try_fill
759
775
pub trait AsByteSliceMut {
760
776
/// Return a mutable reference to self as a byte slice
761
777
fn as_byte_slice_mut < ' a > ( & ' a mut self ) -> & ' a mut [ u8 ] ;
0 commit comments