\HeaderA{XString-class}{BString objects}{XString.Rdash.class}
\aliasA{"!=,BString,character-method}{XString-class}{"!=,BString,character.Rdash.method}
\aliasA{"!=,character,BString-method}{XString-class}{"!=,character,BString.Rdash.method}
\aliasA{"!=,XString,XString-method}{XString-class}{"!=,XString,XString.Rdash.method}
\aliasA{==,BString,character-method}{XString-class}{==,BString,character.Rdash.method}
\aliasA{==,character,BString-method}{XString-class}{==,character,BString.Rdash.method}
\aliasA{==,XString,XString-method}{XString-class}{==,XString,XString.Rdash.method}
\aliasA{alphabet}{XString-class}{alphabet}
\aliasA{alphabet,ANY-method}{XString-class}{alphabet,ANY.Rdash.method}
\aliasA{as.character,XString-method}{XString-class}{as.character,XString.Rdash.method}
\aliasA{BString}{XString-class}{BString}
\aliasA{BString-class}{XString-class}{BString.Rdash.class}
\aliasA{class:BString}{XString-class}{class:BString}
\aliasA{class:XString}{XString-class}{class:XString}
\aliasA{coerce,character,AAString-method}{XString-class}{coerce,character,AAString.Rdash.method}
\aliasA{coerce,character,BString-method}{XString-class}{coerce,character,BString.Rdash.method}
\aliasA{coerce,character,DNAString-method}{XString-class}{coerce,character,DNAString.Rdash.method}
\aliasA{coerce,character,RNAString-method}{XString-class}{coerce,character,RNAString.Rdash.method}
\aliasA{coerce,character,XString-method}{XString-class}{coerce,character,XString.Rdash.method}
\aliasA{coerce,XString,AAString-method}{XString-class}{coerce,XString,AAString.Rdash.method}
\aliasA{coerce,XString,BString-method}{XString-class}{coerce,XString,BString.Rdash.method}
\aliasA{coerce,XString,DNAString-method}{XString-class}{coerce,XString,DNAString.Rdash.method}
\aliasA{coerce,XString,RNAString-method}{XString-class}{coerce,XString,RNAString.Rdash.method}
\aliasA{nchar,XString-method}{XString-class}{nchar,XString.Rdash.method}
\aliasA{show,XString-method}{XString-class}{show,XString.Rdash.method}
\aliasA{toString,XString-method}{XString-class}{toString,XString.Rdash.method}
\aliasA{updateObject,XString-method}{XString-class}{updateObject,XString.Rdash.method}
\aliasA{xsbasetype,AAString-method}{XString-class}{xsbasetype,AAString.Rdash.method}
\aliasA{xsbasetype,BString-method}{XString-class}{xsbasetype,BString.Rdash.method}
\aliasA{xsbasetype,DNAString-method}{XString-class}{xsbasetype,DNAString.Rdash.method}
\aliasA{xsbasetype,RNAString-method}{XString-class}{xsbasetype,RNAString.Rdash.method}
\aliasA{xsbasetype<-,XString-method}{XString-class}{xsbasetype<.Rdash.,XString.Rdash.method}
\aliasA{XString}{XString-class}{XString}
\keyword{methods}{XString-class}
\keyword{classes}{XString-class}
\begin{Description}\relax
The BString class is a general container for storing
a big string (a long sequence of characters) and for making its
manipulation easy and efficient.

The \LinkA{DNAString}{DNAString}, \LinkA{RNAString}{RNAString} and \LinkA{AAString}{AAString} classes are
similar containers but with the more biology-oriented purpose of storing
a DNA sequence (\LinkA{DNAString}{DNAString}), an RNA sequence (\LinkA{RNAString}{RNAString}),
or a sequence of amino acids (\LinkA{AAString}{AAString}).

