c_cpp/etc/calc/help/bround

   1 NAME
   2     bround - round numbers to a specified number of binary digits
   3
   4 SYNOPSIS
   5     bround(x [,plcs [, rnd]])
   6
   7 TYPES
   8     If x is a matrix or a list, bround(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_bround has
  14     to be defined; the types for x, plcs, rnd, and the returned value,
  15     if any, are as required for specified in tt_bround.  For the object
  16     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, bround(x, plcs, rnd) returns x rounded to either
  28     plcs significant binary digits (if rnd & 32 is nonzero) or to plcs
  29     binary places (if rnd & 32 is zero).  In the significant-figure
  30     case the rounding is to plcs - ilog10(x) - 1 binary places.
  31     If the number of binary 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 bround(x[[i]], plcs, rnd) in
  60         the same position as x[[i]] in x.
  61
  62     For object x or plcs:
  63
  64         When bround(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 broundvalue(VALUE *x, VALUE *plcs, VALUE *rnd, VALUE *result)
 118     MATRIX *matbround(MATRIX *m, VALUE *plcs, VALUE *rnd);
 119     LIST *listbround(LIST *m, VALUE *plcs, VALUE *rnd);
 120     NUMBER *qbround(NUMBER *m, long plcs, long rnd);
 121
 122 SEE ALSO
 123     round, trunc, btrunc, int, appr
 124
 125 ## Copyright (C) 1999  Landon Curt Noll
 126 ##
 127 ## Calc is open software; you can redistribute it and/or modify it under
 128 ## the terms of the version 2.1 of the GNU Lesser General Public License
 129 ## as published by the Free Software Foundation.
 130 ##
 131 ## Calc is distributed in the hope that it will be useful, but WITHOUT
 132 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 133 ## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
 134 ## Public License for more details.
 135 ##
 136 ## A copy of version 2.1 of the GNU Lesser General Public License is
 137 ## distributed with calc under the filename COPYING-LGPL.  You should have
 138 ## received a copy with calc; if not, write to Free Software Foundation, Inc.
 139 ## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 140 ##
 141 ## @(#) $Revision: 30.1 $
 142 ## @(#) $Id: bround,v 30.1 2007/03/16 11:10:42 chongo Exp $
 143 ## @(#) $Source: /usr/local/src/cmd/calc/help/RCS/bround,v $
 144 ##
 145 ## Under source code control:   1994/09/30 00:22:35
 146 ## File existed as early as:    1994
 147 ##
 148 ## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
 149 ## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/