/*****************************************************************************
*                                                                            *
*   RAND.SPL      Copyright (C) 2000-2006 DSP Development Corporation        *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:       Randy Race                                                 *
*                                                                            *
*   Synopsis:     Generates a uniformly distributed random array             *
*                                                                            *
*   Revisions:     7 Feb 2000  RRR  Creation                                 *
*                 10 Aug 2001  RRR  single column check                      *
*                 14 Feb 2006  RRR  use builtin grandarray for speed         *
*                                                                            *
*****************************************************************************/


#if @HELP_RAND

    RAND

    Purpose: Generates a uniformly distributed random array

    Syntax:  RAND(numrows, numcols)

               numrows - An integer, number of output rows

               numcols - An optional integer, number of output columns,
                         defaults to numrows

             RAND with no input arguments returns a scalar

    Returns: A scalar, series or array

    Example:
             rand(20, 5)

             Generates a 20 row by 5 column array of uniformly
             distributed random numbers with values between 0.0 and
             1.0.

    Example:
             rand(20)

             Generates a 20 x 20 random array

    Example:
             rand

             Returns a random real value between 0.0 and 1.0.

    Remarks:
             RAND uses GRAND to generate the random values. The SEEDRAND
             function determines the initial seed of the random number
             generator.

    See Also:
             Gnormal
             Grand
             Randn
             Seedrand

#endif


/* generate matrix of uniformly distributed random values */
SERIES rand(n, m)
{
        local r, nr, nc;

        if (argc < 2)
        {
                if (argc < 1)
                {
                        return(castreal(grand(1, 1)));
                }
                
                m = n;
        }

        if (isarray(n))
        {
                /* series argument - get size */
                (nr, nc) = size(n);
                
                if (nr == 2 && nc == 1)
                {
                        /*
                         *  assume series came from size function,
                         *  e.g. rand(size(n))
                         */
                        
                        m = int(n[2]);
                        n = int(n[1]);
                }
                else
                {
                        /* e.g. rand(x) - obsolete */
                        n = nr;
                        m = nc;
                }
        }
        else
        {
                m = castint(m);
                n = castint(n);
        }

        if (m <= 0 || n <= 0)
        {
                /* empty series */
                return({});
        }

        if (m == 1)
        {
                /* no need for array */
                r = grand(n, 1);
        }
        else
        {
                r = grandarray(n, m);
        }

        return(r);
}