Merge pull request #220 from fitzgen/docs

Document bias and behavior when running out of entropy

Author: fitzgen

src/error.rs

@@ -8,6 +8,10 @@ pub enum Error {
     EmptyChoose,
     /// There was not enough underlying data to fulfill some request for raw
     /// bytes.
+    ///
+    /// Note that outside of [`Unstructured::bytes`][crate::Unstructured::bytes],
+    /// most APIs do *not* return this error when running out of underlying arbitrary bytes
+    /// but silently return some default value instead.
     NotEnoughData,
     /// The input bytes were not of the right format
     IncorrectFormat,

src/foreign/core/bool.rs

@@ -1,5 +1,6 @@
 use crate::{Arbitrary, Result, Unstructured};
 
+/// Returns false, not an error, if this `Unstructured` [is empty][Unstructured::is_empty].
 impl<'a> Arbitrary<'a> for bool {
     fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
         Ok(<u8 as Arbitrary<'a>>::arbitrary(u)? & 1 == 1)

src/foreign/core/char.rs

@@ -1,5 +1,6 @@
 use crate::{Arbitrary, Result, Unstructured};
 
+/// Returns '\0', not an error, if this `Unstructured` [is empty][Unstructured::is_empty].
 impl<'a> Arbitrary<'a> for char {
     fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
         // The highest unicode code point is 0x11_FFFF

src/foreign/core/option.rs

@@ -1,5 +1,6 @@
 use crate::{size_hint, Arbitrary, MaxRecursionReached, Result, Unstructured};
 
+/// Returns `None`, not an error, if this `Unstructured` [is empty][Unstructured::is_empty].
 impl<'a, A> Arbitrary<'a> for Option<A>
 where
     A: Arbitrary<'a>,

src/foreign/core/sync/atomic.rs

@@ -3,6 +3,7 @@ use {
     core::sync::atomic::{AtomicBool, AtomicIsize, AtomicUsize},
 };
 
+/// Returns false, not an error, if this `Unstructured` [is empty][Unstructured::is_empty].
 impl<'a> Arbitrary<'a> for AtomicBool {
     fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
         Arbitrary::arbitrary(u).map(Self::new)
@@ -14,6 +15,7 @@ impl<'a> Arbitrary<'a> for AtomicBool {
     }
 }
 
+/// Returns zero, not an error, if this `Unstructured` [is empty][Unstructured::is_empty].
 impl<'a> Arbitrary<'a> for AtomicIsize {
     fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
         Arbitrary::arbitrary(u).map(Self::new)
@@ -25,6 +27,7 @@ impl<'a> Arbitrary<'a> for AtomicIsize {
     }
 }
 
+/// Returns zero, not an error, if this `Unstructured` [is empty][Unstructured::is_empty].
 impl<'a> Arbitrary<'a> for AtomicUsize {
     fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
         Arbitrary::arbitrary(u).map(Self::new)

src/foreign/core/time.rs

@@ -3,6 +3,7 @@ use {
     core::time::Duration,
 };
 
+/// Returns zero, not an error, if this `Unstructured` [is empty][Unstructured::is_empty].
 impl<'a> Arbitrary<'a> for Duration {
     fn arbitrary(u: &mut Unstructured<'a>) -> Result<Self> {
         Ok(Self::new(

src/lib.rs

@@ -425,6 +425,25 @@ pub trait Arbitrary<'a>: Sized {
     }
 }
 
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn exhausted_entropy() {
+        let mut u = Unstructured::new(&[]);
+        assert_eq!(u.arbitrary::<bool>().unwrap(), false);
+        assert_eq!(u.arbitrary::<u8>().unwrap(), 0);
+        assert_eq!(u.arbitrary::<usize>().unwrap(), 0);
+        assert_eq!(u.arbitrary::<f32>().unwrap(), 0.0);
+        assert_eq!(u.arbitrary::<f64>().unwrap(), 0.0);
+        assert_eq!(u.arbitrary::<Option<u32>>().unwrap(), None);
+        assert_eq!(u.int_in_range(4..=100).unwrap(), 4);
+        assert_eq!(u.choose_index(10).unwrap(), 0);
+        assert_eq!(u.ratio(5, 7).unwrap(), true);
+    }
+}
+
 /// Multiple conflicting arbitrary attributes are used on the same field:
 /// ```compile_fail
 /// #[derive(::arbitrary::Arbitrary)]

src/unstructured.rs

@@ -273,6 +273,11 @@ impl<'a> Unstructured<'a> {
     /// Do not use this to generate the size of a collection. Use
     /// `arbitrary_len` instead.
     ///
+    /// The probability distribution of the return value is not necessarily uniform.
+    ///
+    /// Returns `range.start()`, not an error,
+    /// if this `Unstructured` [is empty][Unstructured::is_empty].
+    ///
     /// # Panics
     ///
     /// Panics if `range.start > range.end`. That is, the given range must be
@@ -377,8 +382,12 @@ impl<'a> Unstructured<'a> {
     ///
     /// This should only be used inside of `Arbitrary` implementations.
     ///
-    /// Returns an error if there is not enough underlying data to make a
-    /// choice or if no choices are provided.
+    /// The probability distribution of choices is not necessarily uniform.
+    ///
+    /// Returns the first choice, not an error,
+    /// if this `Unstructured` [is empty][Unstructured::is_empty].
+    ///
+    /// Returns an error if no choices are provided.
     ///
     /// # Examples
     ///
@@ -416,8 +425,12 @@ impl<'a> Unstructured<'a> {
     ///
     /// This should only be used inside of `Arbitrary` implementations.
     ///
-    /// Returns an error if there is not enough underlying data to make a
-    /// choice or if no choices are provided.
+    /// The probability distribution of choices is not necessarily uniform.
+    ///
+    /// Returns the first choice, not an error,
+    /// if this `Unstructured` [is empty][Unstructured::is_empty].
+    ///
+    /// Returns an error if no choices are provided.
     ///
     /// # Examples
     ///
@@ -449,6 +462,10 @@ impl<'a> Unstructured<'a> {
 
     /// Choose a value in `0..len`.
     ///
+    /// The probability distribution of return values is not necessarily uniform.
+    ///
+    /// Returns zero, not an error, if this `Unstructured` [is empty][Unstructured::is_empty].
+    ///
     /// Returns an error if the `len` is zero.
     ///
     /// # Examples
@@ -492,7 +509,9 @@ impl<'a> Unstructured<'a> {
         Ok(idx)
     }
 
-    /// Generate a boolean according to the given ratio.
+    /// Generate a boolean which is true with probability approximately the given ratio.
+    ///
+    /// Returns true, not an error, if this `Unstructured` [is empty][Unstructured::is_empty].
     ///
     /// # Panics
     ///
@@ -512,7 +531,7 @@ impl<'a> Unstructured<'a> {
     /// let mut u = Unstructured::new(&my_data);
     ///
     /// if u.ratio(5, 7)? {
-    ///     // Take this branch 5/7 of the time.
+    ///     // Take this branch approximately 5/7 of the time.
     /// }
     /// # Ok(())
     /// # }