vctrs (version 0.7.0)

vec_ptype: Find the prototype of a set of vectors

Description

• vec_ptype() returns the unfinalised prototype of a single vector.

• vec_ptype_common() returns the common type of multiple vectors. By default, this is finalised for immediate usage, but can optionally be left unfinalised for advanced common type determination.

• vec_ptype_show() nicely prints the common type of any number of inputs, and is designed for interactive exploration.

Usage

vec_ptype(x, ..., x_arg = "", call = caller_env())
vec_ptype_common(
  ...,
  .ptype = NULL,
  .finalise = TRUE,
  .arg = "",
  .call = caller_env()
)
vec_ptype_show(...)

Value

vec_ptype() and vec_ptype_common() return a prototype (a size-0 vector).

Arguments

x

A vector

...

For vec_ptype(), these dots are for future extensions and must be empty.

For vec_ptype_common() and vec_ptype_show(), vector inputs.

x_arg

Argument name for x. This is used in error messages to inform the user about the locations of incompatible types.

call, .call

The execution environment of a currently running function, e.g. caller_env(). The function will be mentioned in error messages as the source of the error. See the call argument of abort() for more information.

.ptype

If NULL, the default, the output type is determined by computing the common type across all elements of ....

Alternatively, you can supply .ptype to give the output known type. If getOption("vctrs.no_guessing") is TRUE you must supply this value: this is a convenient way to make production code demand fixed types.

.finalise

Should vec_ptype_common() finalise its output?

• If TRUE, vec_ptype_finalise() is called on the final ptype before it is returned. Practically this has the effect of converting any types from unspecified to logical.

• If FALSE, unspecified types are left unfinalised, which can be useful for advanced cases where you combine one common type result with another type via vec_ptype2(). Note that you must manually call vec_ptype_finalise() on the final ptype before supplying it to any other vctrs functions.

.arg

An argument name as a string. This argument will be mentioned in error messages as the input that is at the origin of a problem.

<code>vec_ptype()</code>

vec_ptype() returns size 0 vectors potentially containing attributes but no data. Generally, this is just vec_slice(x, 0L), but some inputs require special handling.

• While you can't slice NULL, the prototype of NULL is itself. This is because we treat NULL as an identity value in the vec_ptype2() monoid.

• The prototype of logical vectors that only contain missing values is the special unspecified type, which can be coerced to any other 1d type. This allows bare NAs to represent missing values for any 1d vector type. Finalising this type converts it from unspecified back to logical.

See internal-faq-ptype2-identity for more information about identity values.

vec_ptype() is a performance generic. It is not necessary to implement it because the default method will work for any vctrs type. However the default method builds around other vctrs primitives like vec_slice() which incurs performance costs. If your class has a static prototype, you might consider implementing a custom vec_ptype() method that returns a constant. This will improve the performance of your class in many cases (common type imputation in particular).

Because it may contain unspecified vectors, the prototype returned by vec_ptype() is said to be unfinalised. Call vec_ptype_finalise() to finalise it.

<code>vec_ptype_common()</code>

vec_ptype_common() first finds the prototype of each input, then successively calls vec_ptype2() to find a common type. It returns a finalised prototype by default, but can optionally be left unfinalised for advanced common type determination.

Dependencies of <code>vec_ptype()</code>

• vec_slice() for returning an empty slice

Dependencies of <code>vec_ptype_common()</code>

• vec_ptype2()

• vec_ptype_finalise()

Examples

# Unknown types ------------------------------------------
vec_ptype_show()
vec_ptype_show(NULL)

# Vectors ------------------------------------------------
vec_ptype_show(1:10)
vec_ptype_show(letters)
vec_ptype_show(TRUE)

vec_ptype_show(Sys.Date())
vec_ptype_show(Sys.time())
vec_ptype_show(factor("a"))
vec_ptype_show(ordered("a"))

# Matrices -----------------------------------------------
# The prototype of a matrix includes the number of columns
vec_ptype_show(array(1, dim = c(1, 2)))
vec_ptype_show(array("x", dim = c(1, 2)))

# Data frames --------------------------------------------
# The prototype of a data frame includes the prototype of
# every column
vec_ptype_show(iris)

# The prototype of multiple data frames includes the prototype
# of every column that in any data frame
vec_ptype_show(
  data.frame(x = TRUE),
  data.frame(y = 2),
  data.frame(z = "a")
)

# Finalisation -------------------------------------------

# `vec_ptype()` and `vec_ptype2()` return unfinalised ptypes so that they
# can be coerced to any other type
vec_ptype(NA)
vec_ptype2(NA, NA)

# By default `vec_ptype_common()` finalises so that you can use its result
# directly in other vctrs functions
vec_ptype_common(NA, NA)

# You can opt out of finalisation to make it work like `vec_ptype()` and
# `vec_ptype2()` with `.finalise = FALSE`, but don't forget that you must
# call `vec_ptype_finalise()` manually if you do so!
vec_ptype_common(NA, NA, .finalise = FALSE)
vec_ptype_finalise(vec_ptype_common(NA, NA, .finalise = FALSE))

# This can be useful in rare scenarios, like including a separate `default`
# argument in the ptype computation
xs <- list(NA, NA)
default <- "a"
try(vec_ptype2(vec_ptype_common(!!!xs), default))
vec_ptype2(vec_ptype_common(!!!xs, .finalise = FALSE), default)