Skip to contents

Convert a vector to a character string

Source: R/vect_to_char.R
vect_to_char.Rd

Convert a vector to a character string while preserving names and rounding numeric values.

Usage

vect_to_char(
  x,
  signif = 3L,
  width = Inf,
  sep = ": ",
  collapse = ", ",
  ignore_newlines = TRUE,
  round_type = c("selective", "expanded", "strict")
)

Arguments

x

A vector, factor, NULL, or a non-dataframe list (unlisted through unlist(x, use.names = TRUE), with a warning).

signif

Positive number indicating the number of significant digits to round numeric x to (see Details) or Inf to not round values.

width

natural number giving the maximum line width (in characters) after wrapping. Can be Inf to not wrap text.

sep

character string used to separate the names and the values. Ignored if x does not have names.

collapse

character string to collapse values into a single character string, or NULL to return each value as an element of a character vector.

ignore_newlines

TRUE or FALSE: should newlines in x be replaced by blank characters?

round_type

character string "selective", "expanded", or "signif" indicating the type of rounding to be used, see Details.

Value

A character vector or character string with the names and values in x, with values of numeric x rounded to signif significant digits, wrapped to width characters.

If collapse is NULL, a character vector with the same elements as x is returned, wrapping on a per-element basis. If collapse is not NULL, the name-value pairs are separated by collapse, thus returning a character string.

See Details on the handling of some special values.

Details

Some values are handled specially to better distinguish different values than message() etc. that use paste0():

  • NULL is returned as "NULL"

  • non-NULL zero-length objects are returned as "<type>(0)" (e.g., "logical(0)"; for numeric(0) this is "double(0)")

  • "" is returned as ""

  • logical NA is returned as "NA"

  • non-logical NA is returned as "NA_<type>_" (e.g., "NA_character_"; for NA_real_ this is "NA_double_"; for factors this is "NA_character_" because vect_to_char() converts factors to characters).

Numeric values are not rounded if digits is Inf. Otherwise, numeric values are rounded to at least digits significant digits while ensuring their integer parts are unrounded (if round_type is selective or expanded, see signif_custom() for details) or are rounded to exactly digits significant digits while their integer parts might be rounded (if round_type is signif).

Programming notes

To get a cross-tabulation of x into a character string, one can use paste0(vect_to_char(c(table(x)), sep = " (", collapse = "), "), ")"), see the last Example.

See also

toString() which is shorthand for paste(x, collapse = ", ") and can be used instead of vect_to_char() if names of x can be removed; vignette("type_coercion", package = "checkinput") and help("is_zerolength", package = "checkinput") for a discussion of some issues with type conversion and zero-length input when combining objects into a vector.

Other functions to convert types: as.numeric_safe(), reexports, reorder_levels()

Other functions to modify character vectors: as.numeric_safe(), reexports, replace_vals(), signal_text(), unpaste_unquote(), wrap_text()

Other functions to modify factors: as.numeric_safe(), reexports, reorder_levels(), replace_vals()

Examples

x <- 1:3
names(x) <- letters[x]
vect_to_char(x = x) # "a: 1, b: 2, c: 3"
#> [1] "a: 1, b: 2, c: 3"
vect_to_char(x = x, collapse = NULL) # c("a: 1", "b: 2", "c: 3")
#> [1] "a: 1" "b: 2" "c: 3"
vect_to_char(x = unname(x)) # "1, 2, 3"
#> [1] "1, 2, 3"
y <- x / 7
vect_to_char(x = y, signif = 7) # "a: 0.1428571, b: 0.2857143, c: 0.4285714"
#> [1] "a: 0.1428571, b: 0.2857143, c: 0.4285714"
vect_to_char(x = y, signif = 2, sep = " = ", collapse = " and ", width = 15)
#> [1] "a = 0.14 and b\n= 0.29 and c =\n0.43"
# "a = 0.14 and b\n= 0.29 and c =\n0.43"
vect_to_char(x = 1e3/7, signif = 2) # not 140: completely display integer part
#> [1] "143"

x_char <- c(a = "abc", b = "def", c = "this is text")
vect_to_char(x = x_char) # "a: abc, b: def, c: this is text"
#> [1] "a: abc, b: def, c: this is text"
vect_to_char(x = unname(x_char)) # "abc, def, this is some text"
#> [1] "abc, def, this is text"

# Nicer handling of zero-length input
vect_to_char(logical(0)) # "logical(0)"
#> [1] "logical(0)"
message(logical(0)) # <empty>
#> 
message(vect_to_char(logical(0))) # logical(0)
#> logical(0)

# Using vect_to_char() to get a frequency table
x <- 1:10
names(x) <- letters[x]
y <- 5:15
names(y) <- letters[y]
x <- c(x, y)
paste0(vect_to_char(c(table(x)), sep = " (", collapse =  "), "), ")")
#> [1] "1 (1), 2 (1), 3 (1), 4 (1), 5 (2), 6 (2), 7 (2), 8 (2), 9 (2), 10 (2), 11 (1), 12 (1), 13 (1), 14 (1), 15 (1)"