Deprecate Rng::gen_weighted_bool

Author: pitdicker

src/lib.rs

@@ -518,9 +518,21 @@ pub trait Rng: RngCore {
 
     /// Return a bool with a 1 in n chance of true
     ///
+    /// # Deprecated
+    /// Examples of what to replace `rng.gen_weighted_bool(3)` with
+    /// (from fastest to slowest):
+    /// ```
+    /// # use rand::{thread_rng, Rng};
+    /// # let mut rng = thread_rng();
+    /// rng.gen::<u32>() < std::u32::MAX / 3;
+    /// rng.gen::<f32>() < (1.0f32 / 3.0);
+    /// rng.gen_range(0, 3) < 1;
+    /// ```
+    ///
     /// # Example
     ///
     /// ```rust
+    /// #[allow(deprecated)]
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut rng = thread_rng();
@@ -532,6 +544,7 @@ pub trait Rng: RngCore {
     /// // First meaningful use of `gen_weighted_bool`.
     /// println!("{}", rng.gen_weighted_bool(3));
     /// ```
+    #[deprecated(since="0.5.0", note="use gen_range(0, n) < 1 instead")]
     fn gen_weighted_bool(&mut self, n: u32) -> bool {
         // Short-circuit after `n <= 1` to avoid panic in `gen_range`
         n <= 1 || self.gen_range(0, n) == 0
@@ -1076,6 +1089,7 @@ mod test {
     }
 
     #[test]
+    #[allow(deprecated)]
     fn test_gen_weighted_bool() {
         let mut r = rng(104);
         assert_eq!(r.gen_weighted_bool(0), true);