NAME
    appr - approximate numbers by multiples of a specified number

SYNOPSIS
    appr(x [,y [,z]])

TYPES
    x           real, complex, matrix, list
    y           real
    z           integer

    return      same type as x except that complex x may return a real number

DESCRIPTION
    Return the approximate value of x as specified by a specific error
    (epsilon) and config ("appr") value.

    The default value for y is epsilon().  The default value for z is
    the current value of the "appr" configuration parameter.

    If y is zero or x is a multiple of y, appr(x,y,z) returns x.  I.e.,
    there is no "approximation" - the result represents x exactly.

    In the following it is assumed y is nonzero and x is not a multiple of y.
    For real x:

        appr(x,y,z) is either the nearest multiple of y greater
        than x or the nearest multiple of y less than x.  Thus, if
        we write a = appr(x,y,z) and r = x - a, then a/y is an integer
        and abs(r) < abs(y).  If r > 0, we say x has been "rounded down"
        to a; if r < 0, the rounding is "up".  For particular x and y,
        whether the rounding is down or up is determined by z.

        Only the 5 lowest bits of z are used, so we may assume z has been
        replaced by its value modulo 32.  The type of rounding depends on
        z as follows:

        z = 0   round down or up according as y is positive or negative,
                sgn(r) = sgn(y)

        z = 1   round up or down according as y is positive or negative,
                sgn(r) = -sgn(y)

        z = 2   round towards zero, sgn(r) = sgn(x)

        z = 3   round away from zero, sgn(r) = -sgn(x)

        z = 4   round down, r > 0

        z = 5   round up, r < 0

        z = 6   round towards or from zero according as y is positive or
                negative, sgn(r) = sgn(x/y)

        z = 7   round from or towards zero according as y is positive or
                negative, sgn(r) = -sgn(x/y)

        z = 8   a/y is even

        z = 9   a/y is odd

        z = 10  a/y is even or odd according as x/y is positive or negative

        z = 11  a/y is odd or even according as x/y is positive or negative

        z = 12  a/y is even or odd according as y is positive or negative

        z = 13  a/y is odd or even according as y is positive or negative

        z = 14  a/y is even or odd according as x is positive or negative

        z = 15  a/y is odd or even according as x is positive or negative

        z = 16 to 31    abs(r) <= abs(y)/2; if there is a unique multiple
                of y that is nearest x, appr(x,y,z) is that multiple of y
                and then abs(r) < abs(y)/2.  If x is midway between
                successive multiples of y, then abs(r) = abs(y)/2 and
                the value of a is as given by appr(x, y, z-16).

    Matrix or List x:

        appr(x,y,z) returns the matrix or list indexed in the same way as x,
        in which each element t has been replaced by appr(t,y,z).

    Complex x:

        Returns  appr(re(x), y, z) + appr(im(x), y, z) * 1i

PROPERTIES
        If appr(x,y,z) != x, then abs(x - appr(x,y,z)) < abs(y).

        If appr(x,y,z) != x and 16 <= z <= 31, abs(x - appr(x,y,z)) <= abs(y)/2.

        For z = 0, 1, 4, 5, 16, 17, 20 or 21, and any integer n,
                appr(x + n*y, y, z) = appr(x, y, z) + n * y.

        If y is nonzero, appr(x,y,8)/y = an odd integer n only if x = n * y.

EXAMPLE
    ; print appr(-5.44,0.1,0), appr(5.44,0.1,0), appr(5.7,1,0), appr(-5.7,1,0)
    -5.5 5.4 5 -6

    ; print appr(-5.44,-.1,0), appr(5.44,-.1,0), appr(5.7,-1,0), appr(-5.7,-1,0)
    -5.4 5.5 6 -5

    ; print appr(-5.44,0.1,3), appr(5.44,0.1,3), appr(5.7,1,3), appr(-5.7,1,3)
    -5.5 5.5 6 -6

    ; print appr(-5.44,0.1,4), appr(5.44,0.1,4), appr(5.7,1,4), appr(-5.7,1,4)
    -5.5 5.4 5 -6

    ; print appr(-5.44,0.1,6), appr(5.44,0.1,6), appr(5.7,1,6), appr(-5.7,1,6)
    -5.4 5.4 6 -5

    ; print appr(-5.44,-.1,6), appr(5.44,-.1,6), appr(5.7,-1,6), appr(-5.7,-1,6)
    -5.5 5.5 6 -6

    ; print appr(-5.44,0.1,9), appr(5.44,0.1,9), appr(5.7,1,9), appr(-5.7,1,9)
    -5.5 5.5 5 -5

    ; print appr(-.44,0.1,11), appr(.44,0.1,11), appr(5.7,1,11), appr(-5.7,1,11)
    -0.4 0.5 5 -6

    ; print appr(-.44,-.1,11),appr(.44,-.1,11),appr(5.7,-1,11),appr(-5.7,-1,11)
    -0.5 0.4 6 -5

    ; print appr(-.44,0.1,12), appr(.44,0.1,12), appr(5.7,1,12), appr(-5.7,1,12)
    -0.4 0.5 5 -6

    ; print appr(-.44,-.1,12),appr(.44,-.1,12),appr(5.7,-1,12),appr(-5.7,-1,12)
    -0.5 0.4 6 -5

    ; print appr(-.44,0.1,15), appr(.44,0.1,15), appr(5.7,1,15), appr(-5.7,1,15)
    -0.4 0.5 5 -6

    ; print appr(-.44,-.1,15),appr(.44,-.1,15),appr(5.7,-1,15),appr(-5.7,-1,15)
    -0.4 0.5 5 -6

    ; x = sqrt(7-3i, 1e-20)
    ; print appr(x,1e-5,0), appr(x,1e-5,1), appr(x,1e-5,2), appr(x,1e-6,3)
    2.70331-0.55488i 2.70332-0.55487i 2.70331-0.55487i 2.70332-0.55488i

LIMITS
    none

LINK LIBRARY
    NUMBER *qmappr(NUMBER *q, NUMBER *e, long R);
    LIST *listappr(LIST *oldlp, VALUE *v2, VALUE *v3);
    MATRIX *matappr(MATRIX *m, VALUE *v2, VALUE *v3);

SEE ALSO
    round, bround, cfappr, cfsim

## 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/25 17:18:21
## 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/
