From f4bedded8bb810145cb084181d6cfe5b170ef8fa Mon Sep 17 00:00:00 2001 From: Jay Anderson Date: Sat, 9 Nov 2013 23:11:39 -0700 Subject: Update docs for Fractional, Algebraic, Round, and Trigonometric traits. --- src/libstd/num/mod.rs | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) (limited to 'src') diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs index 3097a8e138e..97b3c8f615c 100644 --- a/src/libstd/num/mod.rs +++ b/src/libstd/num/mod.rs @@ -136,26 +136,87 @@ pub trait Integer: Num /// Calculates the Lowest Common Multiple (LCM) of the number and `other`. #[inline(always)] pub fn lcm(x: T, y: T) -> T { x.lcm(&y) } +/// A collection of rounding operations. pub trait Round { + /// Return the largest integer less than or equal to a number. + /// + /// # Example + /// + /// ```rust + /// assert_approx_eq!(1.3f32.floor(), 1.0); + /// assert_approx_eq!((-1.3f32).floor(), -2.0); + /// ``` fn floor(&self) -> Self; + + /// Return the smallest integer greater than or equal to a number. + /// + /// # Example + /// + /// ```rust + /// assert_approx_eq!(1.3f32.ceil(), 2.0); + /// assert_approx_eq!((-1.3f32).ceil(), -1.0); + /// ``` fn ceil(&self) -> Self; + + /// Return the nearest integer to a number. Round half-way cases away from + /// `0.0`. + /// + /// # Example + /// + /// ```rust + /// assert_approx_eq!(1.3f32.round(), 1.0); + /// assert_approx_eq!((-1.3f32).round(), -1.0); + /// assert_approx_eq!(1.5f32.round(), 2.0); + /// assert_approx_eq!((-1.5f32).round(), -2.0); + /// ``` fn round(&self) -> Self; + + /// Return the integer part of a number. + /// + /// # Example + /// + /// ```rust + /// assert_approx_eq!(1.3f32.round(), 1.0); + /// assert_approx_eq!((-1.3f32).round(), -1.0); + /// assert_approx_eq!(1.5f32.round(), 1.0); + /// assert_approx_eq!((-1.5f32).round(), -1.0); + /// ``` fn trunc(&self) -> Self; + + /// Return the fractional part of a number. + /// + /// # Example + /// + /// ```rust + /// assert_approx_eq!(1.3f32.round(), 0.3); + /// assert_approx_eq!((-1.3f32).round(), -0.3); + /// assert_approx_eq!(1.5f32.round(), 0.5); + /// assert_approx_eq!((-1.5f32).round(), -0.5); + /// ``` fn fract(&self) -> Self; } +/// Trait for common fractional operations. pub trait Fractional: Num + Orderable + Round + Div { + /// Take the reciprocal (inverse) of a number, `1/x`. fn recip(&self) -> Self; } +/// A collection of algebraic operations. pub trait Algebraic { + /// Raise a number to a power. fn pow(&self, n: &Self) -> Self; + /// Take the squre root of a number. fn sqrt(&self) -> Self; + /// Take the reciprocal (inverse) square root of a number, `1/sqrt(x)`. fn rsqrt(&self) -> Self; + /// Take the cubic root of a number. fn cbrt(&self) -> Self; + /// Calculate the length of the hypotenuse of a right-angle triangle given + /// legs of length `x` and `y`. fn hypot(&self, other: &Self) -> Self; } @@ -178,16 +239,44 @@ pub trait Algebraic { /// `y`. #[inline(always)] pub fn hypot(x: T, y: T) -> T { x.hypot(&y) } +/// A trait for trigonometric functions. pub trait Trigonometric { + /// Computes the sine of a number (in radians). fn sin(&self) -> Self; + /// Computes the cosine of a number (in radians). fn cos(&self) -> Self; + /// Computes the tangent of a number (in radians). fn tan(&self) -> Self; + /// Computes the arcsine of a number. Return value is in radians in + /// the range [-pi/2, pi/2] or NaN if the number is outside the range + /// [-1, 1]. fn asin(&self) -> Self; + /// Computes the arccosine of a number. Return value is in radians in + /// the range [0, pi] or NaN if the number is outside the range + /// [-1, 1]. fn acos(&self) -> Self; + /// Computes the arctangent of a number. Return value is in radians in the + /// range [-pi/2, pi/2]; fn atan(&self) -> Self; + /// Computes the four quadrant arctangent of a number, `y`, and another + /// number `x`. Return value is in radians in the range [-pi, pi]; + /// + /// # Example + /// + /// ```rust + /// let y = 3f32.sqrt(); + /// let x = 1f32; + /// let pi_3 = 1.04719758f32; + /// assert_approx_eq!(y.atan2(&x), pi_3); + /// let neg_2_pi_3 = -2.09439516f32; + /// assert_approx_eq!((-y).atan2(&(-x)), neg_2_pi_3); + /// ``` fn atan2(&self, other: &Self) -> Self; + + /// Simultaneously computes the sine and cosine of the number, `x`. Returns + /// `(sin(x), cos(x))`. fn sin_cos(&self) -> (Self, Self); } -- cgit 1.4.1-3-g733a5 From 6c02e81c7009d80b6999bd5d953a9c0beef5dc00 Mon Sep 17 00:00:00 2001 From: Jay Anderson Date: Sun, 10 Nov 2013 21:39:16 -0700 Subject: Add docs for traits Exponential, Hyperbolic, BitCount. --- src/libstd/num/mod.rs | 46 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) (limited to 'src') diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs index 97b3c8f615c..d1b760ccc7d 100644 --- a/src/libstd/num/mod.rs +++ b/src/libstd/num/mod.rs @@ -299,13 +299,20 @@ pub trait Trigonometric { /// Simultaneously computes the sine and cosine of the number. #[inline(always)] pub fn sin_cos(value: T) -> (T, T) { value.sin_cos() } +/// A trait exponential functions. pub trait Exponential { + /// Returns `e^(self)`, (the exponential function). fn exp(&self) -> Self; + /// Returns 2 raised to the power of the number, `2^(self)`. fn exp2(&self) -> Self; + /// Returns the natural logarithm of the number. fn ln(&self) -> Self; + /// Returns the logarithm of the number with respect to an arbitrary base. fn log(&self, base: &Self) -> Self; + /// Returns the base 2 logarithm of the number. fn log2(&self) -> Self; + /// Returns the base 10 logarithm of the number. fn log10(&self) -> Self; } @@ -323,19 +330,26 @@ pub trait Exponential { /// Returns the base 10 logarithm of the number. #[inline(always)] pub fn log10(value: T) -> T { value.log10() } +/// A trait hyperbolic functions. pub trait Hyperbolic: Exponential { + /// Hyperbolic sine function. fn sinh(&self) -> Self; + /// Hyperbolic cosine function. fn cosh(&self) -> Self; + /// Hyperbolic tangent function. fn tanh(&self) -> Self; + /// Inverse hyperbolic sine function. fn asinh(&self) -> Self; + /// Inverse hyperbolic cosine function. fn acosh(&self) -> Self; + /// Inverse hyperbolic tangent function. fn atanh(&self) -> Self; } -/// Hyperbolic cosine function. -#[inline(always)] pub fn sinh(value: T) -> T { value.sinh() } /// Hyperbolic sine function. +#[inline(always)] pub fn sinh(value: T) -> T { value.sinh() } +/// Hyperbolic cosine function. #[inline(always)] pub fn cosh(value: T) -> T { value.cosh() } /// Hyperbolic tangent function. #[inline(always)] pub fn tanh(value: T) -> T { value.tanh() } @@ -374,7 +388,10 @@ pub trait Real: Signed fn ln_10() -> Self; // Angular conversions + + /// Convert degrees to radians. fn to_degrees(&self) -> Self; + /// Convert radians to degrees. fn to_radians(&self) -> Self; } @@ -404,9 +421,34 @@ pub trait Bitwise: Not + Shl + Shr {} +/// A trait for common counting operations on bits. pub trait BitCount { + /// Returns the number of bits set in the number. + /// + /// # Example + /// + /// ```rust + /// let n = 0b0101000u16; + /// assert_eq!(n.population_count(), 2); + /// ``` fn population_count(&self) -> Self; + /// Returns the number of leading zeros in the number. + /// + /// # Example + /// + /// ```rust + /// let n = 0b0101000u16; + /// assert_eq!(n.leading_zeros(), 10); + /// ``` fn leading_zeros(&self) -> Self; + /// Returns the number of trailing zeros in the number. + /// + /// # Example + /// + /// ```rust + /// let n = 0b0101000u16; + /// assert_eq!(n.trailing_zeros(), 3); + /// ``` fn trailing_zeros(&self) -> Self; } -- cgit 1.4.1-3-g733a5 From deefb1f4b7bb6fc9a4145d698bea9cbf5953bd03 Mon Sep 17 00:00:00 2001 From: Jay Anderson Date: Mon, 11 Nov 2013 18:56:48 -0700 Subject: Got directions backwards in to_degrees and to_radians docs. --- src/libstd/num/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src') diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs index d1b760ccc7d..b21016e27d0 100644 --- a/src/libstd/num/mod.rs +++ b/src/libstd/num/mod.rs @@ -389,9 +389,9 @@ pub trait Real: Signed // Angular conversions - /// Convert degrees to radians. - fn to_degrees(&self) -> Self; /// Convert radians to degrees. + fn to_degrees(&self) -> Self; + /// Convert degrees to radians. fn to_radians(&self) -> Self; } -- cgit 1.4.1-3-g733a5 From 8a4be8080b434fec90d8b519414f27e219971ace Mon Sep 17 00:00:00 2001 From: Jay Anderson Date: Mon, 11 Nov 2013 20:52:42 -0700 Subject: Use constants instead of raw values. --- src/libstd/num/mod.rs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'src') diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs index b21016e27d0..873d66d401e 100644 --- a/src/libstd/num/mod.rs +++ b/src/libstd/num/mod.rs @@ -268,10 +268,8 @@ pub trait Trigonometric { /// ```rust /// let y = 3f32.sqrt(); /// let x = 1f32; - /// let pi_3 = 1.04719758f32; - /// assert_approx_eq!(y.atan2(&x), pi_3); - /// let neg_2_pi_3 = -2.09439516f32; - /// assert_approx_eq!((-y).atan2(&(-x)), neg_2_pi_3); + /// assert_approx_eq!(y.atan2(&x), f32::consts::PI / 3f32); + /// assert_approx_eq!((-y).atan2(&(-x)), - 2f32 * f32::consts::PI / 3f32); /// ``` fn atan2(&self, other: &Self) -> Self; -- cgit 1.4.1-3-g733a5