Arithmetic               package:base               R Documentation

Arithmetic Operators

Description:

     These binary operators perform arithmetic on numeric or complex
     vectors (or objects which can be coerced to them).

Usage:

     x + y
     x - y
     x * y
     x / y
     x ^ y
     x %% y
     x %/% y

Arguments:

    x, y: numeric or complex vectors or objects which can be coerced to
          such, or other objects for which methods have been written.

Details:

     The binary arithmetic operators are generic functions: methods can
     be written for them individually or via the 'Ops' group generic
     function.  (See 'Ops' for how dispatch is computed.)

     If applied to arrays the result will be an array if this is
     sensible (for example it will not if the recycling rule has been
     invoked).

     Logical vectors will be coerced to integer or numeric vectors,
     'FALSE' having value zero and 'TRUE' having value one.

     '1 ^ y' and 'y ^ 0' are '1', _always_. 'x ^ y' should also give
     the proper limit result when either argument is infinite (i.e.,
     '+- Inf').

     Objects such as arrays or time-series can be operated on this way
     provided they are conformable.

     For real arguments, '%%' can be subject to catastrophic loss of
     accuracy if 'x' is much larger than 'y', and a warning is given if
     this is detected.

Value:

     These operators return vectors containing the result of the
     element by element operations.  The elements of shorter vectors
     are recycled as necessary (with a 'warning' when they are recycled
     only _fractionally_).  The operators are '+' for addition, '-' for
     subtraction, '*' for multiplication, '/' for division and '^' for
     exponentiation.

     '%%' indicates 'x mod y' and '%/%' indicates integer division.  It
     is guaranteed that 'x == (x %% y) + y * ( x %/% y )' (up to
     rounding error) unless 'y == 0' where the result is 'NA_integer_'
     or 'NaN' (depending on the 'typeof' of the arguments).  See <URL:
     http://en.wikipedia.org/wiki/Modulo_operation> for the rationale.

     If either argument is complex the result will be complex, and if
     one or both arguments are numeric, the result will be numeric.  If
     both arguments are integer, the result of '/' and '^' is numeric
     and of the other operators integer (with overflow returned as 'NA'
     with a warning).

     The rules for determining the attributes of the result are rather
     complicated.  Most attributes are taken from the longer argument,
     the first if they are of the same length.  Names will be copied
     from the first if it is the same length as the answer, otherwise
     from the second if that is.  For time series, these operations are
     allowed only if the series are compatible, when the class and
     'tsp' attribute of whichever is a time series (the same, if both
     are) are used.  For arrays (and an array result) the dimensions
     and dimnames are taken from first argument if it is an array,
     otherwise the second.

S4 methods:

     These operators are members of the S4 'Arith' group generic, and
     so methods can be written for them individually as well as for the
     group generic (or the 'Ops' group generic), with arguments 'c(e1,
     e2)'.

Note:

     '**' is translated in the parser to '^', but this was undocumented
     for many years.  It appears as an index entry in Becker _et al_
     (1988), pointing to the help for 'Deprecated' but is not actually
     mentioned on that page.  Even though it has been deprecated in S
     for 20 years, it is still accepted.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'sqrt' for miscellaneous and 'Special' for special mathematical
     functions.

     'Syntax' for operator precedence.

     '%*%' for matrix multiplication.

Examples:

     x <- -1:12
     x + 1
     2 * x + 3
     x %% 2 #-- is periodic
     x %/% 5

