vctrs (version 0.7.0)

vctrs-unspecified: Unspecified vectors and prototype finalisation

Description

unspecified() is the underlying type used to represent logical vectors that only contain NA. These require special handling because we want to allow logical NA to specify missingness that can be cast to any other type.

In vctrs, the <unspecified> type is considered unfinalised and is not suitable for use in most vctrs functions that take a ptype argument, like vec_c(). The purpose of vec_ptype_finalise() is to finalise any <unspecified> types into <logical> after common type determination has been completed.

vec_ptype() and vec_ptype2() return unfinalised types, and will convert a logical vector of NA into an empty <unspecified> type that can combine with any other type. It is unlikely that you will call these yourself, but, if you do, you'll need to manually finalise with vec_ptype_finalise() to take care of any <unspecified> types.

vec_ptype_common() uses both vec_ptype() and vec_ptype2() to compute the common type, but typically returns a finalised type for immediate usage in other vctrs functions. You can optionally skip finalisation by setting .finalise = FALSE, in which case vec_ptype_common() can return <unspecified> and you'll need to manually call vec_ptype_finalise() yourself.

vec_ptype_finalise() is an S3 generic, but it is extremely rare to need to write an S3 method for this. Data frames (and data frame subclasses) are already recursively finalised by the default method. The only time you may need to write an S3 method for vec_ptype_finalise() is if your class wraps an arbitrary vector that has the potential to be a logical vector containing only NAs. See ivs::iv() for an example of this, which wraps arbitrary start and end vectors of the same type into a single interval vector class.

Usage

unspecified(n = 0)
vec_ptype_finalise(x, ...)

Arguments

n

Length of vector

x

A ptype to finalize, typically a result of vec_ptype(), vec_ptype2(), or vec_ptype_common(.finalise = FALSE).

...

These dots are for future extensions and must be empty.

Examples

# Returns `unspecified()`
vec_ptype(NA)
vec_ptype(c(NA, NA))

# We've chosen to make this return `logical()`, but this is admittedly
# ambiguous, as it could be seen as "an empty vector of `NA`s" that could
# also be treated as unspecified.
vec_ptype(logical())

# These return `unspecified()`
vec_ptype2(NA, NA)
vec_ptype2(NA, NULL)
vec_ptype2(NULL, NA)

# An unspecified vector can combine with any other type
vec_ptype2(NA, "x")
vec_ptype2("x", NA)

# Same as using `unspecified()` directly
vec_ptype2(unspecified(1), "x")
vec_ptype2("x", unspecified(1))

# Finalising a ptype turns unspecified back to logical
vec_ptype(NA)
vec_ptype_finalise(vec_ptype(NA))

# This works recursively over data frames
df <- data_frame(x = NA, y = data_frame(z = NA))
vec_ptype_show(vec_ptype(df))
vec_ptype_show(vec_ptype_finalise(vec_ptype(df)))

# `vec_ptype_common()` finalises automatically rather than returning an
# unspecified type
vec_ptype_common(NA)
vec_ptype_common(NA, NA)
vec_ptype_show(vec_ptype_common(df))

# `vec_ptype_common()` lets you opt out of finalisation using `.finalise`
vec_ptype_common(NA, .finalise = FALSE)
vec_ptype_show(vec_ptype_common(df, .finalise = FALSE))