Improvements to docs and README.md.

README.md

@@ -4,8 +4,9 @@
 [![Crates.io](https://img.shields.io/crates/v/roundable)][crates.io]
 ![Rust version 1.56.1+](https://img.shields.io/badge/Rust%20version-1.56.1%2B-success)
 
-This provides an implementation of rounding for various values, including
-[`std::time::Duration`][`Duration`] (or `core::time::Duration`).
+This provides an implementation of rounding for various values, including the
+native number types and [`core::time::Duration`][`Duration`] (or
+`std::time::Duration`).
 
 This crate is does not need `std` or `alloc` (it’s always in `no_std` mode). No
 features need to be enabled or disabled.
@@ -15,10 +16,14 @@ use roundable::Roundable;
 
 assert!(310 == 314.round_to(10));
 assert!(300.0 == 314.1.round_to(100.0));
+
+// To avoid panicking on overflow:
+assert!(Some(260) == 255.try_round_to(10));
+assert!(None == 255u8.try_round_to(10));
 ```
 
-See [Constants][] for a list of time units that make rounding [`Duration`][]
-easier.
+See [the list of constants][constants] for a list of time units that make
+rounding [`Duration`][] easier.
 
 ```rust
 use roundable::{SECOND, MINUTE, Roundable};
@@ -56,4 +61,4 @@ additional terms or conditions.
 [crates.io]: https://crates.io/crates/roundable
 [issues]: https://github.com/danielparks/roundable/issues
 [`Duration`]: https://doc.rust-lang.org/core/time/struct.Duration.html
-[Constants]: https://docs.rs/roundable/latest/roundable/#Constants
+[Constants]: https://docs.rs/roundable/latest/roundable/#constants

src/lib.rs

@@ -87,24 +87,54 @@ pub const MINUTE: Duration = Duration::from_secs(60);
 /// ```
 pub const HOUR: Duration = Duration::from_secs(60 * 60);
 
-/// Add methods to round to an arbitrary factor.
+/// Methods to round the value to an arbitrary factor.
 ///
 /// For example, you might wish to round an integer to the nearest 10s:
 ///
 /// ```rust
 /// use roundable::Roundable;
 ///
 /// assert!(310 == 314.round_to(10));
-/// assert!(300 == 314.round_to(100));
+/// assert!(Some(300) == 314.try_round_to(100));
 /// ```
 pub trait Roundable: Sized {
-    /// Round to the nearest `factor`.
+    /// Round to the nearest `factor`. Panics if there is an overflow.
+    ///
+    /// ```rust
+    /// use roundable::Roundable;
+    ///
+    /// assert!(315 == 314.round_to(5));
+    /// assert!(-10 == (-15).round_to(10));
+    /// ```
+    ///
+    /// `255u8` can’t be rounded to the nearest 10 (which would be 260) because
+    /// 260 won’t fit in a `u8`:
+    ///
+    /// ```rust,should_panic
+    /// # use roundable::Roundable;
+    /// let _ = 255u8.round_to(10u8);
+    /// ```
     #[must_use]
     fn round_to(self, factor: Self) -> Self {
         self.try_round_to(factor).expect("overflow while rounding")
     }
 
-    /// Round to the nearest `factor`.
+    /// Round to the nearest `factor`. Returns `None` if there is an overflow.
+    ///
+    /// ```rust
+    /// use roundable::Roundable;
+    ///
+    /// assert!(Some(315) == 314.try_round_to(5));
+    /// assert!(Some(-10) == (-15).try_round_to(10));
+    /// ```
+    ///
+    /// `255u8` can’t be rounded to the nearest 10 (which would be 260) because
+    /// 260 won’t fit in a `u8`:
+    ///
+    /// ```rust
+    /// # use roundable::Roundable;
+    /// assert!(None == 255u8.try_round_to(10));
+    /// ```
     #[must_use]
     fn try_round_to(self, factor: Self) -> Option<Self>;
 }
@@ -286,6 +316,18 @@ mod tests {
         check!((-3) == (-3i8).round_to(3));
     }
 
+    #[test]
+    fn round_integer_to_ten() {
+        check!(10 == 14.round_to(10));
+        check!(20 == 15.round_to(10));
+        check!(20 == 16.round_to(10));
+
+        // Parentheses are to work around a compile failure in check!().
+        check!((-10) == (-14).round_to(10));
+        check!((-10) == (-15).round_to(10));
+        check!((-20) == (-16).round_to(10));
+    }
+
     #[test]
     fn round_max_integer() {
         check!(0 == 10.round_to(u32::MAX));