/*****************************************************************************
*                                                                            *
*   ISUNIFORM.SP Copyright (C) 2026 DSP Development Corporation              *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Returns 1 if values are uniformly spaced                    *
*                                                                            *
*   Revisions:    4 May 2026  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_ISUNIFORM

    ISUNIFORM

    Purpose: Returns 1 if the input values are uniformly spaced.

    Syntax:  ISUNIFORM(series, tol)

             (tf, stepsize) = ISUNIFORM(series, tol)

              ser - A real series, the input values to check.

              tol - Optional. A real the tolerance value. Defaults to
                    4 * eps(max(abs(series)))
                    
    Returns: An integer, 1 if the elements of the series are uniformly
             spaced up to round-off tolerance and 0 otherwise. If the
             input is a multi-column series, 0 or 1 is returned for
             each column.

             (tf, stepsize) = ISUNIFORM(series) also returns STEPSIZE,
             the constant step size. If SERIES is uniformly spaced,
             STEPSIZE is a scalar equal to the common step size. If
             SERIES is not uniformly spaced. STEPSIZE is NaN.

    Example:
             a = {1, 2, 3, 4};
             b = {1, 1.5, 2, 3};
             c = {10};
             d = {10, 10};

             isuniform(a) == 1
             isuniform(b) == 0
             isuniform(c) == 0
             isuniform(d) == 1

             If the input is a real-valued series containing at least
             two elements and each successive value increases by the
             same constant amount (including zero), the series is considered
             uniform.

     Example:
             v = 0..0.5..10;
             (tf, stepsize) = isuniform(v);

             tf == 1
             stepsize == 0.5

             Series V is uniform with a step size of 0.5.

     Example:
             v = 10..-0.5..0;
             (tf, stepsize) = isuniform(v);

             tf == 1
             stepsize == -0.5

             Series V is uniform with a step size of -0.5.

     Example:
             v = {1, 2, 4, 5};
             (tf, stepsize) = isuniform(v);

             tf == 0
             stepsize == nan

             Series V is not uniform.
             
     Example:
             a = linspace(0, 1, 100);
             b = a;
             b[end] = 5 * eps(max(abs(a)));
             
             isuniform(a) == 1;
             isuniform(b) == 0;

             The pertubation of series B is exceeds the 4*eps
             default tolerance.

     Example:
             a = {1, nan, 2};
             b = {1, 2, inf};
             c = {nan, nan};
             d = {inf, inf}
             
             isuniform(a) == 0;
             isuniform(b) == 0;
             isuniform(c) == 0;
             isuniform(d) == 0;

             Any input series with nan or inf is not considered uniform.

     Example:
             a = 10;
             b = "10";
             c = {1 + 2i, 2 + 3i};
             d = {10};

             isuniform(a) == 0;
             isuniform(b) == 0;
             isuniform(c) == 0;
             isuniform(d) == 0;

             The input is not considered uniform if it is not a real
             series with at least two values.

    Remarks:
             ISUNIFORM returns 1 when the values SERIES change by a
             constant step size.

             If the input series is not unform, the returned value is 0
             and the returned STEPSIZE is NaN.

             ISUNIFORM returns 0 if the input is not a real series or
             length(SERIES) < 2.

             A real series with length >= 2 and all equal values is
             considered uniform with a step size of 0.

    See Also:
             Finite
             Isempty
             Isinf
#endif


/* do values increase or decrease by uniform constant? */             
ITERATE isuniform(series, tol = nan)
{
        local tf = logical(0), stepsize = nan;

        if (argc < 1) error(sprintf("%s - input value required", __FUNC__));

        if (isarray(series))
        {
                /* use internal function */
                (tf, stepsize) = uniformspacing(series, tol);
        }

        return(tf, stepsize);
}