\HeaderA{encodeString}{Encode Character Vector as for Printing}{encodeString}
\keyword{utilities}{encodeString}
\begin{Description}\relax
\code{encodeString} escapes the strings in a character vector in the
same way \code{print.default} does, and optionally fits the encoded
strings within a field width.
\end{Description}
\begin{Usage}
\begin{verbatim}
encodeString(x, width = 0, quote = "", na.encode = TRUE,
             justify = c("left", "right", "centre", "none"))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A character vector, or an object that can be coerced to one
by \code{\LinkA{as.character}{as.character}}.
\item[\code{width}] integer: the minimum field width.  If \code{NULL} or
\code{NA}, this is taken to be the largest field width needed for
any element of \code{x}.
\item[\code{quote}] character: quoting character, if any.
\item[\code{na.encode}] logical: should \code{NA} strings be encoded?
\item[\code{justify}] character: partial matches are allowed.  If padding to
the minimum field width is needed, how should spaces be inserted?
\code{justify == "none"} is equivalent to \code{width = 0}, for
consistency with \code{format.default}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This escapes backslash and the control characters \code{\\a} (bell),
\code{\\b} (backspace), \code{\\f} (formfeed), \code{\\n} (line feed),
\code{\\r} (carriage return), \code{\\t} (tab), \code{\\v} (vertical tab)
and \code{\\0} (nul) as well as any non-printable characters in a
single-byte locale, which are printed in octal notation
(\code{\\xyz} with leading zeroes).
(Which characters are non-printable depends on the current locale.)
See \code{\LinkA{print.default}{print.default}} for how non-printable characters are
handled in multi-byte locales.

If \code{quote} is a single or double quote any embedded quote of the
same type is escaped.  Note that justification is of the quoted
string, hence spaces are added outside the quotes.
\end{Details}
\begin{Value}
A character vector of the same length as \code{x}, with the same
attributes (including names and dimensions) but with no class set.
\end{Value}
\begin{Note}\relax
The default for \code{width} is different from \code{format.default},
which as of \R{} 2.2.0 does similar things for character vectors (but
without encoding using escapes).
\end{Note}
\begin{SeeAlso}\relax
\code{\LinkA{print.default}{print.default}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- "ab\bc\ndef"
print(x)
cat(x) # interprets escapes
cat(encodeString(x), "\n", sep="") # similar to print()

factor(x) # makes use of this to print the levels

x <- c("a", "ab", "abcde")
encodeString(x, w = NA) # left justification
encodeString(x, w = NA, justify = "c")
encodeString(x, w = NA, justify = "r")
encodeString(x, w = NA, quote = "'", justify = "r")
\end{ExampleCode}
\end{Examples}

