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