/*****************************************************************************
*                                                                            *
*   VSUMS.SPL   Copyright (C) 2014 DSP Development Corporation               *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Returns the point by point sum of one or more inputs        *
*                                                                            *
*   Revisions:   22 Sep 2014  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_VSUMS

    VSUMS

    Purpose: Returns the point by point sum of one or more input arguments.

    Syntax:  VSUMS(val1, val2, ..., valN)

               valN - One ore more series or scalars.

    Returns: A series, the point by point sum of all the input values.

    Example:
             vsums(10, 15, 20)

             returns {45}

    Example:
             W1: vsums({1, 2, 3, 4, 5}, {1, 4, 2}, {1, 0, 3, 8})

             W1 == {3, 6, 8, 12, 5}

    Example:
             W1: ravel(1..9, 3)
             W2: ravel(11..26, 4)
             W3: vsums(W1, W2)

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

             W2 == {{11, 15, 19, 23},
                    {12, 16, 20, 24},
                    {13, 17, 21, 25},
                    {14, 18, 22, 26}}

             W3 == {{12, 19, 26, 23},
                    {14, 21, 28, 24},
                    {16, 23, 30, 25},
                    {14, 18, 22, 26)}

    Example:
             W1: ravel(1..9, 3)
             W2: {1}
             W3: sums(W1, W2)
             W4: vsums(W1, W2)

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

             W2 == {1}

             W3 == {{2, 5, 8},
                    {2, 5, 8},
                    {3, 6, 8}}

             W3 == {{2, 4, 7},
                    {2, 5, 8},
                    {3, 6, 8}}


             Unlike the result fron SUMS, VSUMS does promote series
             with a single row.

    Remarks:
             VSUMS requires at least one input argument.

             VSUMS always returns a series.

             Non-numeric arguments are ignored.

             Unlike SUMS, series with a single row are preserved.

             See VSUM to compute the scalar sum of the input values.

             See VAVGS to compute the point by pointmean of the input values.

    See Also:
             Avgs
             Mean
             Sums
             Vavgs
             Vmax
             Vmean
             Vmin
             Vsum
#endif


/* point by point sum of input args */
vsums(argv)
{
        local j, sum, nr, nc, ncc, s;

        if (argc < 1)
        {
                error("vsums - input value required");
        }

        /* max rows & cols */
        (nr, nc) = vsums_size(argv);

        sum = zeros(1, nc);

        /* get sum and lengths of inputs */
        loop (j = 1..argc)
        {
                if (isnumeric(getargv(j)))
                {
                        s = isarray(getargv(j)) ? refseries(getargv(j)) : castseries(getargv(j));

                        if (length(s) > 0)
                        {
                                if (numcols(s) < nc)
                                {
                                        /* add columns to conform */
                                        ncc  = nc - numcols(s);
                                        s    = ravel(s, zeros(1, ncc));
                                }

                                /* update sum */
                                sum = sums(sum, s);
                        }
                }
        }

        /* sum */
        return(sum);
}


/* find max numrows & numcols for inputs */
vsums_size(argv)
{
        local j, nr, nc, s;

        if (argc < 1)
        {
                error("vsums - input value required");
        }

        nr = nc = 0;

        /* get sum and lengths of inputs */
        loop (j = 1..argc)
        {
                if (isnumeric(getargv(j)))
                {
                        s = isarray(getargv(j)) ? refseries(getargv(j)) : castseries(getargv(j));

                        nr = max(nr, numrows(s));
                        nc = max(nc, numcols(s));
                }
        }

        return(nr, nc);
}