Add examples for Checked[Add|Sub|Mul|Div]

diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs
index df90d81c57abca06ff9690d73feedc5b09cf7c7d..48a3db4258f2b021f2fce3d24fc66bad9ed0c6fc 100644 (file)
--- a/src/libcore/num/mod.rs
+++ b/src/libcore/num/mod.rs
@@ -1217,6 +1217,14 @@ fn saturating_sub(self, v: T) -> T {
 /// Performs addition that returns `None` instead of wrapping around on overflow.
 pub trait CheckedAdd: Add<Self, Self> {
     /// Adds two numbers, checking for overflow. If overflow happens, `None` is returned.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::num::CheckedAdd;
+    /// assert_eq!(5u16.checked_add(&65530), Some(65535));
+    /// assert_eq!(6u16.checked_add(&65530), None);
+    /// ```
     fn checked_add(&self, v: &Self) -> Option<Self>;
 }
 
@@ -1270,6 +1278,14 @@ fn $method(&self, v: &$t) -> Option<$t> {
 /// Performs subtraction that returns `None` instead of wrapping around on underflow.
 pub trait CheckedSub: Sub<Self, Self> {
     /// Subtracts two numbers, checking for underflow. If underflow happens, `None` is returned.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::num::CheckedSub;
+    /// assert_eq!((-127i8).checked_sub(&1), Some(-128));
+    /// assert_eq!((-128i8).checked_sub(&1), None);
+    /// ```
     fn checked_sub(&self, v: &Self) -> Option<Self>;
 }
 
@@ -1298,6 +1314,14 @@ pub trait CheckedSub: Sub<Self, Self> {
 pub trait CheckedMul: Mul<Self, Self> {
     /// Multiplies two numbers, checking for underflow or overflow. If underflow or overflow
     /// happens, `None` is returned.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::num::CheckedMul;
+    /// assert_eq!(5u8.checked_mul(&51), Some(255));
+    /// assert_eq!(5u8.checked_mul(&52), None);
+    /// ```
     fn checked_mul(&self, v: &Self) -> Option<Self>;
 }
 
@@ -1325,6 +1349,14 @@ pub trait CheckedMul: Mul<Self, Self> {
 pub trait CheckedDiv: Div<Self, Self> {
     /// Divides two numbers, checking for underflow or overflow. If underflow or overflow happens,
     /// `None` is returned.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use std::num::CheckedDiv;
+    /// assert_eq!((-127i8).checked_div(&-1), Some(127));
+    /// assert_eq!((-128i8).checked_div(&-1), None);
+    /// ```
     fn checked_div(&self, v: &Self) -> Option<Self>;
 }