NAME
    round - round numbers to a specified number of decimal places

SYNOPSIS
    round(x [,plcs [, rnd]])

TYPES
    If x is a matrix or a list, round(x[[i]], ...) is to return
    a value for each element x[[i]] of x; the value returned will be
    a matrix or list with the same structure as x.

    Otherwise, if x is an object of type tt, or if x is not an object or
    number but y is an object of type tt, and the function tt_round has
    to be defined; the types for x, plcs, rnd, and the returned value, if
    any, are as required or specified in the definition of tt_round.
    In this object case, plcs and rnd default to the null value.

    For other cases:

    x		number (real or complex)
    plcs	integer, defaults to zero
    rnd		integer, defaults to config("round")

    return	number

DESCRIPTION
    For real x, round(x, plcs, rnd) returns x rounded to either
    plcs significant figures (if rnd & 32 is nonzero) or to plcs
    decimal places (if rnd & 32 is zero).  In the significant-figure
    case the rounding is to plcs - ilog10(x) - 1 decimal places.
    If the number of decimal places is n and eps = 10^-n, the
    result is the same as for appr(x, eps, rnd).  This will be
    exactly x if x is a multiple of eps; otherwise rounding occurs
    to one of the nearest multiples of eps on either side of x.	 Which
    of these multiples is returned is determined by z = rnd & 31, i.e.
    the five low order bits of rnd, as follows:

	    z = 0 or 4:		round down, i.e. towards minus infinity
	    z = 1 or 5:		round up, i.e. towards plus infinity
	    z = 2 or 6:		round towards zero
	    z = 3 or 7:		round away from zero
	    z = 8 or 12:	round to the nearest even multiple of eps
	    z = 9 or 13:	round to the nearest odd multiple of eps
	    z = 10 or 14:	round to nearest even or odd multiple of eps
				    according as x > or < 0
	    z = 11 or 15:	round to nearest odd or even multiple of eps
				    according as x > or < 0
	    z = 16 to 31:	round to the nearest multiple of eps when
				    this is uniquely determined.  Otherwise
				    rounding is as if z is replaced by z - 16

    For complex x:

	The real and imaginary parts are rounded as for real x; if the
	imaginary part rounds to zero, the result is real.

    For matrix or list x:

	The returned values has element round(x[[i]], plcs, rnd) in
	the same position as x[[i]] in x.

    For object x or plcs:

	When round(x, plcs, rnd) is called, x is passed by address so may be
	changed by assignments; plcs and rnd are copied to temporary
	variables, so their values are not changed by the call.

EXAMPLE
    ; a = 7/32, b = -7/32

    ; print a, b
    0.21875 -0.21875

    ; print round(a,3,0), round(a,3,1), round(a,3,2), print round(a,3,3)
    0.218, 0.219, 0.218, 0.219

    ; print round(b,3,0), round(b,3,1), round(b,3,2), print round(b,3,3)
    -0.219, -0.218, -0.218, -0.219

    ; print round(a,3,16), round(a,3,17), round(a,3,18), print round(a,3,19)
    0.2188 0.2188 0.2188 0.2188

    ; print round(a,4,16), round(a,4,17), round(a,4,18), print round(a,4,19)
    0.2187 0.2188 0.2187 0.2188

    ; print round(a,2,8), round(a,3,8), round(a,4,8), round(a,5,8)
    0.22 0.218 0.2188 0.21875

    ; print round(a,2,24), round(a,3,24), round(a,4,24), round(a,5,24)
    0.22 0.219 0.2188 0.21875

    ; c = 21875
    ; print round(c,-2,0), round(c,-2,1), round(c,-3,0), round(c,-3,16)
    21800 21900 21000 22000

    ; print round(c,2,32), round(c,2,33), round(c,2,56), round(c,4,56)
    21000 22000 22000 21880

    ; A = list(1/8, 2/8, 3/8, 4/8, 5/8, 6/8, 7/8)
    ; print round(A,2,24)

    list(7 elements, 7 nonzero):
	[[0]] = 0.12
	[[1]] = 0.25
	[[3]] = 0.38
	[[4]] = 0.5
	[[5]] = 0.62
	[[6]] = 0.75
	[[7]] = 0.88

LIMITS
    For non-object case:
	0 <= abs(plcs) < 2^31
	0 <= abs(rnd) < 2^31

LINK LIBRARY
    void roundvalue(VALUE *x, VALUE *plcs, VALUE *rnd, VALUE *result)
    MATRIX *matround(MATRIX *m, VALUE *plcs, VALUE *rnd);
    LIST *listround(LIST *m, VALUE *plcs, VALUE *rnd);
    NUMBER *qround(NUMBER *m, long plcs, long rnd);

SEE ALSO
    bround, btrunc, trunc, int, appr

## Copyright (C) 1999,2021  Landon Curt Noll
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
## or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU Lesser General
## Public License for more details.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## Under source code control:	1994/09/30 00:52:38
## File existed as early as:	1994
##
## chongo <was here> /\oo/\	http://www.isthe.com/chongo/
## Share and enjoy!  :-)	http://www.isthe.com/chongo/tech/comp/calc/