Formatting Utilities

Source: R/utils.R, R/knitr.R

str_out formats character vectors for use in show methods or error/warning messages.

str_out(
  x,
  max = 3L,
  quote = is.character(x),
  use.names = FALSE,
  sep = ", ",
  total = FALSE
)

str_desc(object, exdent = 0L)

str_fun(object)

str_class(x, max = Inf, ...)

str_pkg(pkg, lib.loc = NULL)

str_md5sum(x)

str_hash(x, algo = "md5")

str_dim(x, dims = dim(x))

str_bs(x)

Arguments

x

character vector
max

maximum number of values to appear in the list. If x has more elements than max, a "..." suffix is appended.
quote

a logical indicating whether the values should be quoted with single quotes (defaults) or not.
use.names

a logical indicating whether names should be added to the list as NAME=VAL, ... or not (default).
sep

separator character
total

logical that indicates if the total number of elements should be appended to the formatted string as "'a', ..., 'z' (<N> total)".
object

an R object
exdent

extra indentation passed to str_wrap, and used if the output should spread over more than one lines.
...

other arguments passed to str_out.
pkg

package name
lib.loc

path to a library of R packages
algo

The algorithms to be used; currently available choices are md5, which is also the default, sha1, crc32, sha256, sha512, xxhash32, xxhash64, murmur32 and spookyhash.
dims

a numeric vector of dimensions. Default is to use the input object dimensions (via function dims())

Value

a single character string

Functions

  • str_desc: builds formatted string from a list of complex values.

  • str_fun: extracts and formats a function signature. It typically formats the output capture.output(args(object)).

  • str_class: outputs the class(es) of an object using str_out.

  • str_pkg: formats a package name and version

  • str_md5sum: computes md5sum on character vector using md5sum.

  • str_hash: computes hash of a character vector using digest.

  • str_dim: builds a string that describes the dimension of an object, in the form n x m for 2D-objects, n x m x p for 3D-objects, and so on.

  • str_bs: substitutes backspace characters (\\b) to produce a character string as it would be displayed in the console.

Author

Renaud Gaujoux

str_bs was adapted from a proposal from Yihui Xie.

Examples


x <- letters[1:10]
str_out(x)

#> [1] "'a', 'b', ..., 'j'"
str_out(x, 8)

#> [1] "'a', 'b', 'c', 'd', 'e', 'f', 'g', ..., 'j'"
str_out(x, Inf)

#> [1] "'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j'"
str_out(x, quote=FALSE)

#> [1] "a, b, ..., j"
str_out(x, total = TRUE)

#> [1] "'a', 'b', ..., 'j' (10 total)"

str_fun(install.packages)

#> [1] "function (pkgs, lib, repos = getOption(\"repos\"), contriburl = contrib.url(repos, \n    type), method, available = NULL, destdir = NULL, dependencies = NA, \n    type = getOption(\"pkgType\"), configure.args = getOption(\"configure.args\"), \n    configure.vars = getOption(\"configure.vars\"), clean = FALSE, \n    Ncpus = getOption(\"Ncpus\", 1L), verbose = getOption(\"verbose\"), \n    libs_only = FALSE, INSTALL_opts, quiet = FALSE, keep_outputs = FALSE, \n    ...) "
str_class(matrix())

#> [1] "'matrix', 'array'"

# Backspace substitution
str_bs("abc")

#> [1] "abc"
str_bs("abc\b")

#> [1] "ab"
str_bs("abc\b\b")

#> [1] "a"
str_bs("abc\bd")

#> [1] "abd"
str_bs("abc\b\bde\b")

#> [1] "ad"

# more complex example
x <- "\bab\nc\bd\n\babc\b\bd"
cat(x, "\n")

#> ab
#> cd
#> abcd 
y <- str_bs(x)
y

#> [1] "ab\nd\nad"
cat(y, "\n")

#> ab
#> d
#> ad