List-class {IRanges} | R Documentation |
List objects are Vector objects with a "[["
,
elementType
and elementLengths
method.
The List class serves a similar role as list in base R.
It adds one slot, the elementType
slot, to the two slots shared by
all Vector objects.
The elementType
slot is the preferred location for List
subclasses to store the type of data represented in the sequence. It is
designed to take a character of length 1 representing the class of the
sequence elements. While the List class performs no validity checking
based on elementType
, if a subclass expects elements to be of a
given type, that subclass is expected to perform the necessary validity
checking. For example, the subclass IntegerList has
elementType = "integer"
and its validity method checks if this
condition is TRUE.
To be functional, a class that inherits from List must define at least
a "[["
method (in addition to the minimum set of Vector
methods).
List
objects are typically constructed by calling the
constructor of a concrete implementation, such as
RangesList
or IntegerList
. A
general and convenient way to convert any vector-like object into a
List
is to call as(x, "List")
. This will typically yield
an object from a subclass of CompressedList
.
In the following code snippets, x
is a List object.
elementType(x)
:
Get the scalar string naming the class from which all elements must
derive.
elementLengths(x)
:
Get the length (or nb of row for a matrix-like object) of each of
the elements. Equivalent to sapply(x, NROW)
.
isEmpty(x)
:
Returns a logical indicating either if the sequence has no elements
or if all its elements are empty.
In the code snippets below, x
is a List object.
x[[i]]
:
If defined, return the selected element i
, where i
is an
numeric or character vector of length 1.
x$name
:
Similar to x[[name]]
, but name
is taken literally as an
element name.
In the code snippets below, x
is a List object.
lapply(X, FUN, ...)
:
Like the standard lapply
function defined in the
base package, the lapply
method for List objects returns
a list of the same length as X
, with each element being the
result of applying FUN
to the corresponding element of X
.
sapply(X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)
:
Like the standard sapply
function defined in the
base package, the sapply
method for List objects is a
user-friendly version of lapply
by default returning a vector
or matrix if appropriate.
endoapply(X, FUN, ...)
:
Similar to lapply
, but performs an endomorphism,
i.e. returns an object of class(X)
.
mendoapply(FUN, ..., MoreArgs = NULL)
:
Similar to mapply
, but performs an endomorphism
across multiple objects, i.e. returns an object of
class(list(...)[[1]])
.
revElements(x, i)
:
A convenient way to do x[i] <- endoapply(x[i], rev)
.
There is a fast method for CompressedList objects,
otherwise expect it to be rather slow.
In the code snippets below, x
is a List object.
as.env(x, enclos = parent.frame())
:
Creates an environment from x
with a symbol for each
names(x)
. The values are not actually copied into the
environment. Rather, they are dynamically bound using
makeActiveBinding
. This prevents unnecessary copying
of the data from the external vectors into R vectors. The values
are cached, so that the data is not copied every time the symbol
is accessed.
as.list(x, ...)
, as(from, "list")
:
Turns x
into a standard list.
unlist(x, recursive = TRUE, use.names = TRUE)
: Concatenates
the elements of x
into a single elementType(x)
object.
stack(x, index.var = "name", value.var = "value")
:
As with stack
on a list
,
constructs a DataFrame
with two columns: one for the
unlisted values, the other indicating the name of the element from
which each value was obtained. index.var
specifies the column
name for the index (source name) column and value.var
specifies the column name for the values.
In the code snippets below, envir
and data
are List
objects.
eval(expr, envir, enclos = parent.frame())
:
Converts the List object specified in envir
to an
environment using as.env
, with enclos
as its parent,
and then evaluates expr
within that environment.
with(data, expr, ...)
:
Equivalent to eval(quote(expr), data, ...)
.
within(data, expr, ...)
:
Similar to with
, except assignments made during evaluation
are taken as assignments into data
, i.e., new symbols have
their value appended to data
, and assigning new values to
existing symbols results in replacement.
P. Aboyoun and H. Pages
Vector objects for the parent class.
The SimpleList and CompressedList classes for direct extensions of the List class.
The IRanges class and constructor for an example of a concrete List subclass.
extractList for grouping elements of a vector-like object into a list-like object.
funprog-methods for using functional programming methods on List objects.
showClass("List") # shows (some of) the known subclasses