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