help/appr

   1 NAME
   2     appr - approximate numbers by multiples of a specified number
   3
   4 SYNOPSIS
   5     appr(x [,y [,z]])
   6
   7 TYPES
   8     x           real, complex, matrix, list
   9     y           real
  10     z           integer
  11
  12     return      same type as x except that complex x may return a real number
  13
  14 DESCRIPTION
  15     Return the approximate value of x as specified by a specific error
  16     (epsilon) and config ("appr") value.
  17
  18     The default value for y is epsilon().  The default value for z is
  19     the current value of the "appr" configuration parameter.
  20
  21     If y is zero or x is a multiple of y, appr(x,y,z) returns x.  I.e.,
  22     there is no "approximation" - the result represents x exactly.
  23
  24     In the following it is assumed y is nonzero and x is not a multiple of y.
  25     For real x:
  26
  27         appr(x,y,z) is either the nearest multiple of y greater
  28         than x or the nearest multiple of y less than x.  Thus, if
  29         we write a = appr(x,y,z) and r = x - a, then a/y is an integer
  30         and abs(r) < abs(y).  If r > 0, we say x has been "rounded down"
  31         to a; if r < 0, the rounding is "up".  For particular x and y,
  32         whether the rounding is down or up is determined by z.
  33
  34         Only the 5 lowest bits of z are used, so we may assume z has been
  35         replaced by its value modulo 32.  The type of rounding depends on
  36         z as follows:
  37
  38         z = 0   round down or up according as y is positive or negative,
  39                 sgn(r) = sgn(y)
  40
  41         z = 1   round up or down according as y is positive or negative,
  42                 sgn(r) = -sgn(y)
  43
  44         z = 2   round towards zero, sgn(r) = sgn(x)
  45
  46         z = 3   round away from zero, sgn(r) = -sgn(x)
  47
  48         z = 4   round down, r > 0
  49
  50         z = 5   round up, r < 0
  51
  52         z = 6   round towards or from zero according as y is positive or
  53                 negative, sgn(r) = sgn(x/y)
  54
  55         z = 7   round from or towards zero according as y is positive or
  56                 negative, sgn(r) = -sgn(x/y)
  57
  58         z = 8   a/y is even
  59
  60         z = 9   a/y is odd
  61
  62         z = 10  a/y is even or odd according as x/y is positive or negative
  63
  64         z = 11  a/y is odd or even according as x/y is positive or negative
  65
  66         z = 12  a/y is even or odd according as y is positive or negative
  67
  68         z = 13  a/y is odd or even according as y is positive or negative
  69
  70         z = 14  a/y is even or odd according as x is positive or negative
  71
  72         z = 15  a/y is odd or even according as x is positive or negative
  73
  74         z = 16 to 31    abs(r) <= abs(y)/2; if there is a unique multiple
  75                 of y that is nearest x, appr(x,y,z) is that multiple of y
  76                 and then abs(r) < abs(y)/2.  If x is midway between
  77                 successive multiples of y, then abs(r) = abs(y)/2 and
  78                 the value of a is as given by appr(x, y, z-16).
  79
  80     Matrix or List x:
  81
  82         appr(x,y,z) returns the matrix or list indexed in the same way as x,
  83         in which each element t has been replaced by appr(t,y,z).
  84
  85     Complex x:
  86
  87         Returns  appr(re(x), y, z) + appr(im(x), y, z) * 1i
  88
  89 PROPERTIES
  90         If appr(x,y,z) != x, then abs(x - appr(x,y,z)) < abs(y).
  91
  92         If appr(x,y,z) != x and 16 <= z <= 31, abs(x - appr(x,y,z)) <= abs(y)/2.
  93
  94         For z = 0, 1, 4, 5, 16, 17, 20 or 21, and any integer n,
  95                 appr(x + n*y, y, z) = appr(x, y, z) + n * y.
  96
  97         If y is nonzero, appr(x,y,8)/y = an odd integer n only if x = n * y.
  98
  99 EXAMPLES
 100     > print appr(-5.44,0.1,0), appr(5.44,0.1,0), appr(5.7,1,0), appr(-5.7,1,0)
 101     -5.5 5.4 5 -6
 102
 103     > print appr(-5.44,-.1,0), appr(5.44,-.1,0), appr(5.7,-1,0), appr(-5.7,-1,0)
 104     -5.4 5.5 6 -5
 105
 106     > print appr(-5.44,0.1,3), appr(5.44,0.1,3), appr(5.7,1,3), appr(-5.7,1,3)
 107     -5.5 5.5 6 -6
 108
 109     > print appr(-5.44,0.1,4), appr(5.44,0.1,4), appr(5.7,1,4), appr(-5.7,1,4)
 110     -5.5 5.4 5 -6
 111
 112     > print appr(-5.44,0.1,6), appr(5.44,0.1,6), appr(5.7,1,6), appr(-5.7,1,6)
 113     -5.4 5.4 6 -5
 114
 115     > print appr(-5.44,-.1,6), appr(5.44,-.1,6), appr(5.7,-1,6), appr(-5.7,-1,6)
 116     -5.5 5.5 6 -6
 117
 118     > print appr(-5.44,0.1,9), appr(5.44,0.1,9), appr(5.7,1,9), appr(-5.7,1,9)
 119     -5.5 5.5 5 -5
 120
 121     > print appr(-.44,0.1,11), appr(.44,0.1,11), appr(5.7,1,11), appr(-5.7,1,11)
 122     -.4 .5 5 -6
 123
 124     > print appr(-.44,-.1,11),appr(.44,-.1,11),appr(5.7,-1,11),appr(-5.7,-1,11)
 125     -.5 .4 6 -5
 126
 127     > print appr(-.44,0.1,12), appr(.44,0.1,12), appr(5.7,1,12), appr(-5.7,1,12)
 128     -.4 .5 5 -6
 129
 130     > print appr(-.44,-.1,12),appr(.44,-.1,12),appr(5.7,-1,12),appr(-5.7,-1,12)
 131     -.5 .4 6 -5
 132
 133     > print appr(-.44,0.1,15), appr(.44,0.1,15), appr(5.7,1,15), appr(-5.7,1,15)
 134     -.4 .5 5 -6
 135
 136     > print appr(-.44,-.1,15),appr(.44,-.1,15),appr(5.7,-1,15),appr(-5.7,-1,15)
 137     -.4 .5 5 -6
 138
 139     > x = sqrt(7-3i, 1e-20)
 140     > print appr(x,1e-5,0), appr(x,1e-5,1), appr(x,1e-5,2), appr(x,1e-6,3)
 141     2.70331-.55488i 2.70332-.55487i 2.70331-.55487i 2.70332-.55488i
 142
 143 LIMITS
 144     none
 145
 146 LINK LIBRARY
 147     NUMBER *qmappr(NUMBER *q, NUMBER *e, long R);
 148     LIST *listappr(LIST *oldlp, VALUE *v2, VALUE *v3);
 149     MATRIX *matappr(MATRIX *m, VALUE *v2, VALUE *v3);
 150
 151 SEE ALSO
 152     round, bround, cfappr, cfsim
 153