/*****************************************************************************
*                                                                            *
*   ROUNDN.SPL  Copyright (C) 2023 DSP Development Corporation               *
*                               All Rights Reserved                          *
*                                                                            *
*   Author:      Randy Race                                                  *
*                                                                            *
*   Synopsis:    Round values to n digits                                    *
*                                                                            *
*   Revisions:   18 Jul 2023  RRR  Creation                                  *
*                                                                            *
*****************************************************************************/


#if @HELP_ROUNDN

    ROUNDN

    Purpose: Round a scalar or series to N digits.

    Syntax:  ROUNDN(s, n, "option")

               s - A series or scalar value.

               n - An integer, the number of decimal places to round.
                   If negative, specifies the number of digits to the
                   left of the decimal place. Defaults to 0.

              "option" - Optional. A string, the digit option.

                          "decimals"    : round to N decimal places (default)

                          "significant" : round to N significant figures.

    Returns: A scalar or series, the rounded values.

    Example:
             W1: {6.718, 13.382, 0.556, -1.123}
             W2: round(w1)
             W3: roundn(w1, 0)
             W4: roundn(w1, 1)

             W2 == {7, 13, 1, -1}
             W3 == {7, 13, 1, -1}
             W4 == {6.7, 13.4, 0.6, -1.1}


             Both W2 and W2 round the values to no decimal places.

             W4 rounds the values to 1 decimal place.

   Example:
             W1: {671.8, 1338.2, 55.6, -112.3}
             W2: roundn(w1, -1)
             W3: roundn(w1, -2)
             W4: roundn(w1, -3)

             W2 == {670,  1340,  60,  -110}
             W3 == {700,  1300, 100,  -100}
             W4 == {1000, 1000,   0,     0}

             W2 rounds the values left one place.

             W3 rounds the values left two places.

             W4 rounds the values left three places.

   Example:
             W1: {671.8, 1338.2, 55.6, -112.3}
             W2: roundn(w1, 1, "significant")
             W3: roundn(w1, 2, "significant")
             W4: roundn(w1, 3, "significant")

             W2 == {700, 1000,  60,   -100}
             W3 == {670, 1300,  56,   -110}
             W4 == {672, 1340,  56.6, -112}

             W2 rounds the values to one significant digit.

             W3 rounds the values to two significant digits.

             W4 rounds the values to three significant digits.
    
    Remarks:
             ROUNDN rounds values to N decimal places.

             If OPTION is "significant", the values are rounded to N
             significant figures.

    See Also:
             Fix
             Round
#endif


/* builtin */