/*****************************************************************************
*                                                                            *
*   GSTEPS.SPL    Copyright (C) 2012 DSP Development Corporation             *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     Generates series of step heights                           *
*                                                                            *
*   Revisions:    12 Apr 2012  RRR  Creation                                 *
*                                                                            *
*****************************************************************************/


#if @HELP_GSTEPS

    GSTEPS

    Purpose: Generates a series of step heights.

    Syntax:  GSTEPS(heights, lengths, dx)

               heights - A series, the height of each step segment.

               lengths - A series or integer, the length of each step segment.

                    dx - Optional. A real, the delta X value. Defaults to 1.0.

    Returns: A series, a sequence of step heights.

    Example:
             gsteps({1, 3, 2}, 100)

             Generates a 300 point series where the first 100 points have
             a value of 1, the second 100 points have a value of 3 and the
             final 100 points have a value of 2.

    Example:
             gstep({1, 3, 2}, 100, 0.5)

             Same as above except the resulting delta x value is 0.5.

    Example:
             gsteps({1, 3, 2}, {10, 20, 15})

             Generates a 45 point series where the first 10 points have
             a value of 1, the second 20 points have a value of 3 and the
             final 15 points have a value of 2.

    Example:
             gsteps({1, 3, 2}, {10, 20, 15}, 0.5)

             Same as above except the resulting delta x value is 0.5.

    Remarks:
             The LENGTHS series determines the length of each step segment.
             If LENGTHS is an integer, the length of each step sequence will
             be equal to LENGTHS.

             If the length of LENGTHS is less than the length of HEIGHTS,
             the last LENGTHS value will be used for the length of 
             subsequent steps.

    See Also:
             Append
             Ones

#endif


/* generate steps of specified heights and lengths */
gsteps(heights, lengths, dx)
{
        local j, len, lsize, s = {};

        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error("gsteps - series of step heights required");

                        lengths = 100;
                }

                dx = 1.0;
        }

        /* ensure series */
        heights = castseries(heights);
        lengths = castseries(lengths);

        lsize = length(lengths);
        len   = 100;

        loop (j = 1..length(heights))
        {
                /* step length */
                len = (j > lsize) ? len : round(lengths[j]);

                /* append step */
                s @= ones(len, 1) * heights[j];
        }

        /* set deltax */
        setdeltax(s, dx);

        return(s);
}