/*****************************************************************************
*                                                                            *
*   GNUTTALL.SPL   Copyright (C) 2021 DSP Development Corporation            *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Generates a Blackman-Nuttall window                         *
*                                                                            *
*   Revisions:   18 Oct 2021  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_GNUTTALL

    GNUTTALL

    Purpose: Generates a four term Blackman-Nuttall Window.

    Syntax:  GNUTTALL(N, spacing, "sym")

                     N - Number of points to generate.

               spacing - Spacing between points.

                 "sym" - Optional. A string, the symmetry mode.

                          "symmetric" : Starting and ending points are equal
                                        (default).

                          "periodic"  : Periodically extended window. Conforms 
                                        to ISO standard.

                          "iso"       : Same as "periodic".

    Returns: A series.

    Example:
             gnuttall(100, .01)

             Creates a symmetric 100-point Black-Nuttall window with points
             spaced with an interval of 0.01 using the following formula:

             w[k] = 0.3635819 - 0.4891775 * cos(2*pi*(k-1)/(N-1))
                              + 0.1365995 * cos(4*pi*(k-1)/(N-1))
                              - 0.0106411 * cos(6*pi*(k-1)/(N-1))

    Example:
             gnuttall(100, .01, "periodic")

             Creates a periodic 100-point Black-Nuttall window with points
             spaced with an interval of 0.01 using the following formula:

             w[k] = 0.3635819 - 0.4891775 * cos(2*pi*(k-1)/N)
                              + 0.1365995 * cos(4*pi*(k-1)/N)
                              - 0.0106411 * cos(6*pi*(k-1)/N)

    Remarks:
             The periodic Black-Nuttall window is constructed by the following
             window generation formula:

             w[k]  = a0 - a1 * cos(2*pi*(k-1)/N)
                        + a2 * cos(4*pi*(k-1)/N)
                        - a2 * cos(6*pi*(k-1)/N)

             where:

             a0 = 0.3635819
             a1 = 0.4891775
             a2 = 0.1365995
             a3 = 0.0106411

             The symmetric form can be constructed by setting N to N-1.

             The "sym" flag controls the window symmetry as follows: 

             "Symmetric" sets the first and last points to be equal. 
             An N point symmetric window can be constructed by creating
             an N-1 point periodic window and setting the Nth point to
             the value of the first point.

             "Periodic" or "iso" (the default) creates a periodic
             window function useful in spectrum analysis applications
             where the starting zero is preserved and the trailing zero
             is removed. "Periodic" or "iso" conforms to the ISO
             18431-1 standard for windowing functions.

             Use the NUTTALL function to automatically create and multiply
             a Black-Nuttall window with a series. For example:

               nuttall(W2)

             multiplies Window 2 with a Blackman-Nuttall window calculated
             to the same length and spacing as the series in W2.

             Blackman, Hamming, Hanning, Kaiser and Flattop windows are
             useful in creating FIR filters and in preprocessing series
             for FFT calculations.

    See Also:
             Blackman
             Fft
             Gflattop
             Ghamming
             Ghanning
             Gkaiser
             Psd
             Spectrum
#endif


/* generate an N point, three term Blackman-Nuttall window */
gnuttall(n, dx, sym)
{
        local a, w;

        (n, dx, sym) = gnuttall_parse_args(n, dx, sym);

        /* special cases */
        if (n == 0) return({});
        if (n == 1) return(ones(1, 1, dx));

        /* blackman-nuttall coefficients */
        a = {0.3635819, 0.4891775, 0.1365995, 0.0106411};

        /* generate window */
        w = gcoswin(a, n, dx, sym);

        return(w);
}


gnuttall_parse_args(n, dx, sym)
{
        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error("gnuttall - number of points required");
                        
                        dx = 1.0;
                }
                
                sym = "symmetric";
        }
        
        if (isstring(dx))
        {
                temp = dx;
                dx   = (isstring(sym)) ? 1.0 : sym;
                sym  = temp;
        }

        return(n, dx, sym);
}