All those containers derive directly (and with no additional slots)
from the XString virtual class.
\end{Description}
\begin{Details}\relax
The 2 main differences between an XString object and a standard character
vector are: (1) the data stored in an XString object are not copied on
object duplication and (2) an XString object can only store
a single string (see the \LinkA{XStringSet}{XStringSet} container for an
efficient way to store a big collection of strings in a single object).

Unlike the \LinkA{DNAString}{DNAString}, \LinkA{RNAString}{RNAString} and \LinkA{AAString}{AAString}
containers that accept only a predefined set of letters (the alphabet),
a BString object can be used for storing any single string based on a
single-byte character set.
\end{Details}
\begin{Section}{Constructor-like functions and generics}
In the code snippet below,
\code{x} can be a single string (character vector of length 1)
or an XString object.

\describe{
\item[] \code{BString(x="", start=1, nchar=NA)}:
Tries to convert \code{x} into a BString object by reading
\code{nchar} letters starting at position \code{start} in \code{x}.

}
\end{Section}
\begin{Section}{Accessor methods}
In the code snippets below, \code{x} is an XString object.

\describe{
\item[] \code{alphabet(x)}:
\code{NULL} for a \code{BString} object.
See the corresponding man pages when \code{x} is a 
\LinkA{DNAString}{DNAString}, \LinkA{RNAString}{RNAString} or \LinkA{AAString}{AAString} object.

\item[] \code{length(x)} or \code{nchar(x)}:
Get the length of an XString object, i.e., its number of letters.

}
\end{Section}
\begin{Section}{Coercion}
In the code snippets below, \code{x} is an XString object.

\describe{
\item[] \code{as.character(x)}:
Converts \code{x} to a character string.

\item[] \code{toString(x)}:
Equivalent to \code{as.character(x)}.

}
\end{Section}
\begin{Section}{Subsetting}
In the code snippets below, \code{x} is an XString object.

\describe{
\item[] \code{x[i]}:
Return a new XString object made of the selected letters (subscript
\code{i} must be an NA-free numeric vector specifying the positions of
the letters to select).
The returned object belongs to the same class as \code{x}.

Note that, unlike \code{subseq}, \code{x[i]} does copy the sequence
data and therefore will be very inefficient for extracting a big number
of letters (e.g. when \code{i} contains millions of positions).

}
\end{Section}
\begin{Section}{Equality}
In the code snippets below, \code{e1} and \code{e2} are XString objects.

\describe{
\item[] \code{e1 == e2}:
\code{TRUE} if \code{e1} is equal to \code{e2}.
\code{FALSE} otherwise.

Comparison between two XString objects of different base types (e.g.
a BString object and a \LinkA{DNAString}{DNAString} object) is not supported
with one exception: a \LinkA{DNAString}{DNAString} object and an \LinkA{RNAString}{RNAString}
object can be compared (see \LinkA{RNAString-class}{RNAString.Rdash.class} for more details
about this).

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

\item[] \code{e1 != e2}:
Equivalent to \code{!(e1 == e2)}.

}
\end{Section}
\begin{Author}\relax
H. Pages
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{subseq}{subseq}},
\code{\LinkA{letter}{letter}},
\LinkA{DNAString-class}{DNAString.Rdash.class},
\LinkA{RNAString-class}{RNAString.Rdash.class},
\LinkA{AAString-class}{AAString.Rdash.class},
\LinkA{XStringSet-class}{XStringSet.Rdash.class},
\LinkA{XStringViews-class}{XStringViews.Rdash.class},
\code{\LinkA{reverse,XString-method}{reverse,XString.Rdash.method}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  b <- BString("I am a BString object")
  b
  length(b)

  ## Extracting a linear subsequence 
  subseq(b)
  subseq(b, start=3)
  subseq(b, start=-3)
  subseq(b, end=-3)
  subseq(b, end=-3, width=5)

  ## Subsetting
  b2 <- b[length(b):1]       # better done with reverse(b)

  as.character(b2)

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

  ## 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 an XString 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.
\end{ExampleCode}
\end{Examples}

