[−][src]Struct tune::ratio::Ratio
Struct representing the relative distance between two pitches.
Mathematically, this distance can be interpreted as the factor between the two pitches in linear frequency space or as the offset between them in logarithmic frequency space.
The Ratio
struct offers both linear and logarithmic accessors to the encapsulated distance.
It is possible to convert between the different representations by using from_<repr1>
and as_<repr2>
in
combination where <reprN>
can be a linear (float
) or logarithmic (cents
, semitones
, octaves
) quantity.
Examples
assert_approx_eq!(Ratio::from_float(1.5).as_cents(), 701.955); assert_approx_eq!(Ratio::from_cents(400.0).as_semitones(), 4.0); assert_approx_eq!(Ratio::from_semitones(3.0).as_octaves(), 0.25); assert_approx_eq!(Ratio::from_octaves(3.0).as_float(), 8.0);
Panics
Panics if the linear value is not a finite positive number.
Ratio::from_cents(0.0); // This is Ok Ratio::from_cents(-3.0); // This is Ok
Ratio::from_float(0.0); // But this isn't. Should be positive.
Implementations
impl Ratio
[src]
pub fn from_float(float_value: f64) -> Self
[src]
pub fn from_cents(cents_value: f64) -> Self
[src]
pub fn from_semitones(semitones: impl Into<f64>) -> Self
[src]
pub fn from_octaves(octaves: impl Into<f64>) -> Self
[src]
pub fn octave() -> Self
[src]
pub fn between_pitches(pitch_a: impl Pitched, pitch_b: impl Pitched) -> Self
[src]
Creates a new Ratio
instance based on the relative distance between two Pitched
entities.
Examples
let pitch_330_hz = Pitch::from_hz(330.0); let pitch_440_hz = Pitch::from_hz(440.0); assert_approx_eq!(Ratio::between_pitches(pitch_330_hz, pitch_440_hz).as_float(), 4.0 / 3.0);
pub fn stretched_by(self, stretch: Ratio) -> Ratio
[src]
Stretches self
by the provided stretch
.
This reverses Ratio::deviation_from
.
Examples
assert_approx_eq!(Ratio::octave().stretched_by(Ratio::from_cents(10.0)).as_cents(), 1210.0);
pub fn deviation_from(self, reference: Ratio) -> Ratio
[src]
Calculates the difference between the provided reference
and self
.
This reverses Ratio::stretched_by
.
Examples
assert_approx_eq!(Ratio::from_cents(1210.0).deviation_from(Ratio::octave()).as_cents(), 10.0);
pub fn repeated(self, num_repetitions: impl Into<f64>) -> Ratio
[src]
Creates a new Ratio
instance by applying self
num_repetitions
times.
This reverses Ratio::divided_into_equal_steps
or Ratio::num_equal_steps_of_size
.
Examples
assert_approx_eq!(Ratio::from_semitones(2.0).repeated(3).as_semitones(), 6.0);
pub fn divided_into_equal_steps(self, num_steps: impl Into<f64>) -> Ratio
[src]
Returns the Ratio
resulting from dividing self
into num_steps
equal steps.
This reverses Ratio::repeated
.
Examples
assert_approx_eq!(Ratio::octave().divided_into_equal_steps(15).as_cents(), 80.0);
pub fn num_equal_steps_of_size(self, step_size: Ratio) -> f64
[src]
Determines how many equal steps of size step_size
fit into `self.
This reverses Ratio::repeated
.
Examples
assert_approx_eq!(Ratio::octave().num_equal_steps_of_size(Ratio::from_cents(80.0)), 15.0);
pub fn as_float(self) -> f64
[src]
pub fn as_cents(self) -> f64
[src]
pub fn as_semitones(self) -> f64
[src]
pub fn as_octaves(self) -> f64
[src]
pub fn inv(self) -> Ratio
[src]
assert_approx_eq!(Ratio::from_float(4.0).inv().as_float(), 0.25); assert_approx_eq!(Ratio::from_cents(150.0).inv().as_cents(), -150.0);
pub fn nearest_fraction(self, limit: u16) -> NearestFraction
[src]
Finds a rational number approximation of the current Ratio instance.
The largest acceptable numerator or denominator can be controlled using the limit
parameter.
Only odd factors are compared against the limit
which means that 12 is 3, effectively, while 11 stays 11.
Read the documentation of math::odd_factors_u16
for more examples.
Examples
A minor seventh can be approximated by 16/9.
let minor_seventh = Ratio::from_semitones(10); let limit = 11; let f = minor_seventh.nearest_fraction(9); assert_eq!((f.numer, f.denom), (16, 9)); assert_eq!(f.num_octaves, 0); assert_approx_eq!(f.deviation.as_cents(), 3.910002); // Quite good!
Reducing the limit
saves computation time but may lead to a bad approximation.
let limit = 5; let f = minor_seventh.nearest_fraction(limit); assert_eq!((f.numer, f.denom), (5, 3)); assert_eq!(f.num_octaves, 0); assert_approx_eq!(f.deviation.as_cents(), 115.641287); // Pretty bad!
The approximation is normalized to values within an octave. The number of octaves is reported separately.
let lower_than_an_octave = Ratio::from_float(3.0 / 4.0); let f = lower_than_an_octave.nearest_fraction(11); assert_eq!((f.numer, f.denom), (3, 2)); assert_eq!(f.num_octaves, -1); assert_approx_eq!(f.deviation.as_cents(), 0.0);
Trait Implementations
impl Clone for Ratio
[src]
impl Copy for Ratio
[src]
impl Debug for Ratio
[src]
impl Default for Ratio
[src]
The default Ratio
is the ratio that respresents equivalence of two frequencies, i.e. no distance at all.
Examples
assert_approx_eq!(Ratio::default().as_float(), 1.0); // Neutral element for multiplication assert_approx_eq!(Ratio::default().as_cents(), 0.0); // Neutral element for addition
impl Display for Ratio
[src]
Ratio
s can be formatted as float or cents.
Examples
// As float assert_eq!(format!("{}", Ratio::from_float(1.5)), "1.5000"); assert_eq!(format!("{}", Ratio::from_float(1.0 / 1.5)), "0.6667"); assert_eq!(format!("{:.2}", Ratio::from_float(1.0 / 1.5)), "0.67"); // As cents assert_eq!(format!("{:#}", Ratio::from_float(1.5)), "+702.0c"); assert_eq!(format!("{:#}", Ratio::from_float(1.0 / 1.5)), "-702.0c"); assert_eq!(format!("{:#.2}", Ratio::from_float(1.0 / 1.5)), "-701.96c"); // With padding assert_eq!(format!("{:=^#14.2}", Ratio::from_float(1.5)), "===+701.96c===");
impl Div<Ratio> for Pitch
[src]
Lower a Pitch
by a given Ratio
.
Examples
assert_approx_eq!((Pitch::from_hz(330.0) / Ratio::from_float(1.5)).as_hz(), 220.0);
type Output = Pitch
The resulting type after applying the /
operator.
fn div(self, rhs: Ratio) -> Self::Output
[src]
impl FromStr for Ratio
[src]
Ratio
s can be parsed using tune
's built-in expression language.
Examples
assert_approx_eq!("1.5".parse::<Ratio>().unwrap().as_float(), 1.5); assert_approx_eq!("3/2".parse::<Ratio>().unwrap().as_float(), 1.5); assert_approx_eq!("7:12:2".parse::<Ratio>().unwrap().as_semitones(), 7.0); assert_approx_eq!("702c".parse::<Ratio>().unwrap().as_cents(), 702.0); assert_eq!("foo".parse::<Ratio>().unwrap_err(), "Invalid expression \'foo\': Must be a float (e.g. 1.5), fraction (e.g. 3/2), interval fraction (e.g. 7:12:2) or cents value (e.g. 702c)");
type Err = String
The associated error which can be returned from parsing.
fn from_str(s: &str) -> Result<Self, Self::Err>
[src]
impl Mul<Ratio> for Pitch
[src]
Raise a Pitch
by a given Ratio
.
Examples
assert_approx_eq!((Pitch::from_hz(220.0) * Ratio::from_float(1.5)).as_hz(), 330.0);
type Output = Pitch
The resulting type after applying the *
operator.
fn mul(self, rhs: Ratio) -> Self::Output
[src]
impl PartialEq<Ratio> for Ratio
[src]
impl PartialOrd<Ratio> for Ratio
[src]
fn partial_cmp(&self, other: &Ratio) -> Option<Ordering>
[src]
fn lt(&self, other: &Ratio) -> bool
[src]
fn le(&self, other: &Ratio) -> bool
[src]
fn gt(&self, other: &Ratio) -> bool
[src]
fn ge(&self, other: &Ratio) -> bool
[src]
impl StructuralPartialEq for Ratio
[src]
Auto Trait Implementations
impl RefUnwindSafe for Ratio
impl Send for Ratio
impl Sync for Ratio
impl Unpin for Ratio
impl UnwindSafe for Ratio
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
fn to_owned(&self) -> T
[src]
fn clone_into(&self, target: &mut T)
[src]
impl<T> ToString for T where
T: Display + ?Sized,
[src]
T: Display + ?Sized,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,