From 59a91280084347ced9a27c8d05a211f50fe90737 Mon Sep 17 00:00:00 2001 From: Jonas Hietala Date: Mon, 28 Jul 2014 16:03:01 +0200 Subject: 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] --- src/libnum/bigint.rs | 18 ++++++++++++++---- src/libnum/integer.rs | 45 +++++++++++++++++++++++++++++---------------- 2 files changed, 43 insertions(+), 20 deletions(-) (limited to 'src/libnum') 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] -- cgit 1.4.1-3-g733a5 From f399d308028fb491427a34b2ac70db797536280b Mon Sep 17 00:00:00 2001 From: Piotr Jawniak Date: Mon, 28 Jul 2014 21:24:38 +0200 Subject: Improve documentation of rounding functions --- src/libcore/num/f32.rs | 34 +++++++++++++++++----------------- src/libcore/num/f64.rs | 35 +++++++++++++++++------------------ src/libnum/rational.rs | 27 +++++++++++++++++++-------- 3 files changed, 53 insertions(+), 43 deletions(-) (limited to 'src/libnum') diff --git a/src/libcore/num/f32.rs b/src/libcore/num/f32.rs index 82745663e0c..d4cf10b384f 100644 --- a/src/libcore/num/f32.rs +++ b/src/libcore/num/f32.rs @@ -117,23 +117,23 @@ impl Float for f32 { #[inline] fn neg_zero() -> f32 { -0.0 } - /// Returns `true` if the number is NaN + /// Returns `true` if the number is NaN. #[inline] fn is_nan(self) -> bool { self != self } - /// Returns `true` if the number is infinite + /// Returns `true` if the number is infinite. #[inline] fn is_infinite(self) -> bool { self == Float::infinity() || self == Float::neg_infinity() } - /// Returns `true` if the number is neither infinite or NaN + /// Returns `true` if the number is neither infinite or NaN. #[inline] fn is_finite(self) -> bool { !(self.is_nan() || self.is_infinite()) } - /// Returns `true` if the number is neither zero, infinite, subnormal or NaN + /// Returns `true` if the number is neither zero, infinite, subnormal or NaN. #[inline] fn is_normal(self) -> bool { self.classify() == FPNormal @@ -195,25 +195,25 @@ impl Float for f32 { (mantissa as u64, exponent, sign) } - /// Round half-way cases toward `NEG_INFINITY` + /// Rounds towards minus infinity. #[inline] fn floor(self) -> f32 { unsafe { intrinsics::floorf32(self) } } - /// Round half-way cases toward `INFINITY` + /// Rounds towards plus infinity. #[inline] fn ceil(self) -> f32 { unsafe { intrinsics::ceilf32(self) } } - /// Round half-way cases away from `0.0` + /// Rounds to nearest integer. Rounds half-way cases away from zero. #[inline] fn round(self) -> f32 { unsafe { intrinsics::roundf32(self) } } - /// The integer part of the number (rounds towards `0.0`) + /// Returns the integer part of the number (rounds towards zero). #[inline] fn trunc(self) -> f32 { unsafe { intrinsics::truncf32(self) } @@ -236,7 +236,7 @@ impl Float for f32 { unsafe { intrinsics::fmaf32(self, a, b) } } - /// The reciprocal (multiplicative inverse) of the number + /// Returns the reciprocal (multiplicative inverse) of the number. #[inline] fn recip(self) -> f32 { 1.0 / self } @@ -325,45 +325,45 @@ impl Float for f32 { #[inline] fn ln_10() -> f32 { consts::LN_10 } - /// Returns the exponential of the number + /// Returns the exponential of the number. #[inline] fn exp(self) -> f32 { unsafe { intrinsics::expf32(self) } } - /// Returns 2 raised to the power of the number + /// Returns 2 raised to the power of the number. #[inline] fn exp2(self) -> f32 { unsafe { intrinsics::exp2f32(self) } } - /// Returns the natural logarithm of the number + /// Returns the natural logarithm of the number. #[inline] fn ln(self) -> f32 { unsafe { intrinsics::logf32(self) } } - /// Returns the logarithm of the number with respect to an arbitrary base + /// Returns the logarithm of the number with respect to an arbitrary base. #[inline] fn log(self, base: f32) -> f32 { self.ln() / base.ln() } - /// Returns the base 2 logarithm of the number + /// Returns the base 2 logarithm of the number. #[inline] fn log2(self) -> f32 { unsafe { intrinsics::log2f32(self) } } - /// Returns the base 10 logarithm of the number + /// Returns the base 10 logarithm of the number. #[inline] fn log10(self) -> f32 { unsafe { intrinsics::log10f32(self) } } - /// Converts to degrees, assuming the number is in radians + /// Converts to degrees, assuming the number is in radians. #[inline] fn to_degrees(self) -> f32 { self * (180.0f32 / Float::pi()) } - /// Converts to radians, assuming the number is in degrees + /// Converts to radians, assuming the number is in degrees. #[inline] fn to_radians(self) -> f32 { let value: f32 = Float::pi(); diff --git a/src/libcore/num/f64.rs b/src/libcore/num/f64.rs index a3a82aeec5e..a3ae8e7c79e 100644 --- a/src/libcore/num/f64.rs +++ b/src/libcore/num/f64.rs @@ -123,23 +123,23 @@ impl Float for f64 { #[inline] fn neg_zero() -> f64 { -0.0 } - /// Returns `true` if the number is NaN + /// Returns `true` if the number is NaN. #[inline] fn is_nan(self) -> bool { self != self } - /// Returns `true` if the number is infinite + /// Returns `true` if the number is infinite. #[inline] fn is_infinite(self) -> bool { self == Float::infinity() || self == Float::neg_infinity() } - /// Returns `true` if the number is neither infinite or NaN + /// Returns `true` if the number is neither infinite or NaN. #[inline] fn is_finite(self) -> bool { !(self.is_nan() || self.is_infinite()) } - /// Returns `true` if the number is neither zero, infinite, subnormal or NaN + /// Returns `true` if the number is neither zero, infinite, subnormal or NaN. #[inline] fn is_normal(self) -> bool { self.classify() == FPNormal @@ -201,25 +201,25 @@ impl Float for f64 { (mantissa, exponent, sign) } - /// Round half-way cases toward `NEG_INFINITY` + /// Rounds towards minus infinity. #[inline] fn floor(self) -> f64 { unsafe { intrinsics::floorf64(self) } } - /// Round half-way cases toward `INFINITY` + /// Rounds towards plus infinity. #[inline] fn ceil(self) -> f64 { unsafe { intrinsics::ceilf64(self) } } - /// Round half-way cases away from `0.0` + /// Rounds to nearest integer. Rounds half-way cases away from zero. #[inline] fn round(self) -> f64 { unsafe { intrinsics::roundf64(self) } } - /// The integer part of the number (rounds towards `0.0`) + /// Returns the integer part of the number (rounds towards zero). #[inline] fn trunc(self) -> f64 { unsafe { intrinsics::truncf64(self) } @@ -242,7 +242,7 @@ impl Float for f64 { unsafe { intrinsics::fmaf64(self, a, b) } } - /// The reciprocal (multiplicative inverse) of the number + /// Returns the reciprocal (multiplicative inverse) of the number. #[inline] fn recip(self) -> f64 { 1.0 / self } @@ -332,46 +332,45 @@ impl Float for f64 { #[inline] fn ln_10() -> f64 { consts::LN_10 } - /// Returns the exponential of the number + /// Returns the exponential of the number. #[inline] fn exp(self) -> f64 { unsafe { intrinsics::expf64(self) } } - /// Returns 2 raised to the power of the number + /// Returns 2 raised to the power of the number. #[inline] fn exp2(self) -> f64 { unsafe { intrinsics::exp2f64(self) } } - /// Returns the natural logarithm of the number + /// Returns the natural logarithm of the number. #[inline] fn ln(self) -> f64 { unsafe { intrinsics::logf64(self) } } - /// Returns the logarithm of the number with respect to an arbitrary base + /// Returns the logarithm of the number with respect to an arbitrary base. #[inline] fn log(self, base: f64) -> f64 { self.ln() / base.ln() } - /// Returns the base 2 logarithm of the number + /// Returns the base 2 logarithm of the number. #[inline] fn log2(self) -> f64 { unsafe { intrinsics::log2f64(self) } } - /// Returns the base 10 logarithm of the number + /// Returns the base 10 logarithm of the number. #[inline] fn log10(self) -> f64 { unsafe { intrinsics::log10f64(self) } } - - /// Converts to degrees, assuming the number is in radians + /// Converts to degrees, assuming the number is in radians. #[inline] fn to_degrees(self) -> f64 { self * (180.0f64 / Float::pi()) } - /// Converts to radians, assuming the number is in degrees + /// Converts to radians, assuming the number is in degrees. #[inline] fn to_radians(self) -> f64 { let value: f64 = Float::pi(); diff --git a/src/libnum/rational.rs b/src/libnum/rational.rs index a279ede6fa5..e0f6b4fb9af 100644 --- a/src/libnum/rational.rs +++ b/src/libnum/rational.rs @@ -38,13 +38,13 @@ pub type BigRational = Ratio; impl Ratio { - /// Create a ratio representing the integer `t`. + /// Creates a ratio representing the integer `t`. #[inline] pub fn from_integer(t: T) -> Ratio { Ratio::new_raw(t, One::one()) } - /// Create a ratio without checking for `denom == 0` or reducing. + /// Creates a ratio without checking for `denom == 0` or reducing. #[inline] pub fn new_raw(numer: T, denom: T) -> Ratio { Ratio { numer: numer, denom: denom } @@ -61,7 +61,7 @@ impl ret } - /// Convert to an integer. + /// Converts to an integer. #[inline] pub fn to_integer(&self) -> T { self.trunc().numer @@ -79,7 +79,7 @@ impl &self.denom } - /// Return true if the rational number is an integer (denominator is 1). + /// Returns true if the rational number is an integer (denominator is 1). #[inline] pub fn is_integer(&self) -> bool { self.denom == One::one() @@ -103,19 +103,21 @@ impl } } - /// Return a `reduce`d copy of self. + /// Returns a `reduce`d copy of self. pub fn reduced(&self) -> Ratio { let mut ret = self.clone(); ret.reduce(); ret } - /// Return the reciprocal + /// Returns the reciprocal. #[inline] pub fn recip(&self) -> Ratio { Ratio::new_raw(self.denom.clone(), self.numer.clone()) } + /// Rounds towards minus infinity. + #[inline] pub fn floor(&self) -> Ratio { if *self < Zero::zero() { Ratio::from_integer((self.numer - self.denom + One::one()) / self.denom) @@ -124,6 +126,8 @@ impl } } + /// Rounds towards plus infinity. + #[inline] pub fn ceil(&self) -> Ratio { if *self < Zero::zero() { Ratio::from_integer(self.numer / self.denom) @@ -132,8 +136,12 @@ impl } } + /// Rounds to the nearest integer. Rounds half-way cases away from zero. + /// + /// Note: This function is currently broken and always rounds away from zero. #[inline] pub fn round(&self) -> Ratio { + // FIXME(#15826) if *self < Zero::zero() { Ratio::from_integer((self.numer - self.denom + One::one()) / self.denom) } else { @@ -141,18 +149,21 @@ impl } } + /// Rounds towards zero. #[inline] pub fn trunc(&self) -> Ratio { Ratio::from_integer(self.numer / self.denom) } + ///Returns the fractional part of a number. + #[inline] pub fn fract(&self) -> Ratio { Ratio::new_raw(self.numer % self.denom, self.denom.clone()) } } impl Ratio { - /// Converts a float into a rational number + /// Converts a float into a rational number. pub fn from_float(f: T) -> Option { if !f.is_finite() { return None; @@ -328,7 +339,7 @@ impl ToStrRadix for Ratio { impl FromStr for Ratio { - /// Parses `numer/denom` or just `numer` + /// Parses `numer/denom` or just `numer`. fn from_str(s: &str) -> Option> { let mut split = s.splitn('/', 1); -- cgit 1.4.1-3-g733a5