The R Project SVN R

% File src/library/base/man/encodeString.Rd

% Part of the R package, https://www.R-project.org

% Copyright 1995-2022 R Core Team

% Distributed under GPL 2 or later

\name{encodeString}

\alias{encodeString}

\title{

  Encode Character Vector as for Printing

}

\description{

  \code{encodeString} escapes the strings in a character vector in the

  same way \code{print.default} does, and optionally fits the encoded

  strings within a field width.

}

\usage{

encodeString(x, width = 0, quote = "", na.encode = TRUE,

             justify = c("left", "right", "centre", "none"))

}

\arguments{

  \item{x}{a character vector, or an object that can be coerced to one

    by \code{\link{as.character}}.}

  \item{width}{integer: the minimum field width.  If \code{NULL} or

    \code{NA}, this is taken to be the largest field width needed for

    any element of \code{x}.}

  \item{quote}{character: quoting character, if any.}

  \item{na.encode}{logical: should \code{NA} strings be encoded?}

  \item{justify}{character: partial matches are allowed.  If padding to

    the minimum field width is needed, how should spaces be inserted?

    \code{justify == "none"} is equivalent to \code{width = 0}, for

    consistency with \code{format.default}.}

}

\details{

  This escapes backslash and the control characters \samp{\\a} (bell),

  \samp{\\b} (backspace), \samp{\\f} (form feed),

  \samp{\\n} (line feed, aka \dQuote{newline}),

  \samp{\\r} (carriage return), \samp{\\t} (tab) and \samp{\\v}

  (vertical tab) as well as any non-printable characters in a

  single-byte locale, which are printed in octal notation (\samp{\\xyz}

  with leading zeroes).

  Which characters are non-printable depends on the current locale.

  Windows' reporting of printable characters is unreliable, so there all

  other control characters are regarded as non-printable, and all

  characters with codes 32--255 as printable in a single-byte locale.

  See \code{\link{print.default}} for how non-printable characters are

  handled in multi-byte locales.

  If \code{quote} is a single or double quote any embedded quote of the

  same type is escaped.  Note that justification is of the quoted

  string, hence spaces are added outside the quotes.

}

\note{

  The default for \code{width} is different from \code{format.default},

  which does similar things for character vectors but without encoding

  using escapes.

}

\value{

  A character vector of the same length as \code{x}, with the same

  attributes (including names and dimensions) but with no class set.

  Marked UTF-8 encodings are preserved.

}

\seealso{

  \code{\link{print.default}}

}

\examples{

x <- "ab\bc\ndef"

print(x)

cat(x) # interprets escapes

cat(encodeString(x), "\n", sep = "") # similar to print()

factor(x) # makes use of this to print the levels

x <- c("a", "ab", "abcde")

encodeString(x) # width = 0: use as little as possible

encodeString(x, 2) # use two or more (left justified)

encodeString(x, width = NA) # left justification

encodeString(x, width = NA, justify = "c")

encodeString(x, width = NA, justify = "r")

encodeString(x, width = NA, quote = "'", justify = "r")

}

\keyword{ utilities }