\HeaderA{findPalindromes}{Searching a sequence for palindromes or complemented palindromes}{findPalindromes}
\aliasA{complementedPalindromeArmLength}{findPalindromes}{complementedPalindromeArmLength}
\aliasA{complementedPalindromeArmLength,DNAString-method}{findPalindromes}{complementedPalindromeArmLength,DNAString.Rdash.method}
\aliasA{complementedPalindromeArmLength,XStringViews-method}{findPalindromes}{complementedPalindromeArmLength,XStringViews.Rdash.method}
\aliasA{complementedPalindromeLeftArm}{findPalindromes}{complementedPalindromeLeftArm}
\aliasA{complementedPalindromeLeftArm,DNAString-method}{findPalindromes}{complementedPalindromeLeftArm,DNAString.Rdash.method}
\aliasA{complementedPalindromeLeftArm,XStringViews-method}{findPalindromes}{complementedPalindromeLeftArm,XStringViews.Rdash.method}
\aliasA{complementedPalindromeRightArm}{findPalindromes}{complementedPalindromeRightArm}
\aliasA{complementedPalindromeRightArm,DNAString-method}{findPalindromes}{complementedPalindromeRightArm,DNAString.Rdash.method}
\aliasA{complementedPalindromeRightArm,XStringViews-method}{findPalindromes}{complementedPalindromeRightArm,XStringViews.Rdash.method}
\aliasA{findComplementedPalindromes}{findPalindromes}{findComplementedPalindromes}
\aliasA{findComplementedPalindromes,DNAString-method}{findPalindromes}{findComplementedPalindromes,DNAString.Rdash.method}
\aliasA{findComplementedPalindromes,MaskedXString-method}{findPalindromes}{findComplementedPalindromes,MaskedXString.Rdash.method}
\aliasA{findComplementedPalindromes,XStringViews-method}{findPalindromes}{findComplementedPalindromes,XStringViews.Rdash.method}
\aliasA{findPalindromes,MaskedXString-method}{findPalindromes}{findPalindromes,MaskedXString.Rdash.method}
\aliasA{findPalindromes,XString-method}{findPalindromes}{findPalindromes,XString.Rdash.method}
\aliasA{findPalindromes,XStringViews-method}{findPalindromes}{findPalindromes,XStringViews.Rdash.method}
\aliasA{palindromeArmLength}{findPalindromes}{palindromeArmLength}
\aliasA{palindromeArmLength,XString-method}{findPalindromes}{palindromeArmLength,XString.Rdash.method}
\aliasA{palindromeArmLength,XStringViews-method}{findPalindromes}{palindromeArmLength,XStringViews.Rdash.method}
\aliasA{palindromeLeftArm}{findPalindromes}{palindromeLeftArm}
\aliasA{palindromeLeftArm,XString-method}{findPalindromes}{palindromeLeftArm,XString.Rdash.method}
\aliasA{palindromeLeftArm,XStringViews-method}{findPalindromes}{palindromeLeftArm,XStringViews.Rdash.method}
\aliasA{palindromeRightArm}{findPalindromes}{palindromeRightArm}
\aliasA{palindromeRightArm,XString-method}{findPalindromes}{palindromeRightArm,XString.Rdash.method}
\aliasA{palindromeRightArm,XStringViews-method}{findPalindromes}{palindromeRightArm,XStringViews.Rdash.method}
\keyword{methods}{findPalindromes}
\begin{Description}\relax
The \code{findPalindromes} and \code{findComplementedPalindromes}
functions can be used to find palindromic or complemented palindromic
regions in a sequence.

\code{palindromeArmLength}, \code{palindromeLeftArm},
\code{palindromeRightArm},
\code{complementedPalindromeArmLength}, \code{complementedPalindromeLeftArm}
and \code{complementedPalindromeRightArm} are utility functions for
operating on palindromic or complemented palindromic sequences.
\end{Description}
\begin{Usage}
\begin{verbatim}
  findPalindromes(subject, min.armlength=4, max.looplength=1, min.looplength=0, max.mismatch=0)
  palindromeArmLength(x, max.mismatch=0, ...)
  palindromeLeftArm(x, max.mismatch=0, ...)
  palindromeRightArm(x, max.mismatch=0, ...)

  findComplementedPalindromes(subject, min.armlength=4, max.looplength=1, min.looplength=0, max.mismatch=0)
  complementedPalindromeArmLength(x, max.mismatch=0, ...)
  complementedPalindromeLeftArm(x, max.mismatch=0, ...)
  complementedPalindromeRightArm(x, max.mismatch=0, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{subject}] An \LinkA{XString}{XString} object containing the subject string,
