\HeaderA{letter}{Subsetting a string}{letter}
\aliasA{letter,character-method}{letter}{letter,character.Rdash.method}
\aliasA{letter,MaskedXString-method}{letter}{letter,MaskedXString.Rdash.method}
\aliasA{letter,XString-method}{letter}{letter,XString.Rdash.method}
\aliasA{letter,XStringViews-method}{letter}{letter,XStringViews.Rdash.method}
\keyword{methods}{letter}
\begin{Description}\relax
Extract a substring from a string by picking up individual
letters by their position.
\end{Description}
\begin{Usage}
\begin{verbatim}
  letter(x, i)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A character vector, or an \LinkA{XString}{XString}, \LinkA{XStringViews}{XStringViews}
or \LinkA{MaskedXString}{MaskedXString} object.

\item[\code{i}] An integer vector with no NAs.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Unlike with the \code{substr} or \code{substring} functions,
\code{i} must contain valid positions.
\end{Details}
\begin{Value}
A character vector of length 1 when \code{x} is an \LinkA{XString}{XString}
or \LinkA{MaskedXString}{MaskedXString} object (the masks are ignored for the latter).

A character vector of the same length as \code{x} when \code{x}
is a character vector or an \LinkA{XStringViews}{XStringViews} object.

Note that, because \code{i} must contain valid positions,
all non-NA elements in the result are guaranteed to have exactly
\code{length(i)} characters.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{subseq}{subseq}},
\LinkA{XString-class}{XString.Rdash.class},
\LinkA{XStringViews-class}{XStringViews.Rdash.class},
\LinkA{MaskedXString-class}{MaskedXString.Rdash.class}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  x <- c("abcd", "ABC")
  i <- c(3, 1, 1, 2, 1)

  ## With a character vector:
  letter(x[1], 3:1)
  letter(x, 3)
  letter(x, i)
  #letter(x, 4)             # Error!

  ## With a BString object:
  letter(BString(x[1]), i)  # returns a character vector
  BString(x[1])[i]          # returns a BString object

  ## With an XStringViews object:
  x2 <- XStringViews(x, "BString")
  letter(x2, i)
\end{ExampleCode}
\end{Examples}

