\HeaderA{Arithmetic}{Arithmetic Operators}{Arithmetic}
\aliasA{*}{Arithmetic}{*}
\aliasA{**}{Arithmetic}{**}
\aliasA{+}{Arithmetic}{+}
\aliasA{-}{Arithmetic}{.Rdash.}
\aliasA{/}{Arithmetic}{/}
\aliasA{\%/\%}{Arithmetic}{.Rpcent./.Rpcent.}
\aliasA{\%\%}{Arithmetic}{.Rpcent..Rpcent.}
\aliasA{\textasciicircum{}}{Arithmetic}{\textasciicircum.Rlbrace..Rrbrace.}
\keyword{arith}{Arithmetic}
\begin{Description}\relax
These binary operators perform arithmetic on numeric or complex vectors
(or objects which can be coerced to them).
\end{Description}
\begin{Usage}
\begin{verbatim}
x + y
x - y
x * y
x / y
x ^ y
x %% y
x %/% y
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y}] numeric or complex vectors or objects which can be
coerced to such, or other objects for which methods have been written.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The binary arithmetic operators are generic functions: methods can be
written for them individually or via the
\code{\LinkA{Ops}{Ops}} group generic function.  (See
\code{\LinkA{Ops}{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,
\code{FALSE} having value zero and \code{TRUE} having value one.

\code{1 \textasciicircum{} y} and \code{y \textasciicircum{} 0} are \code{1}, \emph{always}.
\code{x \textasciicircum{} y} should also give the proper limit result when
either argument is infinite (i.e., \code{+- \LinkA{Inf}{Inf}}).

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

For real arguments, \code{\%\%} can be subject to catastrophic loss of
accuracy if \code{x} is much larger than \code{y}, and a warning is
given if this is detected.
\end{Details}
\begin{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 \code{\LinkA{warning}{warning}} when they are recycled only
\emph{fractionally}).  The operators are \code{+} for addition,
\code{-} for subtraction, \code{*} for multiplication, \code{/} for
division and \code{\textasciicircum{}} for exponentiation.

\code{\%\%} indicates \code{x mod y} and \code{\%/\%} indicates
integer division.  It is guaranteed that \code{x == (x \%\% y) + y * ( x
    \%/\% y )} (up to rounding error) unless \code{y == 0} where the
result is \code{\LinkA{NA\_integer\_}{NA.Rul.integer.Rul.}} or \code{\LinkA{NaN}{NaN}} (depending on
the \code{\LinkA{typeof}{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 \code{/} and \code{\textasciicircum{}} is numeric
and of the other operators integer (with overflow returned as
\code{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 \code{\LinkA{tsp}{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.
\end{Value}
\begin{Section}{S4 methods}
These operators are members of the S4 \code{\LinkA{Arith}{Arith}} group generic,
and so methods can be written for them individually as well as for the
group generic (or the \code{Ops} group generic), with arguments
\code{c(e1, e2)}.
\end{Section}
\begin{Note}\relax
\code{**} is translated in the parser to \code{\textasciicircum{}}, but this was
undocumented for many years.  It appears as an index entry in Becker
\emph{et al} (1988), pointing to the help for \code{Deprecated} but
is not actually mentioned on that page.  Even though it has been
deprecated in S for 20 years, it is still accepted.
\end{Note}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{sqrt}{sqrt}} for miscellaneous and \code{\LinkA{Special}{Special}} for special
mathematical functions.

\code{\LinkA{Syntax}{Syntax}} for operator precedence.

\code{\LinkA{\%*\%}{.Rpcent.*.Rpcent.}} for matrix multiplication.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- -1:12
x + 1
2 * x + 3
x %% 2 #-- is periodic
x %/% 5
\end{ExampleCode}
\end{Examples}

