\HeaderA{nchar}{Count the Number of Characters (or Bytes or Width)}{nchar}
\aliasA{nzchar}{nchar}{nzchar}
\keyword{character}{nchar}
\begin{Description}\relax
\code{nchar} takes a character vector as an argument and
returns a vector whose elements contain the sizes of
the corresponding elements of \code{x}.

\code{nzchar} is a fast way to find out if elements of a character
vector are non-empty strings.
\end{Description}
\begin{Usage}
\begin{verbatim}
nchar(x, type = "chars", allowNA = FALSE)

nzchar(x)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] character vector, or a vector to be coerced to a character
vector.
\item[\code{type}] character string: partial matching to one of
\code{c("bytes", "chars", "width")}.  See Details.
\item[\code{allowNA}] logical: show \code{NA} be returned for invalid
multibyte strings (rather than throwing an error)?
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The \sQuote{size} of a character string can be measured in one of
three ways
\describe{
\item[\code{bytes}] The number of bytes needed to store the string
(plus in C a final terminator which is not counted).
\item[\code{chars}] The number of human-readable characters.
\item[\code{width}] The number of columns \code{cat} will use to
print the string in a monospaced font.  The same as \code{chars}
if this cannot be calculated.
}
These will often be the same, and almost always will be in single-byte
locales.  There will be differences between the first two with
multibyte character sequences, e.g. in UTF-8 locales.
If the byte stream contains embedded \code{nul} bytes,
\code{type = "bytes"} looks at all the bytes whereas the other two
types look only at the string as printed by \code{cat}, up to the
first \code{nul} byte.

The internal equivalent of the default method of
\code{\LinkA{as.character}{as.character}} is performed on \code{x} (so there is no
method dispatch).  If you want to operate on non-vector objects
passing them through \code{\LinkA{deparse}{deparse}} first will be required.
\end{Details}
\begin{Value}
For \code{nchar}, an integer vector giving the sizes of each element,
currently always \code{2} for missing values (for \code{NA}).

If \code{allowNA = TRUE} and an element is invalid in a multi-byte
character set such as UTF-8, its number of characters and the width
will be \code{NA}.  Otherwise the number of characters will be
non-negative, so \code{!is.na(nchar(x, "chars", TRUE))} is a test of
validity.

Names, dims and dimnames are copied from the input.

For \code{nzchar}, a logical vector of the same length as \code{x},
true if and only if the element has non-zero length.
\end{Value}
\begin{Note}\relax
This does \strong{not} by default give the number of characters that
will be used to \code{print()} the string.  Use
\code{\LinkA{encodeString}{encodeString}} to find the characters used to print the
string.

Embedded \code{nul} bytes are included in the byte count (but not the
final \code{nul}).  In contrast, characters are counted up to the
string terminator (the first \code{nul} that is not part of a
character representation).
\end{Note}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{strwidth}{strwidth}} giving width of strings for plotting;
\code{\LinkA{paste}{paste}}, \code{\LinkA{substr}{substr}}, \code{\LinkA{strsplit}{strsplit}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- c("asfef", "qwerty", "yuiop[", "b", "stuff.blah.yech")
nchar(x)
# 5  6  6  1 15

nchar(deparse(mean))
# 18 17
\end{ExampleCode}
\end{Examples}

