Skip to content

Commit 746a7aa

Browse files
committed
fill and try_fill methods: improve documentation; add links
1 parent 122272e commit 746a7aa

File tree

1 file changed

+25
-9
lines changed

1 file changed

+25
-9
lines changed

src/lib.rs

Lines changed: 25 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -482,13 +482,17 @@ pub trait Rng {
482482
Ok(self.fill_bytes(dest))
483483
}
484484

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.).
488488
///
489489
/// On big-endian platforms this performs byte-swapping to ensure
490490
/// portability of results from reproducible generators.
491491
///
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+
///
492496
/// # Example
493497
///
494498
/// ```rust
@@ -498,21 +502,25 @@ pub trait Rng {
498502
/// thread_rng().try_fill(&mut arr[..]);
499503
/// ```
500504
///
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
502508
fn fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T) where Self: Sized {
503509
self.fill_bytes(dest.as_byte_slice_mut());
504510
dest.to_le();
505511
}
506512

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.).
510516
///
511517
/// On big-endian platforms this performs byte-swapping to ensure
512518
/// portability of results from reproducible generators.
513519
///
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`].
516524
///
517525
/// # Example
518526
///
@@ -530,6 +538,9 @@ pub trait Rng {
530538
/// ```
531539
///
532540
/// [`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
533544
fn try_fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T) -> Result<(), Error> where Self: Sized {
534545
self.try_fill_bytes(dest.as_byte_slice_mut())?;
535546
dest.to_le();
@@ -756,6 +767,11 @@ impl<R: ?Sized> Rng for Box<R> where R: Rng {
756767
}
757768

758769
/// 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
759775
pub trait AsByteSliceMut {
760776
/// Return a mutable reference to self as a byte slice
761777
fn as_byte_slice_mut<'a>(&'a mut self) -> &'a mut [u8];

0 commit comments

Comments
 (0)