or an \LinkA{XStringViews}{XStringViews} object.

\item[\code{min.armlength}] An integer giving the minimum length of the arms of the palindromes
(or complemented palindromes) to search for.

\item[\code{max.looplength}] An integer giving the maximum length of "the loop" (i.e the sequence
separating the 2 arms) of the palindromes (or complemented palindromes)
to search for.
Note that by default (\code{max.looplength=1}), \code{findPalindromes}
will search for strict palindromes (or complemented palindromes) only.

\item[\code{min.looplength}] An integer giving the minimum length of "the loop" of the palindromes
(or complemented palindromes) to search for.

\item[\code{max.mismatch}] The maximum number of mismatching letters allowed between the 2 arms of
the palindromes (or complemented palindromes) to search for.

\item[\code{x}] An \LinkA{XString}{XString} object containing a 2-arm palindrome
or complemented palindrome, or an \LinkA{XStringViews}{XStringViews} object containing a set
of 2-arm palindromes or complemented palindromes.

\item[\code{...}] Additional arguments to be passed to or from methods.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The \code{findPalindromes} function finds palindromic substrings in a subject
string. The palindromes that can be searched for are either strict palindromes
or 2-arm palindromes (the former being a particular case of the latter) i.e.
palindromes where the 2 arms are separated by an arbitrary sequence called
"the loop".

Use the \code{findComplementedPalindromes} function to find complemented
palindromic substrings in a \LinkA{DNAString}{DNAString} subject (in a complemented
palindrome the 2 arms are reverse-complementary sequences).
\end{Details}
\begin{Value}
\code{findPalindromes} and \code{findComplementedPalindromes} return an
\LinkA{XStringViews}{XStringViews} object containing all palindromes (or complemented
palindromes) found in \code{subject} (one view per palindromic substring
found).

\code{palindromeArmLength} and \code{complementedPalindromeArmLength} return
the arm length (integer) of the 2-arm palindrome (or complemented palindrome)
\code{x}.
It will raise an error if \code{x} has no arms. Note that any sequence could
be considered a 2-arm palindrome if we were OK with arms of length 0 but we
are not: \code{x} must have arms of length greater or equal to 1 in order to
be considered a 2-arm palindrome. The same apply to 2-arm complemented
palindromes.
When applied to an \LinkA{XStringViews}{XStringViews} object \code{x},
\code{palindromeArmLength} and \code{complementedPalindromeArmLength} behave
in a vectorized fashion by returning an integer vector of the same length
as \code{x}.

\code{palindromeLeftArm} and \code{complementedPalindromeLeftArm} return an
object of the same class as the original object \code{x} and containing the
left arm of \code{x}.

\code{palindromeRightArm} does the same as \code{palindromeLeftArm} but on
the right arm of \code{x}.

Like \code{palindromeArmLength}, both \code{palindromeLeftArm} and
\code{palindromeRightArm} will raise an error if \code{x} has no arms.
Also, when applied to an \LinkA{XStringViews}{XStringViews} object \code{x}, both behave
in a vectorized fashion by returning an \LinkA{XStringViews}{XStringViews} object of the
same length as \code{x}.
\end{Value}
\begin{Author}\relax
H. Pages
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{maskMotif}{maskMotif}},
\code{\LinkA{matchPattern}{matchPattern}},
\code{\LinkA{matchLRPatterns}{matchLRPatterns}},
\code{\LinkA{matchProbePair}{matchProbePair}},
\LinkA{XStringViews-class}{XStringViews.Rdash.class},
\LinkA{DNAString-class}{DNAString.Rdash.class}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  ## Note that complemented palindromes (like palindromes) can be nested
  findComplementedPalindromes(DNAString("ACGTTNAACGT-ACGTTNAACGT"))

  ## A real use case
  library(BSgenome.Dmelanogaster.UCSC.dm3)
  chrX <- Dmelanogaster$chrX
  chrX_pals <- findComplementedPalindromes(chrX, min.armlength=50, max.looplength=20)
  complementedPalindromeArmLength(chrX_pals)  # 251

  ## Of course, whitespaces matter
  palindromeArmLength(BString("was it a car or a cat I saw"))

  ## Note that the 2 arms of a strict palindrome (or strict complemented
  ## palindrome) are equal to the full sequence.
  palindromeLeftArm(BString("Delia saw I was aileD"))
  complementedPalindromeLeftArm(DNAString("N-ACGTT-AACGT-N"))
  palindromeLeftArm(DNAString("N-AAA-N-N-TTT-N"))
\end{ExampleCode}
\end{Examples}

