/*!

**rust iterators that yield
[generalized cosine](https://snd.github.io/apodize/apodize/fn.cosine_iter.html),
[hanning](https://snd.github.io/apodize/apodize/fn.hanning_iter.html),
[hamming](https://snd.github.io/apodize/apodize/fn.hamming_iter.html),
[blackman](https://snd.github.io/apodize/apodize/fn.blackman_iter.html),
[nuttall](https://snd.github.io/apodize/apodize/fn.nuttall_iter.html)
and
[triangular](https://snd.github.io/apodize/apodize/fn.triangular_iter.html)
windows**

useful for
smoothing the sharp discontinuities at the edges (beginning and end)
of each slice of samples when doing a
[short time fourier transform](https://en.wikipedia.org/wiki/Short-time_Fourier_transform).
windowing also improves temporal resolution by making
the signal near the time
being analyzed have higher weight than the signal
further away from the time being analyzed.

to use add `apodize = "*"`
to the `[dependencies]` section of your `Cargo.toml` and call `extern crate apodize;` in your code.

all functions use `f64`s.
previously they were generic over the floating type used.
this was removed because it introduced a lot of complexity.
if you need `f32`s just `.map(|x| x as f32)` over the iterator.

## example

you will most likely want to collect the yielded values
in a vector and then multiply that window vector repeatedly with some
data vectors to apodize them.

here is an example of that for a hanning window (hamming, blackman and nuttall are analogous).

```
use std::ops::Mul;

#[macro_use]
extern crate nalgebra;
use nalgebra::{ApproxEq, DVec};

#[macro_use]
extern crate apodize;
use apodize::{hanning_iter};

fn main() {
    // create a hanning window iterator of size 7
    // and collect the values it yields in an nalgebra::DVec.
    let window = hanning_iter(7).collect::<DVec<_>>();

    assert_approx_eq_ulps!(
        window,
        dvec![
            0.0,
            0.24999999999999994,
            0.7499999999999999,
            1.0,
            0.7500000000000002,
            0.25,
            0.0],
        10);

    // some data we want to apodize (multiply with the window)
    let data: DVec<f64> = dvec![1., 2., 3., 4., 5., 6., 7.];

    // multiply data with window
    let windowed_data = window.mul(data);

    assert_approx_eq_ulps!(
        windowed_data,
        dvec![
            0.0,
            0.4999999999999999,
            2.2499999999999996,
            4.0,
            3.750000000000001,
            1.5,
            0.0],
        10);
}
```
*/

use std::f64::consts::PI;

extern crate num;
use num::{FromPrimitive};

macro_rules! f64_from_usize {
    ($val:expr) => {
        <f64>::from_usize($val)
            .expect("type `f64` can't represent a specific value of type `usize` on this architecture. use a smaller window size!");
    }
}

/// build an `nalgebra::DVec` as easy as a `std::Vec`.
/// for shorter, more readable code in tests and examples.
#[macro_export]
macro_rules! dvec {
    ($( $x:expr ),*) => { DVec {at: vec![$($x),*]} };
    ($($x:expr,)*) => { dvec![$($x),*] };
}

/// holds the window coefficients and
/// iteration state of an iterator for a cosine window
pub struct CosineWindowIter {
    /// coefficient `a` of the cosine window
    pub a: f64,
    /// coefficient `b` of the cosine window
    pub b: f64,
    /// coefficient `c` of the cosine window
    pub c: f64,
    /// coefficient `d` of the cosine window
    pub d: f64,
    /// the current `index` of the iterator
    pub index: usize,
    /// `size` of the cosine window
    pub size: usize,
}

impl Iterator for CosineWindowIter {
    type Item = f64;

    #[inline]
    fn next(&mut self) -> Option<f64> {
        if self.index == self.size {
            return None;
        }
        let index = self.index;
        self.index += 1;
        Some(cosine_at(self.a,
                       self.b,
                       self.c,
                       self.d,
                       self.size,
                       index))
    }

    #[inline]
    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.size - self.index;
        (remaining, Some(remaining))
    }
}

impl ExactSizeIterator for CosineWindowIter {
    #[inline]
    fn len(&self) -> usize { self.size }
}

