1\name{utf8_format}
2\title{UTF-8 Text Formatting}
3\alias{utf8_format}
4\description{
5Format a character object for UTF-8 printing.
6}
7\usage{
8utf8_format(x, trim = FALSE, chars = NULL, justify = "left",
9            width = NULL, na.encode = TRUE, quote = FALSE,
10            na.print = NULL, print.gap = NULL, utf8 = NULL, ...)
11}
12\arguments{
13\item{x}{character object.}
14
15\item{trim}{logical scalar indicating whether to suppress padding
16    spaces around elements.}
17
18\item{chars}{integer scalar indicating the maximum number of
19    character units to display.  Wide characters like emoji take
20    two character units; combining marks and default ignorables
21    take none. Longer strings get truncated and suffixed or prefixed
22    with an ellipsis (\code{"..."} or \code{"\u2026"}, whichever is most
23    appropriate for the current character locale). Set to \code{NULL} to
24    limit output to the line width as determined by
25    \code{getOption("width")}.}
26
27\item{justify}{justification; one of \code{"left"}, \code{"right"},
28    \code{"centre"}, or \code{"none"}. Can be abbreviated.}
29
30\item{width}{the minimum field width; set to \code{NULL} or
31    \code{0} for no restriction.}
32
33\item{na.encode}{logical scalar indicating whether to encode
34    \code{NA} values as character strings.}
35
36\item{quote}{logical scalar indicating whether to format for a context
37    with surrounding double-quotes (\code{'"'}) and escaped internal
38    double-quotes.}
39
40\item{na.print}{character string (or \code{NULL}) indicating the
41    encoding for \code{NA} values. Ignored when \code{na.encode}
42    is \code{FALSE}.}
43
44\item{print.gap}{non-negative integer (or \code{NULL}) giving the
45    number of spaces in gaps between columns; set to \code{NULL}
46    or \code{1} for a single space.}
47
48\item{utf8}{logical scalar indicating whether to format for a UTF-8
49    capable display (ASCII-only otherwise), or \code{NULL} to
50    format for output capabilities as determined by \code{output_utf8()}.}
51
52\item{...}{further arguments passed from other methods. Ignored.}
53}
54\details{
55\code{utf8_format} formats a character object for printing, optionally
56truncating long character strings.
57}
58\value{
59A character object with the same attributes as \code{x} but with
60\code{Encoding} set to \code{"UTF-8"} for elements that can be
61converted to valid UTF-8 and \code{"bytes"} for others.
62}
63\seealso{
64\code{\link{utf8_print}}, \code{\link{utf8_encode}}.
65}
66\examples{
67# the second element is encoded in latin-1, but declared as UTF-8
68x <- c("fa\u00E7ile", "fa\xE7ile", "fa\xC3\xA7ile")
69Encoding(x) <- c("UTF-8", "UTF-8", "bytes")
70
71# formatting
72utf8_format(x, chars = 3)
73utf8_format(x, chars = 3, justify = "centre", width = 10)
74utf8_format(x, chars = 3, justify = "right")
75}
76