TypedList-class {IRanges} | R Documentation |
The virtual class TypedList
is an emulation of an ordinary
list
, except all of the elements must derive from a particular
type. This is useful for validity checking and for implementing
vectorized type-specific operations.
In general, a TypedList
may be treated as any ordinary
list
, except with regard to the element type restriction.
The required element type is indicated by the elementClass
slot, a scalar string naming the class from which all elements must
derive. This slot should never be set after initialization.
TypedList
is a virtual class, so a subclass must be derived for
a particular element type. This turns out to be useful in almost all
cases, as the explicit class can be used as the type of a slot in a
class that requires a homogeneous list of elements. Also, methods may
be implemented for the subclass that, for example, perform a vectorized
operation specific to the element type. Using this approach, the
convention is for the prototype of the subclass to set the
elementClass
slot and to leave it unchanged.
In the following code snippets, x
is a TypedList
object.
x[i]
: Get a subset of x
containing the
elements indexed by
i
, which may be numeric, character, logical, NULL
or
missing. The behavior is very similar to an ordinary list
,
except operations that would insert NULL
elements are only
allowed if NULL
is a valid element type.x[[i]]
: Get the element in x
indexed by
i
, which may be a scalar number or string. The behavior is
nearly identical to that of an ordinary list
.
x[[i]] <- value
: Replace the element at index
i
(a scalar number or string) with value
. The behavior is
very similar to that of an ordinary list
, except
value
must be coercible (and is coerced) to the required
element class.
In the following code snippets, x
is a TypedList
object.
length(x)
: Get the number of elements in x
names(x)
, names(x) <- value
: Get or set the
names of the elements in the list. This behaves exactly the same as
an ordinary list
.
elementClass(x)
: Get the scalar string naming the
class from which all elements must derive.
elements(x)
: Returns the internal list
holding
the elements. It is not recommended to access the elements this
way, as for some subclasses of TypedList
this may be an
internal representation that is not consistent with what is
extracted with, for example, the [[
method.
The following are methods for
combining TypedList
elements. In the signatures, x
is a
TypedList
object.
append(x, values, after = length(x))
: Insert the
TypedList
values
onto x
at the position given
by after
. values
must have an elementClass
that extends that of x
.
c(x, ..., recursive = FALSE)
: Appends the
TypedList
instances in ...
onto the end of
x
. All arguments must have an element class that extends that
of x
.
Note that the default split
method happens
to work on TypedList
objects.
In the following code snippets, x
is a TypedList
object.
as.list(x)
, as(from, "list")
: Coerces a
TypedList
to an ordinary list
. Note that this is
preferred over the elements
accessor for getting a list
of the elements.
unlist(x)
: Combines all of the elements in this list
into a single element via the c
function and returns the
result. Will not work if the elements have no method for
c
. Returns NULL
if there are no elements in x
,
which may not be what is expected in many cases.
Subclasses should implement their own logic.
lapply(X, FUN, ...)
: Applies the function
FUN
over the TypedList
X
, with arguments in
...
passed on to FUN
. Returns a list
, with
each element resulting from invoking FUN
on the corresponding
element of X
. Same semantics as the default lapply
.
Michael Lawrence
RangesList
for an example implementation
## demonstrated on RangesList, as TypedList is virtual range1 <- IRanges(start=c(1,2,3), end=c(5,2,8)) range2 <- IRanges(start=c(15,45,20,1), end=c(15,100,80,5)) collection <- RangesList(range1, range2) ## names names(collection) <- c("one", "two") names(collection) names(collection) <- NULL # clear names names(collection) names(collection) <- "one" names(collection) # c("one", NA) ## extraction collection[[1]] # range1 collection[["1"]] # NULL, does not exist collection[["one"]] # range1 collection[[NA_integer_]] # NULL ## subsetting collection[numeric()] # empty collection[NULL] # empty collection[] # identity collection[c(TRUE, FALSE)] # first element collection[2] # second element collection[c(2,1)] # reversed collection[-1] # drop first ## combining col1 <- RangesList(one = range1, range2) col2 <- RangesList(two = range2, one = range1) col3 <- RangesList(range2) append(col1, col2, 1) append(col1, col2, -5) c(col1, col2, col3) ## get the starts of each Ranges lapply(col1, start)