/// returns the value of the [cosine
/// window](https://en.wikipedia.org/wiki/Window_function#Higher-order_generalized_cosine_windows)
/// of `size`
/// with the coefficients `a`, `b`, `c` and `d`
/// at `index`
/// # Panics
/// panics unless `1 < size`
#[inline]
pub fn cosine_at(
    a: f64,
    b: f64,
    c: f64,
    d: f64,
    size: usize,
    index: usize
) -> f64
{
    let x = (PI * f64_from_usize!(index)) / (f64_from_usize!(size) - 1.);
    let b_ = b * (2. * x).cos();
    let c_ = c * (4. * x).cos();
    let d_ = d * (6. * x).cos();
    (a - b_) + (c_ - d_)
}

/// returns an iterator that yields the values for a [cosine
/// window](https://en.wikipedia.org/wiki/Window_function#Hann_.28Hanning.29_window) of `size`
/// with the coefficients `a`, `b`, `c` and `d`
/// # Panics
/// panics unless `1 < size`
pub fn cosine_iter(
    a: f64,
    b: f64,
    c: f64,
    d: f64,
    size: usize)
    -> CosineWindowIter {
        assert!(1 < size);
        CosineWindowIter {
            a: a,
            b: b,
            c: c,
            d: d,
            index: 0,
            size: size,
        }
    }

/// returns an iterator that yields the values for a [hanning
/// window](https://en.wikipedia.org/wiki/Window_function#Hann_.28Hanning.29_window) of `size`
/// # Panics
/// panics unless `1 < size`
pub fn hanning_iter(size: usize) -> CosineWindowIter {
    cosine_iter(0.5, 0.5, 0., 0., size)
}

/// returns an iterator that yields the values for a [hamming
/// window](https://en.wikipedia.org/wiki/Window_function#Hamming_window) of `size`
/// # Panics
/// panics unless `1 < size`
pub fn hamming_iter(size: usize) -> CosineWindowIter {
    cosine_iter(0.54, 0.46, 0., 0., size)
}

/// returns an iterator that yields the values for a [blackman
/// window](https://en.wikipedia.org/wiki/Window_function#Blackman_windows) of `size`
/// # Panics
/// panics unless `1 < size`
pub fn blackman_iter(size: usize) -> CosineWindowIter {
    cosine_iter(0.35875, 0.48829, 0.14128, 0.01168, size)
}

/// returns an iterator that yields the values for a [nuttall
/// window](https://en.wikipedia.org/wiki/Window_function#Nuttall_window.2C_continuous_first_derivative) of `size`
/// # Panics
/// panics unless `1 < size`
pub fn nuttall_iter(size: usize) -> CosineWindowIter {
    cosine_iter(0.355768, 0.487396, 0.144232, 0.012604, size)
}

/// holds the iteration state of an iterator for a triangular window
pub struct TriangularWindowIter {
    pub l: usize,
    /// the current `index` of the iterator
    pub index: usize,
    /// `size` of the triangular window
    pub size: usize,
}

/// returns the value of the
/// [triangular window]
/// (https://en.wikipedia.org/wiki/Window_function#Triangular_window)
/// of `size`
/// at `index`
#[inline]
pub fn triangular_at(l: usize, size: usize, index: usize) -> f64 {
    // ends with zeros if l == size - 1
    // if l == size - 1 && index == 0 then 1 - 1 / 1 == 0
    // if l == size - 1 && index == size - 1 then 1 - 0 / 1 == 0
    1. - (
        (f64_from_usize!(index) - (f64_from_usize!(size) - 1.) / 2.)
        /
        (f64_from_usize!(l) / 2.)
    ).abs()
}

impl Iterator for TriangularWindowIter
{
    type Item = f64;

    #[inline]
    fn next(&mut self) -> Option<f64> {
        if self.index == self.size {
            return None;
        }
        let index = self.index;
        self.index += 1;
        Some(triangular_at(self.l, self.size, index))
    }

    #[inline]
    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.size - self.index;
        (remaining, Some(remaining))
    }
}

impl ExactSizeIterator for TriangularWindowIter {
    #[inline]
    fn len(&self) -> usize { self.size }
}

/// returns an iterator that yields the values for a [triangular
/// window](https://en.wikipedia.org/wiki/Window_function#Triangular_window)
/// if `l = size - 1` then the outermost values of the window are `0`.
/// if `l = size` then the outermost values of the window are higher.
/// if `l = size + 1` then the outermost values of the window are even higher.
/// # Panics
/// panics unless `0 < size`
pub fn triangular_iter(size: usize) -> TriangularWindowIter {
    assert!(0 < size);
    TriangularWindowIter {
        l: size,
        size: size,
        index: 0,
    }
}