1% File src/library/base/man/length.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2017 R Core Team
4% Distributed under GPL 2 or later
5
6\name{length}
7\alias{length}
8\alias{length<-}
9\alias{length<-.factor}
10\title{Length of an Object}
11\description{
12  Get or set the length of vectors (including lists) and factors, and of
13  any other \R object for which a method has been defined.
14}
15\usage{
16length(x)
17length(x) <- value
18}
19\arguments{
20  \item{x}{an \R object.  For replacement, a vector or factor.}
21  \item{value}{a non-negative integer or double (which will be rounded down).}
22}
23\details{
24  Both functions are generic: you can write methods to handle specific
25  classes of objects, see \link{InternalMethods}.  \code{length<-} has a
26  \code{"factor"} method.
27
28  The replacement form can be used to reset the length of a vector.  If
29  a vector is shortened, extra values are discarded and when a vector is
30  lengthened, it is padded out to its new length with \code{\link{NA}}s
31  (\code{nul} for raw vectors).
32
33  Both are \link{primitive} functions.
34}
35
36\value{
37  The default method for \code{length} currently returns a non-negative
38  \code{\link{integer}} of length 1, except for vectors of more than
39  \eqn{2^{31}-1}{2^31 - 1} elements, when it returns a double.
40
41  For vectors (including lists) and factors the length is the number of
42  elements.  For an environment it is the number of objects in the
43  environment, and \code{NULL} has length 0.  For expressions and
44  pairlists (including \link{language objects} and dotlists) it is the
45  length of the pairlist chain.  All other objects (including functions)
46  have length one: note that for functions this differs from S.
47
48  The replacement form removes all the attributes of \code{x} except its
49  names, which are adjusted (and if necessary extended by \code{""}).
50}
51
52\section{Warning}{
53  Package authors have written methods that return a result of length
54  other than one (\CRANpkg{Formula}) and that return a vector of type
55  \code{\link{double}} (\CRANpkg{Matrix}), even with non-integer values
56  (earlier versions of \CRANpkg{sets}).  Where a single double value is
57  returned that can be represented as an integer it is returned as a
58  length-one integer vector.
59}
60
61\seealso{\code{nchar} for counting the number of characters in character
62  vectors, \code{\link{lengths}} for getting the length of every element
63  in a list.
64}
65\references{
66  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
67  \emph{The New S Language}.
68  Wadsworth & Brooks/Cole.
69}
70\examples{
71length(diag(4))  # = 16 (4 x 4)
72length(options())  # 12 or more
73length(y ~ x1 + x2 + x3)  # 3
74length(expression(x, {y <- x^2; y+2}, x^y))  # 3
75
76## from example(warpbreaks)
77require(stats)
78
79fm1 <- lm(breaks ~ wool * tension, data = warpbreaks)
80length(fm1$call)      # 3, lm() and two arguments.
81length(formula(fm1))  # 3, ~ lhs rhs
82}
83\keyword{attribute}
84
85