/*****************************************************************************
*                                                                            *
*   UPSAMPLE.SPL Copyright (C) 2012 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Inserts zeros in preparation for FIR upsampling             *
*                                                                            *
*   Revisions:    2 Oct 2012  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_UPSAMPLE

    UPSAMPLE

    Purpose: Inserts N zeros between each sample for FIR upsampling.

    Syntax:  UPSAMPLE(s, n, offset)

                   s - A series, the input data.

                   n - An integer, the rate factor. Inserts N-1 zeros
                       between each sample, increasing the sample rate
                       by a factor of N. Defaults to 1, no rate change.

              offset - Optional. An integer, the starting offset for zero
                       insertion. Defaults to 0, start insertion after the
                       first sample. 

    Returns: A series, the zero inserted result.

    Example:
             W1: 1..5
             W2: upsample(w1, 2)

             W2 == {1, 0, 2, 0, 3, 0, 4, 0, 5}

             rate(w1) == 1
             rate(w2) == 2

    Example:
             W3: 1..5
             W4: upsample(w1, 3)

             W4 == {1, 0, 0, 2, 0, 0, 3, 0, 0, 4, 0, 0, 5, 0, 0}

             rate(w3) == 1
             rate(w4) == 3

    Example:
             W1: 1..5
             W2: upsample(w1, 3, 2)

             W2 == {0, 0, 1, 0, 0, 2, 0, 0, 3, 0, 0, 4, 0, 0, 5}

             rate(w1) == 1
             rate(w2) == 3

    Remarks:
             UPSAMPLE increases the sample rate of the input series by a
             factor of N by inserting N-1 zeros between each sample.

             An upsampled series can be interpolated by filtering
             the result with a low pass filter with a cut off frequency
             of Fs / 2 where Fs is the original sample rate.

    See Also:
             Decilp
             Decimate
             Downsample
             Interpolate
             Merge
             Resample
             Zeros
#endif


/* insert N-1 zeros */
ITERATE upsample(s, n, offset)
{
        local z;

        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error("upsample - input series required");

                        n = 1;
                }

                offset = 0;
        }

        n--;

        if (n > 0)
        {
                /* zeros with same delta x */
                z = zeros(length(s), 1, deltax(s));

                /* merge */
                s = merge(s, z, n, offset);

                if (offset > 0)
                {
                        /* prepend zeros */
                        s = extract(s, -offset + 1, length(s));
                }
        }

        return(s);
}