Rename Integer trait `divides` to `is_multiple_of`.

It is being changed because the previous wording was ambiguous.
`a.divides(b)` implied `a % b == 0` but it sounds like the other way
around. `9.divides(&3) == true` but we might read that as
"does 9 divide 3?".  It has been renamed to sidestep the ambiguity.

Work around the change by using `is_multiple_of` instead.

[breaking-change]

2 files changed, 43 insertions, 20 deletions

diff --git a/src/libnum/bigint.rs b/src/libnum/bigint.rs
index acba750aaf4..4dd3817e475 100644
--- a/src/libnum/bigint.rs
+++ b/src/libnum/bigint.rs
@@ -514,9 +514,14 @@ impl Integer for BigUint {
     #[inline]
     fn lcm(&self, other: &BigUint) -> BigUint { ((*self * *other) / self.gcd(other)) }
 
-    /// Returns `true` if the number can be divided by `other` without leaving a remainder.
+    /// Deprecated, use `is_multiple_of` instead.
+    #[deprecated = "function renamed to `is_multiple_of`"]
     #[inline]
-    fn divides(&self, other: &BigUint) -> bool { (*self % *other).is_zero() }
+    fn divides(&self, other: &BigUint) -> bool { return self.is_multiple_of(other); }
+
+    /// Returns `true` if the number is a multiple of `other`.
+    #[inline]
+    fn is_multiple_of(&self, other: &BigUint) -> bool { (*self % *other).is_zero() }
 
     /// Returns `true` if the number is divisible by `2`.
     #[inline]
@@ -1112,9 +1117,14 @@ impl Integer for BigInt {
         BigInt::from_biguint(Plus, self.data.lcm(&other.data))
     }
 
-    /// Returns `true` if the number can be divided by `other` without leaving a remainder.
+    /// Deprecated, use `is_multiple_of` instead.
+    #[deprecated = "function renamed to `is_multiple_of`"]
+    #[inline]
+    fn divides(&self, other: &BigInt) -> bool { return self.is_multiple_of(other); }
+
+    /// Returns `true` if the number is a multiple of `other`.
     #[inline]
-    fn divides(&self, other: &BigInt) -> bool { self.data.divides(&other.data) }
+    fn is_multiple_of(&self, other: &BigInt) -> bool { self.data.is_multiple_of(&other.data) }
 
     /// Returns `true` if the number is divisible by `2`.
     #[inline]
diff --git a/src/libnum/integer.rs b/src/libnum/integer.rs
index bcaebbd1368..b06e2b448d4 100644
--- a/src/libnum/integer.rs
+++ b/src/libnum/integer.rs
@@ -77,16 +77,20 @@ pub trait Integer: Num + PartialOrd
     /// ~~~
     fn lcm(&self, other: &Self) -> Self;
 
-    /// Returns `true` if `other` divides evenly into `self`.
+    /// Deprecated, use `is_multiple_of` instead.
+    #[deprecated = "function renamed to `is_multiple_of`"]
+    fn divides(&self, other: &Self) -> bool;
+
+    /// Returns `true` if `other` is a multiple of `self`.
     ///
     /// # Examples
     ///
     /// ~~~
     /// # use num::Integer;
-    /// assert_eq!(9i.divides(&3), true);
-    /// assert_eq!(3i.divides(&9), false);
+    /// assert_eq!(9i.is_multiple_of(&3), true);
+    /// assert_eq!(3i.is_multiple_of(&9), false);
     /// ~~~
-    fn divides(&self, other: &Self) -> bool;
+    fn is_multiple_of(&self, other: &Self) -> bool;
 
     /// Returns `true` if the number is even.
     ///
@@ -231,10 +235,14 @@ macro_rules! impl_integer_for_int {
                 ((*self * *other) / self.gcd(other)).abs()
             }
 
-            /// Returns `true` if the number can be divided by `other` without
-            /// leaving a remainder
+            /// Deprecated, use `is_multiple_of` instead.
+            #[deprecated = "function renamed to `is_multiple_of`"]
+            #[inline]
+            fn divides(&self, other: &$T) -> bool { return self.is_multiple_of(other); }
+
+            /// Returns `true` if the number is a multiple of `other`.
             #[inline]
-            fn divides(&self, other: &$T) -> bool { *self % *other == 0 }
+            fn is_multiple_of(&self, other: &$T) -> bool { *self % *other == 0 }
 
             /// Returns `true` if the number is divisible by `2`
             #[inline]
@@ -393,21 +401,26 @@ macro_rules! impl_integer_for_uint {
                 n
             }
 
-            /// Calculates the Lowest Common Multiple (LCM) of the number and `other`
+            /// Calculates the Lowest Common Multiple (LCM) of the number and `other`.
             #[inline]
             fn lcm(&self, other: &$T) -> $T {
                 (*self * *other) / self.gcd(other)
             }
 
-            /// Returns `true` if the number can be divided by `other` without leaving a remainder
+            /// Deprecated, use `is_multiple_of` instead.
+            #[deprecated = "function renamed to `is_multiple_of`"]
             #[inline]
-            fn divides(&self, other: &$T) -> bool { *self % *other == 0 }
+            fn divides(&self, other: &$T) -> bool { return self.is_multiple_of(other); }
 
-            /// Returns `true` if the number is divisible by `2`
+            /// Returns `true` if the number is a multiple of `other`.
+            #[inline]
+            fn is_multiple_of(&self, other: &$T) -> bool { *self % *other == 0 }
+
+            /// Returns `true` if the number is divisible by `2`.
             #[inline]
             fn is_even(&self) -> bool { self & 1 == 0 }
 
-            /// Returns `true` if the number is not divisible by `2`
+            /// Returns `true` if the number is not divisible by `2`.
             #[inline]
             fn is_odd(&self) -> bool { !self.is_even() }
         }
@@ -449,10 +462,10 @@ macro_rules! impl_integer_for_uint {
             }
 
             #[test]
-            fn test_divides() {
-                assert!((6 as $T).divides(&(6 as $T)));
-                assert!((6 as $T).divides(&(3 as $T)));
-                assert!((6 as $T).divides(&(1 as $T)));
+            fn test_is_multiple_of() {
+                assert!((6 as $T).is_multiple_of(&(6 as $T)));
+                assert!((6 as $T).is_multiple_of(&(3 as $T)));
+                assert!((6 as $T).is_multiple_of(&(1 as $T)));
             }
 
             #[test]