help/round

   1 NAME
   2     round - round numbers to a specified number of decimal places
   3
   4 SYNOPSIS
   5     round(x [,plcs [, rnd]])
   6
   7 TYPES
   8     If x is a matrix or a list, round(x[[i]], ...) is to return
   9     a value for each element x[[i]] of x; the value returned will be
  10     a matrix or list with the same structure as x.
  11
  12     Otherwise, if x is an object of type tt, or if x is not an object or
  13     number but y is an object of type tt, and the function tt_round has
  14     to be defined; the types for x, plcs, rnd, and the returned value, if
  15     any, are as required or specified in the definition of tt_round.
  16     In this object case, plcs and rnd default to the null value.
  17
  18     For other cases:
  19
  20     x           number (real or complex)
  21     plcs        integer, defaults to zero
  22     rnd         integer, defaults to config("round")
  23
  24     return      number
  25
  26 DESCRIPTION
  27     For real x, round(x, plcs, rnd) returns x rounded to either
  28     plcs significant figures (if rnd & 32 is nonzero) or to plcs
  29     decimal places (if rnd & 32 is zero).  In the significant-figure
  30     case the rounding is to plcs - ilog10(x) - 1 decimal places.
  31     If the number of decimal places is n and eps = 10^-n, the
  32     result is the same as for appr(x, eps, rnd).  This will be
  33     exactly x if x is a multiple of eps; otherwise rounding occurs
  34     to one of the nearest multiples of eps on either side of x.  Which
  35     of these multiples is returned is determined by z = rnd & 31, i.e.
  36     the five low order bits of rnd, as follows:
  37
  38             z = 0 or 4:         round down, i.e. towards minus infinity
  39             z = 1 or 5:         round up, i.e. towards plus infinity
  40             z = 2 or 6:         round towards zero
  41             z = 3 or 7:         round away from zero
  42             z = 8 or 12:        round to the nearest even multiple of eps
  43             z = 9 or 13:        round to the nearest odd multiple of eps
  44             z = 10 or 14:       round to nearest even or odd multiple of eps
  45                                     according as x > or < 0
  46             z = 11 or 15:       round to nearest odd or even multiple of eps
  47                                     according as x > or < 0
  48             z = 16 to 31:       round to the nearest multiple of eps when
  49                                     this is uniquely determined.  Otherwise
  50                                     rounding is as if z is replaced by z - 16
  51
  52     For complex x:
  53
  54         The real and imaginary parts are rounded as for real x; if the
  55         imaginary part rounds to zero, the result is real.
  56
  57     For matrix or list x:
  58
  59         The returned values has element round(x[[i]], plcs, rnd) in
  60         the same position as x[[i]] in x.
  61
  62     For object x or plcs:
  63
  64         When round(x, plcs, rnd) is called, x is passed by address so may be
  65         changed by assignments; plcs and rnd are copied to temporary
  66         variables, so their values are not changed by the call.
  67
  68 EXAMPLES
  69     > a = 7/32, b = -7/32
  70
  71     > print a, b
  72     .21875 -.21875
  73
  74     > print round(a,3,0), round(a,3,1), round(a,3,2), print round(a,3,3)
  75     .218, .219, .218, .219
  76
  77     > print round(b,3,0), round(b,3,1), round(b,3,2), print round(b,3,3)
  78     -.219, -.218, -.218, -.219
  79
  80     > print round(a,3,16), round(a,3,17), round(a,3,18), print round(a,3,19)
  81     .2188 .2188 .2188 .2188
  82
  83     > print round(a,4,16), round(a,4,17), round(a,4,18), print round(a,4,19)
  84     .2187 .2188 .2187 .2188
  85
  86     > print round(a,2,8), round(a,3,8), round(a,4,8), round(a,5,8)
  87     .22 .218 .2188 .21875
  88
  89     > print round(a,2,24), round(a,3,24), round(a,4,24), round(a,5,24)
  90     .22 .219 .2188 .21875
  91
  92     > c = 21875
  93     > print round(c,-2,0), round(c,-2,1), round(c,-3,0), round(c,-3,16)
  94     21800 21900 21000 22000
  95
  96     > print round(c,2,32), round(c,2,33), round(c,2,56), round(c,4,56)
  97     21000 22000 22000 21880
  98
  99     > A = list(1/8, 2/8, 3/8, 4/8, 5/8, 6/8, 7/8)
 100     > print round(A,2,24)
 101
 102     list(7 elements, 7 nonzero):
 103         [[0]] = .12
 104         [[1]] = .25
 105         [[3]] = .38
 106         [[4]] = .5
 107         [[5]] = .62
 108         [[6]] = .75
 109         [[7]] = .88
 110
 111 LIMITS
 112     For non-object case:
 113         0 <= abs(plcs) < 2^31
 114         0 <= abs(rnd) < 2^31
 115
 116 LINK LIBRARY
 117     void roundvalue(VALUE *x, VALUE *plcs, VALUE *rnd, VALUE *result)
 118     MATRIX *matround(MATRIX *m, VALUE *plcs, VALUE *rnd);
 119     LIST *listround(LIST *m, VALUE *plcs, VALUE *rnd);
 120     NUMBER *qround(NUMBER *m, long plcs, long rnd);
 121
 122 SEE ALSO
 123     bround, btrunc, trunc, int, appr
 124