\inputencoding{latin1}
\HeaderA{Encoding}{Read or Set the Declared Encodings for a Character Vector}{Encoding}
\aliasA{Encoding<\Rdash}{Encoding}{Encoding<.Rdash.}
\keyword{utilities}{Encoding}
\keyword{character}{Encoding}
\begin{Description}\relax
Read or set the declared encodings for a character vector.
\end{Description}
\begin{Usage}
\begin{verbatim}
Encoding(x)

Encoding(x) <- value
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A character vector.
\item[\code{value}] A character vector of positive length.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Character strings in \R{} can be declared to be in \code{"latin1"} or
\code{"UTF-8"}.  These declarations can be read by \code{Encoding},
which will return a character vector of values \code{"latin1"},
\code{"UTF-8"} or \code{"unknown"}, or set, when \code{value} is
recycled as needed and other values are silently treated as
\code{"unknown"}.  ASCII strings will never be marked with a declared
encoding, since their representation is the same in all encodings.


There are other ways for character strings to acquire a declared
encoding apart from explicitly setting it (and these have changed as
\R{} has evolved).  Functions \code{\LinkA{scan}{scan}},
\code{\LinkA{read.table}{read.table}}, \code{\LinkA{readLines}{readLines}}, and
\code{\LinkA{parse}{parse}} have an \code{encoding} argument that is used to
declare encodings, \code{\LinkA{iconv}{iconv}} declares encodings from its
\code{from} argument, and console input in suitable locales is also
declared.  \code{\LinkA{intToUtf8}{intToUtf8}} declares its output as
\code{"UTF-8"}, and output text connections are marked if running in a
suitable locale.  Under some circumstances (see its help page)
\code{\LinkA{source}{source}(encoding=)} will mark encodings of character
strings it outputs.

Most character manipulation functions will set the encoding on output
strings if it was declared on the corresponding input.  These include
\code{\LinkA{chartr}{chartr}}, \code{\LinkA{strsplit}{strsplit}}, \code{\LinkA{strtrim}{strtrim}},
\code{\LinkA{tolower}{tolower}} and \code{\LinkA{toupper}{toupper}}
as well as \code{\LinkA{sub}{sub}(useBytes = FALSE)} and
\code{\LinkA{gsub}{gsub}(useBytes = FALSE)}.  Note that such functions
do not \emph{preserve} the encoding, but if they know the input
encoding and that the string has been successfully re-encoded to the
current encoding, they mark the output with the latter (if it is
\code{"latin1"} or \code{"UTF-8"}).

\code{\LinkA{substr}{substr}} does preserve the encoding, and
\code{\LinkA{chartr}{chartr}}, \code{\LinkA{tolower}{tolower}} and \code{\LinkA{toupper}{toupper}}
preserve UTF-8 encoding on systems with Unicode wide characters.  With
their \code{fixed} and \code{perl} options, \code{\LinkA{strsplit}{strsplit}},
\code{\LinkA{sub}{sub}} and \code{gsub} will give a marked UTF-8 result if
any of the inputs are UTF-8.

\code{\LinkA{paste}{paste}} and \code{\LinkA{sprintf}{sprintf}} return a UTF-8 marked
element if any of the inputs to that element are UTF-8.
\end{Details}
\begin{Value}
A character vector.
\end{Value}
\begin{Examples}
\begin{ExampleCode}
## x is intended to be in latin1
x <- "fa\xE7ile"
Encoding(x)
Encoding(x) <- "latin1"
x
xx <- iconv(x, "latin1", "UTF-8")
Encoding(c(x, xx))
c(x, xx)
\end{ExampleCode}
\end{Examples}

