TypedList-class           package:IRanges           R Documentation

_T_y_p_e_d _L_i_s_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_D_e_t_a_i_l_s:

     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.

_O_b_j_e_c_t _U_p_d_a_t_i_n_g:


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

_S_u_b_s_e_t_t_i_n_g:

     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.


_A_c_c_e_s_s_o_r_s:

     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.


_S_p_l_i_t_t_i_n_g _a_n_d _C_o_m_b_i_n_i_n_g:

     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.

_C_o_e_r_c_i_o_n:

     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.


_L_o_o_p_i_n_g:


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


_A_u_t_h_o_r(_s):

     Michael Lawrence

_S_e_e _A_l_s_o:

     'ListLike', 'RangesList' for an example implementation

_E_x_a_m_p_l_e_s:

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

