1% File src/library/base/man/sum.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2018 R Core Team
4% Distributed under GPL 2 or later
5
6\name{sum}
7\alias{sum}
8\title{Sum of Vector Elements}
9\description{
10  \code{sum} returns the sum of all the values
11  present in its arguments.
12}
13\usage{
14sum(\dots, na.rm = FALSE)
15}
16\arguments{
17  \item{\dots}{numeric or complex or logical vectors.}
18  \item{na.rm}{logical.  Should missing values (including \code{NaN}) be
19    removed?}
20}
21\value{
22  The sum.  If all of the \code{\dots} arguments are of type
23  integer or logical, then the sum is \code{\link{integer}} when
24  possible and is \code{double} otherwise.  Integer overflow should no
25  longer happen since \R version 3.5.0.
26  For other argument types it is a length-one numeric
27  (\code{\link{double}}) or complex vector.
28
29  \strong{NB:} the sum of an empty set is zero, by definition.
30}
31\details{
32  This is a generic function: methods can be defined for it
33  directly or via the \code{\link[=S3groupGeneric]{Summary}} group generic.
34  For this to work properly, the arguments \code{\dots} should be
35  unnamed, and dispatch is on the first argument.
36
37  If \code{na.rm} is \code{FALSE} an \code{NA} or \code{NaN} value in
38  any of the arguments will cause a value of \code{NA} or \code{NaN} to
39  be returned, otherwise \code{NA} and \code{NaN} values are ignored.
40
41  Logical true values are regarded as one, false values as zero.
42  For historical reasons, \code{NULL} is accepted and treated as if it
43  were \code{integer(0)}.
44
45  Loss of accuracy can occur when summing values of different signs:
46  this can even occur for sufficiently long integer inputs if the
47  partial sums would cause integer overflow.  Where possible
48  extended-precision accumulators are used, typically well supported
49  with C99 and newer, but possibly platform-dependent.
50}
51\section{S4 methods}{
52  This is part of the S4 \code{\link[=S4groupGeneric]{Summary}}
53  group generic.  Methods for it must use the signature
54  \code{x, \dots, na.rm}.
55
56  \sQuote{\link{plotmath}} for the use of \code{sum} in plot annotation.
57}
58\seealso{
59  \code{\link{colSums}} for row and column sums.
60}
61\references{
62  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
63  \emph{The New S Language}.
64  Wadsworth & Brooks/Cole.
65}
66\examples{% for beginners
67## Pass a vector to sum, and it will add the elements together.
68sum(1:5)
69
70## Pass several numbers to sum, and it also adds the elements.
71sum(1, 2, 3, 4, 5)
72
73## In fact, you can pass vectors into several arguments, and everything gets added.
74sum(1:2, 3:5)
75
76## If there are missing values, the sum is unknown, i.e., also missing, ....
77sum(1:5, NA)
78## ... unless  we exclude missing values explicitly:
79sum(1:5, NA, na.rm = TRUE)
80}
81\keyword{arith}
82