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$name
: similar to above, where name
is taken
literally as an element name.
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.
x$name <- value
: similar to above, where name
is taken
literally as an element name.
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.
elementLengths(x)
: Get the 'length' of each of the
elements.
isEmpty(x)
: Gets a logical vector indicating
which elements are empty.
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
objects 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, ...)
:
Like the standard lapply
function defined in the
base package, the lapply
method for TypedLike objects returns
a list of the same length as X
, each element of which is 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 TypedList objects is a
user-friendly version of lapply
by default returning a vector
or matrix if appropriate.
Michael Lawrence
ListLike
,
RangesList
for an example implementation
## demonstrated on IntegerList objects, as TypedList is virtual int1 <- c(1L,2L,3L,5L,2L,8L) int2 <- c(15L,45L,20L,1L,15L,100L,80L,5L) collection <- IntegerList(int1, int2) ## 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 collection$one ## replacement collection$one <- int2 collection[[2]] <- int1 ## combining col1 <- IntegerList(one = int1, int2) col2 <- IntegerList(two = int2, one = int1) col3 <- IntegerList(int2) append(col1, col2) append(col1, col2, 0) c(col1, col2, col3) ## get the mean for each element lapply(col1, mean)