| % File src/library/base/man/lengths.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2015 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{lengths} |
| \alias{lengths} |
| \title{Lengths of List or Vector Elements} |
| \encoding{UTF-8} |
| \description{ |
| Get the length of each element of a \code{\link{list}} or atomic |
| vector (\code{\link{is.atomic}}) as an integer or numeric vector. |
| } |
| \usage{ |
| lengths(x, use.names = TRUE) |
| } |
| \arguments{ |
| \item{x}{a \code{\link{list}}, list-like such as an |
| \code{\link{expression}} or an atomic vector (for which the result |
| is trivial).} |
| \item{use.names}{logical indicating if the result should inherit the |
| \code{\link{names}} from \code{x}.} |
| } |
| \details{ |
| This function loops over \code{x} and returns a compatible vector |
| containing the length of each element in \code{x}. Effectively, |
| \code{length(x[[i]])} is called for all \code{i}, so any methods on |
| \code{length} are considered. |
| |
| \code{lengths} is generic: you can write methods to handle |
| specific classes of objects, see \link{InternalMethods}. |
| } |
| \note{ |
| One raison d'\enc{ĂȘtre}{etre} of \code{lengths(x)} is its use as a |
| more efficient version of \code{sapply(x, length)} and similar |
| \code{*apply} calls to \code{\link{length}}. This is the reason why |
| \code{x} may be an atomic vector, even though \code{lengths(x)} is |
| trivial in that case. |
| } |
| \value{ |
| A non-negative \code{\link{integer}} of length \code{length(x)}, |
| except when any element has a length of more than |
| \eqn{2^{31}-1}{2^31 - 1} elements, when it returns a double vector. |
| When \code{use.names} is true, the names are taken from the names on |
| \code{x}, if any. |
| } |
| \seealso{ |
| \code{\link{length}} for getting the length of any \R object. |
| } |
| \examples{ |
| require(stats) |
| ## summarize by month |
| l <- split(airquality$Ozone, airquality$Month) |
| avgOz <- lapply(l, mean, na.rm=TRUE) |
| ## merge result |
| airquality$avgOz <- rep(unlist(avgOz, use.names=FALSE), lengths(l)) |
| ## but this is safer and cleaner, but can be slower |
| airquality$avgOz <- unsplit(avgOz, airquality$Month) |
| |
| ## should always be true, except when a length does not fit in 32 bits |
| stopifnot(identical(lengths(l), vapply(l, length, integer(1L)))) |
| |
| ## empty lists are not a problem |
| x <- list() |
| stopifnot(identical(lengths(x), integer())) |
| |
| ## nor are "list-like" expressions: |
| lengths(expression(u, v, 1+ 0:9)) |
| |
| ## and we should dispatch to length methods |
| f <- c(rep(1, 3), rep(2, 6), 3) |
| dates <- split(as.POSIXlt(Sys.time() + 1:10), f) |
| stopifnot(identical(lengths(dates), vapply(dates, length, integer(1L)))) |
| } |
| \keyword{attribute} |