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.

_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[[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. 

_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.

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


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

_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.


_A_p_p_l_y_i_n_g:


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


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

     Michael Lawrence

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

     'RangesList' for an example implementation

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

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

