From 2354a5f43ce61d623e51b53449582c005a39d913 Mon Sep 17 00:00:00 2001 From: Justin Worthe Date: Mon, 26 Dec 2016 20:48:45 +0200 Subject: Moved sinusoid usage example tests to documentation --- src/sinusoid.rs | 98 ++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 59 insertions(+), 39 deletions(-) diff --git a/src/sinusoid.rs b/src/sinusoid.rs index cc9c20c..fe8b3ad 100644 --- a/src/sinusoid.rs +++ b/src/sinusoid.rs @@ -1,9 +1,12 @@ use std::cmp::{PartialOrd}; use ::num_traits::{Trig, ArithmeticOps, FractionOps}; -// generic number type, but realistically it's only useful for -// floats. Maybe also complex - +/// A data structure representing a sinusoid. AKA the sin or cos functions. +/// +/// The general formula for a sinusoid is A cos(2πf + θ) +/// +/// The number type is generic, but realistically it's only useful for +/// floats. pub struct Sinusoid { amplitude: T, frequency: T, @@ -20,20 +23,72 @@ impl Sinusoid { } } impl Sinusoid where T: FractionOps + Copy { + /// The period is the time taken for each repetition of the + /// sinusoid + /// + /// ``` + /// use worthe_signals::sinusoid::Sinusoid; + /// use std::f32; + /// + /// let sinusoid = Sinusoid::new(1.0 as f32, 0.5, 0.0); + /// assert!((sinusoid.period()-2.0) < f32::EPSILON); + /// ``` pub fn period(&self) -> T { self.frequency.recip() } } impl Sinusoid where T: FractionOps + ArithmeticOps + Trig + Copy { + /// Frequency can be considered in terms of the signal's number of + /// repetitions per second (referred to just as the frequency), or + /// the frequency in radians. + /// ``` + /// use worthe_signals::sinusoid::Sinusoid; + /// use std::f32; + /// + /// let sinusoid = Sinusoid::new(1.0 as f32, 1.0, 0.0); + /// assert!((sinusoid.radial_frequency()-2.0*f32::consts::PI) < f32::EPSILON); + /// ``` pub fn radial_frequency(&self) -> T { T::two_pi()*self.frequency } + + /// A sinusoid can be sampled to get its value at a given point in + /// time. + /// + /// ``` + /// use worthe_signals::sinusoid::Sinusoid; + /// use std::f32; + /// + /// let sinusoid = Sinusoid::new(1.0 as f32, 1.0, -f32::consts::FRAC_PI_2); //AKA sin + /// assert!((sinusoid.sample(0.0)-0.0) < f32::EPSILON); + /// assert!((sinusoid.sample(0.25)-1.0) < f32::EPSILON); + /// assert!((sinusoid.sample(0.5)-0.0) < f32::EPSILON); + /// assert!((sinusoid.sample(0.75)+1.0) < f32::EPSILON); + /// assert!((sinusoid.sample(1.0)-0.0) < f32::EPSILON); + /// ``` pub fn sample(&self, t: T) -> T { (self.radial_frequency()*(t%self.period()) + self.phase).cos() * self.amplitude } } impl Sinusoid where T: FractionOps + ArithmeticOps + From + Trig + Copy + PartialOrd { - //inclusive of start, exclusive of end + /// Sometimes, it's useful to sample at all of the points in a range + /// + /// Start value is inclusive. End value is exclusive. + /// + /// ``` + /// use worthe_signals::sinusoid::Sinusoid; + /// use std::f32; + /// + /// let sinusoid = Sinusoid::new(1.0 as f32, 1.0, -f32::consts::FRAC_PI_2); //AKA sin + /// let samples = sinusoid.sample_range(0.0, 100.0, 4.0); + /// assert_eq!(samples.len(), 400); + /// for i in (0..100).map(|i| i*4) { + /// assert!((samples[i+0]-0.0) < f32::EPSILON, "Sample {} was {}", i+0, samples[i+0]); + /// assert!((samples[i+1]-1.0) < f32::EPSILON, "Sample {} was {}", i+1, samples[i+1]); + /// assert!((samples[i+2]-0.0) < f32::EPSILON, "Sample {} was {}", i+2, samples[i+2]); + /// assert!((samples[i+3]+1.0) < f32::EPSILON, "Sample {} was {}", i+3, samples[i+3]); + /// } + /// ``` pub fn sample_range(&self, start: T, end: T, sample_rate: T) -> Vec { let mut result = Vec::new(); let mut i: u16 = 0; @@ -55,39 +110,4 @@ mod tests { use super::*; use std::f32; - #[test] - fn period() { - let sinusoid = Sinusoid::new(1.0 as f32, 0.5, 0.0); - assert!((sinusoid.period()-2.0) < f32::EPSILON); - } - #[test] - fn radial_f() { - let sinusoid = Sinusoid::new(1.0 as f32, 1.0, 0.0); - assert!((sinusoid.radial_frequency()-2.0*f32::consts::PI) < f32::EPSILON); - } - - #[test] - fn sample() { - let sinusoid = Sinusoid::new(1.0 as f32, 1.0, -f32::consts::FRAC_PI_2); //AKA sin - - assert!((sinusoid.sample(0.0)-0.0) < f32::EPSILON); - assert!((sinusoid.sample(0.25)-1.0) < f32::EPSILON); - assert!((sinusoid.sample(0.5)-0.0) < f32::EPSILON); - assert!((sinusoid.sample(0.75)+1.0) < f32::EPSILON); - assert!((sinusoid.sample(1.0)-0.0) < f32::EPSILON); - } - - #[test] - fn sample_range() { - let sinusoid = Sinusoid::new(1.0 as f32, 1.0, -f32::consts::FRAC_PI_2); //AKA sin - let samples = sinusoid.sample_range(0.0, 100.0, 4.0); - println!("Epsilon is {}", f32::EPSILON); - assert_eq!(samples.len(), 400); - for i in (0..100).map(|i| i*4) { - assert!((samples[i+0]-0.0) < f32::EPSILON, "Sample {} was {}", i+0, samples[i+0]); - assert!((samples[i+1]-1.0) < f32::EPSILON, "Sample {} was {}", i+1, samples[i+1]); - assert!((samples[i+2]-0.0) < f32::EPSILON, "Sample {} was {}", i+2, samples[i+2]); - assert!((samples[i+3]+1.0) < f32::EPSILON, "Sample {} was {}", i+3, samples[i+3]); - } - } } -- cgit v1.2.3