The R Project SVN R

Rev

Rev 77633 | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 77633 Rev 89122
Line 1... Line 1...
1 
% File src/library/base/man/sequence.Rd
 1 
% File src/library/base/man/sequence.Rd
2 
% Part of the R package, https://www.R-project.org
 2 
% Part of the R package, https://www.R-project.org
3 
% Copyright 1995-2007 R Core Team
 3 
% Copyright 1995-2025 R Core Team
4 
% Distributed under GPL 2 or later
 4 
% Distributed under GPL 2 or later
5 
 
 5 
 
6 
\name{sequence}
 6 
\name{sequence}
7 
\title{Create A Vector of Sequences}
 7 
\title{Create A Vector of Sequences}
8 
\usage{
 8 
\usage{
9 
sequence(nvec, \dots)
 9 
sequence(nvec, \dots)
10 
\method{sequence}{default}(nvec, from = 1L, by = 1L, \dots)
 10 
\method{sequence}{default}(nvec, from = 1L, by = 1L,
- 
 
 11 
    recycle = Sys.getenv("R_sequence_recycle", "false"), \dots)
11 
}
 12 
}
12 
\alias{sequence}
 13 
\alias{sequence}
13 
\alias{sequence.default}
 14 
\alias{sequence.default}
14 
\arguments{
 15 
\arguments{
15 
  \item{nvec}{coerced to a non-negative integer vector each element of which
 16 
  \item{nvec}{coerced to a non-negative integer vector each element of which
16 
    specifies the length of a sequence.}
 17 
    specifies the length of a sequence.}
17 
  \item{from}{coerced to an integer vector each element of which
 18 
  \item{from}{coerced to an integer vector each element of which
18 
    specifies the first element of a sequence.}
 19 
    specifies the first element of a sequence.}
19 
  \item{by}{coerced to an integer vector each element of which
 20 
  \item{by}{coerced to an integer vector each element of which
20 
    specifies the step size between elements of a sequence.}
 21 
    specifies the step size between elements of a sequence.}
- 
 
 22 
  \item{recycle}{\code{\link{logical}} or coercible to it, indicating if
- 
 
 23 
    \code{nvec} is recycled, as it has always been documented to.
- 
 
 24 
    We recommend to set this to \code{TRUE} explicitly, as that will become
- 
 
 25 
    default, see \sQuote{Details}.}% also \PR{18304} for background
21 
  \item{\dots}{additional arguments passed to methods.}
 26 
  \item{\dots}{additional arguments passed to methods.}
22 
}
 27 
}
23 
\description{
 28 
\description{
24 
  The default method for \code{sequence} generates the sequence
 29 
  The default method for \code{sequence} generates the sequence
25 
  \code{\link{seq}(from[i], by = by[i], length.out = nvec[i])} for each
 30 
  \code{\link{seq}(from[i], by = by[i], length.out = nvec[i])} for each
26 
  element \code{i} in the parallel (and recycled) vectors \code{from},
 31 
  element \code{i} in the parallel (and recycled) vectors \code{from},
- 
 
 32 
  \code{by} and \code{nvec}.
27 
  \code{by} and \code{nvec}. It then returns the result of concatenating
 33 
  Note that \code{nvec} is \emph{not} recycled unless \code{recycle}
28 
  those sequences.
 34 
  is true, see \sQuote{Details}.
- 
 
 35 
  It then returns the result of concatenating those sequences.
29 
}
 36 
}
30 
\details{
 37 
\details{
31 
  Negative values are supported for \code{from} and
 38 
  Negative values are supported for \code{from} and
32 
  \code{by}. \code{sequence(nvec, from, by=0L)} is equivalent to
 39 
  \code{by}. \code{sequence(nvec, from, by=0L)} is equivalent to
33 
  \code{rep(from, each=nvec)}.
 40 
  \code{rep(from, each=nvec)}.
34 
 
 41 
 
35 
  This function was originally implemented in R with fewer features, but
 42 
  This function was originally implemented in \R with fewer features, but
36 
  it has since become more flexible, and the default method is
 43 
  it has since become more flexible, and the default method is
37 
  implemented in C for speed.
 44 
  implemented in C for speed.
- 
 
 45 
 
- 
 
 46 
  Argument \code{recycle} is new since \R 4.6.0;
- 
 
 47 
  currently, the default is \code{FALSE} unless the environment variable
- 
 
 48 
  \env{R_sequence_recycle} is set to a true value.  \cr
- 
 
 49 
  This provides back compatibility with \R <= 4.5.z, where \code{from} and
- 
 
 50 
  \code{by} are recycled or shortened to length \code{length(nvec)} in case
- 
 
 51 
  that is shorter than the maximal length.  \cr
- 
 
 52 
  The plan is to replace the environment variable with an option
- 
 
 53 
  (\code{\link{getOption}}) defaulting to \code{TRUE} and later to
- 
 
 54 
  \code{TRUE} without a global option, to use \R's usual recycling semantic
- 
 
 55 
  for all three arguments \code{nvec, from, by}.
38 
}
 56 
}
39 
\seealso{
 57 
\seealso{
40 
  \code{\link{gl}}, \code{\link{seq}}, \code{\link{rep}}.
 58 
  \code{\link{gl}}, \code{\link{seq}}, \code{\link{rep}}.
41 
}
 59 
}
42 
\author{Of the current version, Michael Lawrence based on code from the
 60 
\author{Of the current version, Michael Lawrence based on code from the
43 
  S4Vectors Bioconductor package}
 61 
  \pkg{S4Vectors} Bioconductor package}
44 
\examples{
 62 
\examples{
45 
sequence(c(3, 2)) # the concatenated sequences 1:3 and 1:2.
 63 
sequence(c(3, 2)) # the concatenated sequences 1:3 and 1:2.
46 
#> [1] 1 2 3 1 2
 64 
#> [1] 1 2 3 ' 1 2  (using ' to visualize the sub-sequences)
47 
sequence(c(3, 2), from=2L)
 65 
sequence(c(3, 2), from=2L)         #> [1] 2 3 4 ' 2 3
48 
#> [1] 2 3 4 2 3
 66 
sequence(c(3, 2), from=2L, by=2L)  #> [1] 2 4 6 ' 2 4
49 
sequence(c(3, 2), from=2L, by=2L)
 67 
sequence(c(3, 2), by=c(-1L, 1L))   #> [1] 1 0 -1 ' 1 2
- 
 
 68 
 
50 
#> [1] 2 4 6 2 4
 69 
## Cases where  'recycle'  makes a difference:
- 
 
 70 
sequence(3, 1:3) #>  1 2 3  (_currently_ -- will change in future!)
51 
sequence(c(3, 2), by=c(-1L, 1L))
 71 
sequence(3, 1:3, recycle = FALSE)# back compatible: 1 2 3
- 
 
 72 
sequence(3, 1:3, recycle = TRUE) # future default -- use in new code!
- 
 
 73 
                                    # --> 1 2 3 ' 2 3 4 ' 3 4 5
- 
 
 74 
try(sequence(3, 1:3, 1[0], recycle = FALSE)) # an Error; default will be "empty":
52 
#> [1] 1 0 -1 1 2
 75 
    sequence(3, 1:3, 1[0], recycle = TRUE) # |--> integer(0)
53 
}
 76 
}
54 
\keyword{manip}
 77 
\keyword{manip}