| 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 xnames(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)