\HeaderA{injectHardMask}{Injecting a hard mask in a sequence}{injectHardMask}
\aliasA{injectHardMask,MaskedXString-method}{injectHardMask}{injectHardMask,MaskedXString.Rdash.method}
\aliasA{injectHardMask,XStringViews-method}{injectHardMask}{injectHardMask,XStringViews.Rdash.method}
\keyword{utilities}{injectHardMask}
\keyword{manip}{injectHardMask}
\begin{Description}\relax
\code{injectHardMask} allows the user to "fill" the masked regions
of a sequence with an arbitrary letter (typically the \code{"+"}
letter).
\end{Description}
\begin{Usage}
\begin{verbatim}
  injectHardMask(x, letter="+")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A \LinkA{MaskedXString}{MaskedXString} or \LinkA{XStringViews}{XStringViews} object.

\item[\code{letter}] A single letter.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The name of the \code{injectHardMask} function was chosen because of the
primary use that it is intended for: converting a pile of active "soft
masks" into a "hard mask".
Here the pile of active "soft masks" refers to the active masks that have
been put on top of a sequence. In Biostrings, the original sequence and the
masks defined on top of it are bundled together in one of the dedicated
containers for this: the \LinkA{MaskedBString}{MaskedBString}, \LinkA{MaskedDNAString}{MaskedDNAString},
\LinkA{MaskedRNAString}{MaskedRNAString} and \LinkA{MaskedAAString}{MaskedAAString} containers (this is the
\LinkA{MaskedXString}{MaskedXString} family of containers).
The original sequence is always stored unmodified in a \LinkA{MaskedXString}{MaskedXString}
object so no information is lost. This allows the user to activate/deactivate
masks without having to worry about losing the letters that are in the
regions that are masked/unmasked. Also this allows better memory
management since the original sequence never needs to be copied, even when
the set of active/inactive masks changes.

However, there are situations where the user might want to \emph{really}
get rid of the letters that are in some particular regions by replacing
them with a junk letter (e.g. \code{"+"}) that is guaranteed to not interfer
with the analysis that s/he is currently doing.
For example, it's very likely that a set of motifs or short reads will not
contain the \code{"+"} letter (this could easily be checked) so they will
never hit the regions filled with \code{"+"}.
In a way, it's like the regions filled with \code{"+"} were masked but we
call this kind of masking "hard masking".

Some important differences between "soft" and "hard" masking:
\describe{
\item[] \code{injectHardMask} creates a (modified) copy of the original
sequence. Using "soft masking" does not.

\item[] A function that is "mask aware" like \code{alphabetFrequency} or
\code{matchPattern} will really skip the masked regions
when "soft masking" is used i.e. they will not walk thru the
regions that are under active masks. This might lead to some
speed improvements when a high percentage of the original sequence
is masked.
With "hard masking", the entire sequence is walked thru.

\item[] Matches cannot span over masked regions with "soft masking".
With "hard masking" they can.

}
\end{Details}
\begin{Value}
An \LinkA{XString}{XString} object of the same length as the orignal object \code{x}
if \code{x} is a \LinkA{MaskedXString}{MaskedXString} object, or of the same length
as \code{subject(x)} if it's an \LinkA{XStringViews}{XStringViews} object.
\end{Value}
\begin{Author}\relax
H. Pages
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{maskMotif}{maskMotif}},
\LinkA{MaskedXString-class}{MaskedXString.Rdash.class},
\code{\LinkA{replaceLetterAt}{replaceLetterAt}},
\code{\LinkA{chartr}{chartr}},
\LinkA{XString}{XString},
\LinkA{XStringViews-class}{XStringViews.Rdash.class}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  ## ---------------------------------------------------------------------
  ## A. WITH AN XStringViews OBJECT
  ## ---------------------------------------------------------------------
  v2 <- Views("abCDefgHIJK", start=c(8, 3), end=c(14, 4))
  injectHardMask(v2)
  injectHardMask(v2, letter="=")

  ## ---------------------------------------------------------------------
  ## B. WITH A MaskedXString OBJECT
  ## ---------------------------------------------------------------------
  mask0 <- Mask(mask.width=29, start=c(3, 10, 25), width=c(6, 8, 5))
  x <- DNAString("ACACAACTAGATAGNACTNNGAGAGACGC")
  masks(x) <- mask0
  x
  subject <- injectHardMask(x)

  ## Matches can span over masked regions with "hard masking":
  matchPattern("ACggggggA", subject, max.mismatch=6)
  ## but not with "soft masking":
  matchPattern("ACggggggA", x, max.mismatch=6)
\end{ExampleCode}
\end{Examples}

