NAME
    bround - round numbers to a specified number of binary digits

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

TYPES
    If x is a matrix or a list, bround(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_bround has
    to be defined; the types for x, plcs, rnd, and the returned value,
    if any, are as required for specified in tt_bround.  For the 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, bround(x, plcs, rnd) returns x rounded to either
    plcs significant binary digits (if rnd & 32 is nonzero) or to plcs
    binary places (if rnd & 32 is zero).  In the significant-figure
    case the rounding is to plcs - ilog10(x) - 1 binary places.
    If the number of binary 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 bround(x[[i]], plcs, rnd) in
        the same position as x[[i]] in x.

    For object x or plcs:

        When bround(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 broundvalue(VALUE *x, VALUE *plcs, VALUE *rnd, VALUE *result)
    MATRIX *matbround(MATRIX *m, VALUE *plcs, VALUE *rnd);
    LIST *listbround(LIST *m, VALUE *plcs, VALUE *rnd);
    NUMBER *qbround(NUMBER *m, long plcs, long rnd);

SEE ALSO
    round, trunc, btrunc, 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:22:35
## 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/
