/*****************************************************************************
*                                                                            *
*   SERPAD.SPL   Copyright (C) 2010 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Pads a series or table with a specified value               *
*                                                                            *
*   Revisions:    5 Jul 2010  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/

#if @HELP_SERPAD

    SERPAD

    Purpose: Pads a series or table with a specified value.

    Syntax:  SERPAD(s, padlen, val)

                s    - A series or table, the input to pad.

              padlen - An integer or series, the desired output length.

              val    - Optional. A real, the padding value. Defaults to 0.0.


    Returns: A series or table, the padded result.

    Example:
             W1: 1..5
             W2: serpad(w1, 8, -1)

             W1 contains the series {1, 2, 3, 4, 5}. W2 pads the series
             to a length of 8 with the value -1. The resulting series is
             {1, 2, 3, 4, 5, -1, -1, -1}.

    Example:
             W1: 1..5
             W2: serpad(w1, 3, -1)

             W1 contains the series {1, 2, 3, 4, 5}. Because the padding
             length is less than the original series length, the resulting
             series is {1, 2, 3}.

    Example:
             W1: reshape(1..9, {2, 3, 4, 2})
             W2: serpad(w1, 4, -1)

             W1 contains the table:

             1  3  6
             2  4  7
                5  8
                   9

            W2 pads each column with a value of -1 so the desired length of
            each column is 4. The resulting 4x3 table is:

            {{ 1,  3, 6},
             { 2,  4, 7},
             {-1,  5, 8},
             {-1, -1, 9}}

    Example:
             W1: reshape(1..9, {2, 3, 4, 2})
             W2: serpad(w1, {3, 5, 6}, -1)

             W1 contains the table:

             1  3  6
             2  4  7
                5  8
                   9

            W2 pads each column with a value of -1 such that the desired
            length of column 1 is 3, the length of column 2 is 5 and the
            length of column 3 is 6. The resulting table is:

             1  3  6
             2  4  7
            -1  5  8
               -1  9
               -1 -1
                  -1

    Remarks:
             If the padding length is less than the series length, the input
             is extracted to the smaller length.

             To apply separate padding lengths for each column of an input
             table, set PADLEN to a series containing the desired lengths.

    See Also:
             Append
             Concat
             Extract
#endif


/* pads a table so each column is the same length */
serpad(s, padlen, val)
{
        local y, plen;

        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error("serpad - series required");
                        
                        padlen = 0;
                }
                
                val = 0.0;
        }

        if (isarray(padlen))
        {
                if (numcols(padlen) == 1)
                {
                        /* transpose for serpad_length */
                        padlen = padlen';
                }
        }

        /* get padding length for each column - 1xN series */
        plen = padlen - collength(s);

        /* pad each column to padlen - extracts if shorter */
        y = serpad_length(s, plen, val);

        return(y);
}


/* pad data based on 1xN series of lengths - one column at a time */
ITERATE serpad_length(s, plen, val)
{
        local y, pad;

        if (argc < 3)
        {
                if (argc < 2)
                {
                        if (argc < 1) error("serpad - series required");
                        
                        len = 0;
                }
                
                val = 0.0;
        }

        /* make sure pad length is integer */
        if ((plen = castint(plen)) > 0)
        {
                /* padding values */
                pad = ones(plen, 1) * val;

                /* pad series via concatenation */
                y = concat(s, pad);
        }
        else if (plen < 0)
        {
                /* pad length is shorter than series length - extract */
                y = extract(s, 1, length(s) + plen);
        }
        else
        {
                /* return original series */
                y = s;
        }
        
        return(y);
}