Encode Character Object as for UTF-8 Printing

Escape the strings in a character object, optionally adding quotes or spaces, adjusting the width for display.

utf8_encode(x, width = 0L, quote = FALSE, justify = "left", escapes = NULL,
            display = FALSE, utf8 = NULL)

Arguments

x

character object.

width

integer giving the minimum field width; specify NULL or NA for no minimum.

quote

logical scalar indicating whether to surround results with double-quotes and escape internal double-quotes.

justify

justification; one of "left", "right", "centre", or "none". Can be abbreviated.

escapes

a character string specifying the display style for the backslash escapes, as an ANSI SGR parameter string, or NULL for no styling.

display

logical scalar indicating whether to optimize the encoding for display, not byte-for-byte data transmission.

utf8

logical scalar indicating whether to encode for a UTF-8 capable display (ASCII-only otherwise), or NULL to encode for output capabilities as determined by output_utf8().

Details

utf8_encode encodes a character object for printing on a UTF-8 device by escaping controls characters and other non-printable characters. When display = TRUE, the function optimizes the encoding for display by removing default ignorable characters (soft hyphens, zero-width spaces, etc.) and placing zero-width spaces after wide emoji. When output_utf8() is FALSE the function escapes all non-ASCII characters and gives the same results on all platforms.

Value

A character object with the same attributes as x but with

Encoding set to "UTF-8".

See also

utf8_print.

Examples

# the second element is encoded in latin-1, but declared as UTF-8
x <- c("fa\u00E7ile", "fa\xE7ile", "fa\xC3\xA7ile")
Encoding(x) <- c("UTF-8", "UTF-8", "bytes")

# encoding
utf8_encode(x)
#> [1] "façile"          "fa\\xe7ile"      "fa\\xc3\\xa7ile"

# add style to the escapes
cat(utf8_encode("hello\nstyled\\world", escapes = "1"), "\n")
#> hello\nstyled\\world