help/mod

   1 NAME
   2     mod - compute the remainder for an integer quotient
   3
   4 SYNOPSIS
   5     mod(x, y, rnd)
   6     x % y
   7
   8 TYPES
   9     If x is a matrix or list, the returned value is a matrix or list v of
  10     the same structure for which each element v[[i]] = mod(x[[i]], y, rnd).
  11
  12     If x is an xx-object or x is not an object and y is an xx-object,
  13     this function calls the user-defined function xx_mod(x, y, rnd);
  14     the types of arguments and returned value are as required by the
  15     definition of xx_mod().
  16
  17     If neither x nor y is an object, or x is not a matrix or list:
  18
  19     x           number (real or complex)
  20     y           real
  21     rnd         integer, defaults to config("mod")
  22
  23     return      number
  24
  25 DESCRIPTION
  26     If x is real or complex and y is zero, mod(x, y, rnd) returns x.
  27
  28     If x is complex, mod(x, y, rnd) returns
  29                 mod(re(x), y, rnd) + mod(im(x), y, rnd) * 1i.
  30
  31     In the following it is assumed x is real and y is nonzero.
  32
  33     If x/y is an integer mod(x, y, rnd) returns zero.
  34
  35     If x/y is not an integer, mod(x, y, rnd) returns one of the two numbers
  36     r for which for some integer q, x = q * v + r and abs(r) < abs(y).
  37     Which of the two numbers is returned is controlled by rnd.
  38
  39     If bit 4 of rnd is set (e.g. if 16 <= rnd < 32) abs(r) <= abs(y)/2;
  40     this uniquely determines r if abs(r) < abs(y)/2.  If bit 4 of rnd is
  41     set and abs(r) = abs(y)/2, or if bit 4 of r is not set, the result for
  42     r depends on rnd as in the following table:
  43
  44         (Blank entries indicate that the description would be complicated
  45          and probably not of much interest.)
  46
  47              rnd & 15      sign of r            parity of q
  48
  49                 0            sgn(y)
  50                 1           -sgn(y)
  51                 2            sgn(x)
  52                 3           -sgn(x)
  53                 4             +
  54                 5             -
  55                 6            sgn(x/y)
  56                 7           -sgn(x/y)
  57                 8                                  even
  58                 9                                  odd
  59                10                               even if x/y > 0, otherwise odd
  60                11                               odd if x/y > 0, otherwise even
  61                12                               even if y > 0, otherwise odd
  62                13                               odd if y > 0, otherwise even
  63                14                               even if x > 0, otherwise odd
  64                15                               odd if x > 0, otherwise even
  65
  66         This dependence on rnd is consistent with quo(x, y, rnd) and
  67         appr(x, y, rnd) in that for any real x and y and any integer rnd,
  68
  69                 x = y * quo(x, y, rnd) + mod(x, y, rnd).
  70                 mod(x, y, rnd) = x - appr(x, y, rnd)
  71
  72         If y and rnd are fixed and mod(x, y, rnd) is to be considered as
  73         a canonical residue of x modulo y, bits 1 and 3 of rnd should be
  74         zero: if 0 <= rnd < 32, it is only for rnd = 0, 1, 4, 5, 16, 17,
  75         20, or 21, that the set of possible values for mod(x, y, rnd)
  76         form an interval of length y, and for any x1, x2,
  77
  78                 mod(x1, y, rnd) = mod(x2, y, rnd)
  79
  80         is equivalent to:
  81
  82                 x1 is congruent to x2 modulo y.
  83
  84         This is particularly relevant when working with the ring of
  85         integers modulo an integer y.
  86
  87 EXAMPLE
  88     > print mod(11,5,0), mod(11,5,1), mod(-11,5,2), mod(-11,-5,3)
  89     1 -4 -1 4
  90
  91     > print mod(12.5,5,16), mod(12.5,5,17), mod(12.5,5,24), mod(-7.5,-5,24)
  92     2.5 -2.5 2.5 2.5
  93
  94     > A = list(11,13,17,23,29)
  95     > print mod(A,10,0)
  96
  97     list (5 elements, 5 nonzero):
  98         [[0]] = 1
  99         [[1]] = 3
 100         [[2]] = 7
 101         [[3]] = 3
 102         [[4]] = 9
 103
 104 LIMITS
 105     none
 106
 107 LINK LIBRARY
 108     void modvalue(VALUE *x, VALUE *y, VALUE *rnd, VALUE *result)
 109     NUMBER *qmod(NUMBER *y, NUMBER *y, long rnd)
 110
 111 SEE ALSO
 112     quo, quomod, //, %
 113