Improve Ratio docs
Closes #208. Clarifies the rounding behavior of some methods and makes formatting more uniform.
This commit is contained in:
parent
29c5ab362d
commit
c84c4d15ba
|
@ -56,13 +56,13 @@ pub type Rational64 = Ratio<i64>;
|
||||||
pub type BigRational = Ratio<BigInt>;
|
pub type BigRational = Ratio<BigInt>;
|
||||||
|
|
||||||
impl<T: Clone + Integer> Ratio<T> {
|
impl<T: Clone + Integer> Ratio<T> {
|
||||||
/// Creates a ratio representing the integer `t`.
|
/// Creates a `Ratio` representing the integer `t`.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn from_integer(t: T) -> Ratio<T> {
|
pub fn from_integer(t: T) -> Ratio<T> {
|
||||||
Ratio::new_raw(t, One::one())
|
Ratio::new_raw(t, One::one())
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Creates a ratio without checking for `denom == 0` or reducing.
|
/// Creates a `Ratio` without checking for `denom == 0` or reducing.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn new_raw(numer: T, denom: T) -> Ratio<T> {
|
pub fn new_raw(numer: T, denom: T) -> Ratio<T> {
|
||||||
Ratio {
|
Ratio {
|
||||||
|
@ -71,7 +71,7 @@ impl<T: Clone + Integer> Ratio<T> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Create a new Ratio. Fails if `denom == 0`.
|
/// Creates a new `Ratio`. Fails if `denom == 0`.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn new(numer: T, denom: T) -> Ratio<T> {
|
pub fn new(numer: T, denom: T) -> Ratio<T> {
|
||||||
if denom == Zero::zero() {
|
if denom == Zero::zero() {
|
||||||
|
@ -82,7 +82,7 @@ impl<T: Clone + Integer> Ratio<T> {
|
||||||
ret
|
ret
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Converts to an integer.
|
/// Converts to an integer, rounding towards zero.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn to_integer(&self) -> T {
|
pub fn to_integer(&self) -> T {
|
||||||
self.trunc().numer
|
self.trunc().numer
|
||||||
|
@ -106,7 +106,7 @@ impl<T: Clone + Integer> Ratio<T> {
|
||||||
self.denom == One::one()
|
self.denom == One::one()
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Put self into lowest terms, with denom > 0.
|
/// Puts self into lowest terms, with denom > 0.
|
||||||
fn reduce(&mut self) {
|
fn reduce(&mut self) {
|
||||||
let g: T = self.numer.gcd(&self.denom);
|
let g: T = self.numer.gcd(&self.denom);
|
||||||
|
|
||||||
|
@ -124,7 +124,10 @@ impl<T: Clone + Integer> Ratio<T> {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Returns a `reduce`d copy of self.
|
/// Returns a reduced copy of self.
|
||||||
|
///
|
||||||
|
/// In general, it is not necessary to use this method, as the only
|
||||||
|
/// method of procuring a non-reduced fraction is through `new_raw`.
|
||||||
pub fn reduced(&self) -> Ratio<T> {
|
pub fn reduced(&self) -> Ratio<T> {
|
||||||
let mut ret = self.clone();
|
let mut ret = self.clone();
|
||||||
ret.reduce();
|
ret.reduce();
|
||||||
|
@ -201,7 +204,9 @@ impl<T: Clone + Integer> Ratio<T> {
|
||||||
Ratio::from_integer(self.numer.clone() / self.denom.clone())
|
Ratio::from_integer(self.numer.clone() / self.denom.clone())
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Returns the fractional part of a number.
|
/// Returns the fractional part of a number, with division rounded towards zero.
|
||||||
|
///
|
||||||
|
/// Satisfies `self == self.trunc() + self.fract()`.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn fract(&self) -> Ratio<T> {
|
pub fn fract(&self) -> Ratio<T> {
|
||||||
Ratio::new_raw(self.numer.clone() % self.denom.clone(), self.denom.clone())
|
Ratio::new_raw(self.numer.clone() % self.denom.clone(), self.denom.clone())
|
||||||
|
@ -209,7 +214,7 @@ impl<T: Clone + Integer> Ratio<T> {
|
||||||
}
|
}
|
||||||
|
|
||||||
impl<T: Clone + Integer + PrimInt> Ratio<T> {
|
impl<T: Clone + Integer + PrimInt> Ratio<T> {
|
||||||
/// Raises the ratio to the power of an exponent
|
/// Raises the `Ratio` to the power of an exponent.
|
||||||
#[inline]
|
#[inline]
|
||||||
pub fn pow(&self, expon: i32) -> Ratio<T> {
|
pub fn pow(&self, expon: i32) -> Ratio<T> {
|
||||||
match expon.cmp(&0) {
|
match expon.cmp(&0) {
|
||||||
|
|
Loading…
Reference in New Issue