| 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 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.
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)