TypedList-class {IRanges} | R Documentation

## Typed Lists

### Description

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.

### Details

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.

### Object Updating

  updateTypedObject(object): Updates instances of objects the inherit from an older TypedList class definition to match the current TypedList class definition.

### Subsetting

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.

### Accessors

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.

### Splitting and Combining

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.

### Coercion

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.

### Looping

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

### Author(s)

Michael Lawrence

### See Also

`ListLike`, `RangesList` for an example implementation

### Examples

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

[Package IRanges version 1.2.3 Index]