BString-class           package:Biostrings           R Documentation

_T_h_e _B_S_t_r_i_n_g _c_l_a_s_s

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

     The 'BString' class is a general container for storing a big
     string (a long sequence of characters) and to make its
     manipulation easy and efficient. The 'DNAString', 'RNAString' and
     'AAString' classes are direct 'BString' derivations with the more
     specific purpose of storing a DNA sequence ('DNAString'), a RNA
     sequence ('RNAString') or a sequence of amino acids ('AAString').

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

     The 2 main differences between a 'BString' object and a standard
     character vector are: (1) the data stored in a 'BString' object
     are not copied on object duplication and (2) a 'BString' can only
     store a single string (see the 'BStringViews' for an efficient way
     to store a collection of big strings in a single object). A
     'BString' object can be used to store any non-empty string based
     on a single-byte character set.

_C_o_n_s_t_r_u_c_t_o_r-_l_i_k_e _f_u_n_c_t_i_o_n_s _a_n_d _g_e_n_e_r_i_c_s:

     In the code snippet below, 'src' can be a character vector or a
     'BString' (or derived) object.

      'BString(src)': Tries to convert 'src' into a 'BString' object.
          'src' can be a single string (character vector of length 1),
          a DNAString object, an RNAString object or an AAString
          object.

_S_t_a_n_d_a_r_d _g_e_n_e_r_i_c _m_e_t_h_o_d_s:

     In the code snippets below, 'x', 'object', 'e1' and 'e2' are
     BString (or derived) objects, and 'i' is a NA-free numeric vector.

      'length(x)' or 'nchar(x)': Get the length of a BString object,
          i.e., its number of letters.

      'x[i]': Return a new BString (or derived) object made of the
          selected letters. The returned object belongs to the same
          class as 'x'.

      'e1 == e2': 'TRUE' if 'e1' is equal to 'e2'. 'FALSE' otherwise.

          Comparison between two BString objects of different classes
          (e.g. a BString instance and a DNAString instance) is not
          supported with one exception: a DNAString instance and a
          RNAString instance can be compared (see RNAString-class for
          more details about this).

          Comparison between a BString instance and a character string
          is also supported (see examples below).

      'e1 != e2': Equivalent to '!(e1 == e2)'.

      'as.character(x)': Converts 'x' to a character string.

      'toString(x)': Equivalent to 'as.character(x)'.

_O_t_h_e_r _f_u_n_c_t_i_o_n_s _a_n_d _g_e_n_e_r_i_c_s:

     In the code snippet below, 'x' is a 'BString' (or derived) object.

      'alphabet(x)': 'NULL' for a 'BString' object. See the
          corresponding man pages when 'x' is of class 'DNAString',
          'RNAString' or code{AAString}.

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

     'subBString', 'letter', DNAString-class, RNAString-class,
     AAString-class, BStringViews-class

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

       b <- BString("I am a BString object")
       b
       length(b)
       b2 <- b[length(b):1]
       as.character(b2)

       ## b[1:length(b)] is equal but not identical to b!
       b == b[1:length(b)]        # TRUE
       identical(b, 1:length(b))  # FALSE
       ## This is because subsetting a BString object with [ makes a copy
       ## of part or all its sequence data. Hence, for the resulting object,
       ## the internal slot containing the memory address of the sequence
       ## data differs from the original. This is enough for identical() to
       ## see the 2 objects as different. See ?subBString for a much more
       ## efficient substring extraction (does NOT copy the sequence data of
       ## the original object).

       b2 == b                    # FALSE
       b2 == as.character(b2)     # TRUE

