The R Project SVN R

% File src/library/base/man/sequence.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2025 R Core Team
% Distributed under GPL 2 or later

\name{sequence}
\title{Create A Vector of Sequences}
\usage{
sequence(nvec, \dots)
\method{sequence}{default}(nvec, from = 1L, by = 1L,
    recycle = Sys.getenv("R_sequence_recycle", "false"), \dots)
}
\alias{sequence}
\alias{sequence.default}
\arguments{
  \item{nvec}{coerced to a non-negative integer vector each element of which
    specifies the length of a sequence.}
  \item{from}{coerced to an integer vector each element of which
    specifies the first element of a sequence.}
  \item{by}{coerced to an integer vector each element of which
    specifies the step size between elements of a sequence.}
  \item{recycle}{\code{\link{logical}} or coercible to it, indicating if
    \code{nvec} is recycled, as it has always been documented to.
    We recommend to set this to \code{TRUE} explicitly, as that will become
    default, see \sQuote{Details}.}% also \PR{18304} for background
  \item{\dots}{additional arguments passed to methods.}
}
\description{
  The default method for \code{sequence} generates the sequence
  \code{\link{seq}(from[i], by = by[i], length.out = nvec[i])} for each
  element \code{i} in the parallel (and recycled) vectors \code{from},
  \code{by} and \code{nvec}.
  Note that \code{nvec} is \emph{not} recycled unless \code{recycle}
  is true, see \sQuote{Details}.
  It then returns the result of concatenating those sequences.
}
\details{
  Negative values are supported for \code{from} and
  \code{by}. \code{sequence(nvec, from, by=0L)} is equivalent to
  \code{rep(from, each=nvec)}.

  This function was originally implemented in \R with fewer features, but
  it has since become more flexible, and the default method is
  implemented in C for speed.

  Argument \code{recycle} is new since \R 4.6.0;
  currently, the default is \code{FALSE} unless the environment variable
  \env{R_sequence_recycle} is set to a true value.  \cr
  This provides back compatibility with \R <= 4.5.z, where \code{from} and
  \code{by} are recycled or shortened to length \code{length(nvec)} in case
  that is shorter than the maximal length.  \cr
  The plan is to replace the environment variable with an option
  (\code{\link{getOption}}) defaulting to \code{TRUE} and later to
  \code{TRUE} without a global option, to use \R's usual recycling semantic
  for all three arguments \code{nvec, from, by}.
}
\seealso{
  \code{\link{gl}}, \code{\link{seq}}, \code{\link{rep}}.
}
\author{Of the current version, Michael Lawrence based on code from the
  \pkg{S4Vectors} Bioconductor package}
\examples{
sequence(c(3, 2)) # the concatenated sequences 1:3 and 1:2.
#> [1] 1 2 3 ' 1 2  (using ' to visualize the sub-sequences)
sequence(c(3, 2), from=2L)         #> [1] 2 3 4 ' 2 3
sequence(c(3, 2), from=2L, by=2L)  #> [1] 2 4 6 ' 2 4
sequence(c(3, 2), by=c(-1L, 1L))   #> [1] 1 0 -1 ' 1 2

## Cases where  'recycle'  makes a difference:
sequence(3, 1:3) #>  1 2 3  (_currently_ -- will change in future!)
sequence(3, 1:3, recycle = FALSE)# back compatible: 1 2 3
sequence(3, 1:3, recycle = TRUE) # future default -- use in new code!
                                    # --> 1 2 3 ' 2 3 4 ' 3 4 5
try(sequence(3, 1:3, 1[0], recycle = FALSE)) # an Error; default will be "empty":
    sequence(3, 1:3, 1[0], recycle = TRUE) # |--> integer(0)
}
\keyword{manip}