1\name{utf8_width}
2\title{Measure the Character String Width}
3\alias{utf8_width}
4\description{
5Compute the display widths of the elements of a character object.
6}
7\usage{
8utf8_width(x, encode = TRUE, quote = FALSE, utf8 = NULL)
9}
10\arguments{
11    \item{x}{character object.}
12
13    \item{encode}{whether to encode the object before measuring its
14        width.}
15
16    \item{quote}{whether to quote the object before measuring its
17        width.}
18
19    \item{utf8}{logical scalar indicating whether to determine widths
20        assuming a UTF-8 capable display (ASCII-only otherwise), or
21        \code{NULL} to format for output capabilities as determined
22        by \code{output_utf8()}.}
23}
24\details{
25    \code{utf8_width} returns the printed widths of the elements of
26    a character object on a UTF-8 device (or on an ASCII device
27    when \code{output_utf8()} is \code{FALSE}), when printed with
28    \code{utf8_print}. If the string is not printable on the device,
29    for example if it contains a control code like \code{"\n"}, then
30    the result is \code{NA}. If \code{encode = TRUE}, the default,
31    then the function returns the widths of the encoded elements
32    via \code{utf8_encode}); otherwise, the function returns the
33    widths of the original elements.
34}
35\value{
36    An integer object,  with the same \code{names}, \code{dim}, and
37    \code{dimnames} as \code{x}.
38}
39\seealso{
40    \code{\link{utf8_print}}.
41}
42\examples{
43# the second element is encoded in latin-1, but declared as UTF-8
44x <- c("fa\u00E7ile", "fa\xE7ile", "fa\xC3\xA7ile")
45Encoding(x) <- c("UTF-8", "UTF-8", "bytes")
46
47# get widths
48utf8_width(x)
49utf8_width(x, encode = FALSE)
50utf8_width('"')
51utf8_width('"', quote = TRUE)
52}
53