[](https://codecov.io/github/r-lib/vctrs?branch=master)
[](https://www.tidyverse.org/lifecycle/#maturing)
There are three main goals to the vctrs package, each described in a
vignette:
- To propose `vec_size()` and `vec_ptype()` as alternatives to
`length()` and `class()`; `vignette("type-size")`. These definitions
are paired with a framework for size-recycling and type-coercion.
`ptype` should evoke the notion of a prototype, i.e. the original or
typical form of something.
- To define size- and type-stability as desirable function properties,
use them to analyse existing base functions, and to propose better
alternatives; `vignette("stability")`. This work has been
particularly motivated by thinking about the ideal properties of
`c()`, `ifelse()`, and `rbind()`.
- To provide a new `vctr` base class that makes it easy to create new
S3 vectors; `vignette("s3-vector")`. vctrs provides methods for many
base generics in terms of a few new vctrs generics, making
implementation considerably simpler and more robust.
vctrs is a developer-focussed package. Understanding and extending vctrs
requires some effort from developers, but should be invisible to most
users. It’s our hope that having an underlying theory will mean that
users can build up an accurate mental model without explicitly learning
the theory. vctrs will typically be used by other packages, making it
easy for them to provide new classes of S3 vectors that are supported
throughout the tidyverse (and beyond). For that reason, vctrs has few
dependencies.
## Installation
Install vctrs from CRAN with:
``` r
install.packages("vctrs")
```
Alternatively, if you need the development version, install it with:
``` r
# install.packages("devtools")
devtools::install_github("r-lib/vctrs")
```
## Usage
``` r
library(vctrs)
# Sizes
str(vec_size_common(1, 1:10))
#> int 10
str(vec_recycle_common(1, 1:10))
#> List of 2
#> $ : num [1:10] 1 1 1 1 1 1 1 1 1 1
#> $ : int [1:10] 1 2 3 4 5 6 7 8 9 10
# Prototypes
str(vec_ptype_common(FALSE, 1L, 2.5))
#> num(0)
str(vec_cast_common(FALSE, 1L, 2.5))
#> List of 3
#> $ : num 0
#> $ : num 1
#> $ : num 2.5
```
## Motivation
The original motivation for vctrs comes from two separate but related
problems. The first problem is that `base::c()` has rather undesirable
behaviour when you mix different S3 vectors:
``` r
# combining factors makes integers
c(factor("a"), factor("b"))
#> [1] 1 1
# combining dates and date-times gives incorrect values; also, order matters
dt <- as.Date("2020-01-01")
dttm <- as.POSIXct(dt)
c(dt, dttm)
#> [1] "2020-01-01" "4321940-06-07"
c(dttm, dt)
#> [1] "2019-12-31 16:00:00 PST" "1969-12-31 21:04:22 PST"
```
This behaviour arises because `c()` has dual purposes: as well as its
primary duty of combining vectors, it has a secondary duty of stripping
attributes. For example, `?POSIXct` suggests that you should use `c()`
if you want to reset the timezone.
The second problem is that `dplyr::bind_rows()` is not extensible by
others. Currently, it handles arbitrary S3 classes using heuristics, but
these often fail, and it feels like we really need to think through the
problem in order to build a principled solution. This intersects with
the need to cleanly support more types of data frame columns, including
lists of data frames, data frames, and matrices.
vctrs/man/ 0000755 0001762 0000144 00000000000 13623045240 012165 5 ustar ligges users vctrs/man/vec_duplicate.Rd 0000644 0001762 0000144 00000003771 13622451540 015276 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dictionary.R
\name{vec_duplicate}
\alias{vec_duplicate}
\alias{vec_duplicate_any}
\alias{vec_duplicate_detect}
\alias{vec_duplicate_id}
\title{Find duplicated values}
\usage{
vec_duplicate_any(x)
vec_duplicate_detect(x)
vec_duplicate_id(x)
}
\arguments{
\item{x}{A vector (including a data frame).}
}
\value{
\itemize{
\item \code{vec_duplicate_any()}: a logical vector of length 1.
\item \code{vec_duplicate_detect()}: a logical vector the same length as \code{x}.
\item \code{vec_duplicate_id()}: an integer vector the same length as \code{x}.
}
}
\description{
\itemize{
\item \code{vec_duplicate_any()}: detects the presence of duplicated values,
similar to \code{\link[=anyDuplicated]{anyDuplicated()}}.
\item \code{vec_duplicate_detect()}: returns a logical vector describing if each
element of the vector is duplicated elsewhere. Unlike \code{\link[=duplicated]{duplicated()}}, it
reports all duplicated values, not just the second and subsequent
repetitions.
\item \code{vec_duplicate_id()}: returns an integer vector giving the location of
the first occurrence of the value.
}
}
\section{Missing values}{
In most cases, missing values are not considered to be equal, i.e.
\code{NA == NA} is not \code{TRUE}. This behaviour would be unappealing here,
so these functions consider all \code{NAs} to be equal. (Similarly,
all \code{NaN} are also considered to be equal.)
}
\examples{
vec_duplicate_any(1:10)
vec_duplicate_any(c(1, 1:10))
x <- c(10, 10, 20, 30, 30, 40)
vec_duplicate_detect(x)
# Note that `duplicated()` doesn't consider the first instance to
# be a duplicate
duplicated(x)
# Identify elements of a vector by the location of the first element that
# they're equal to:
vec_duplicate_id(x)
# Location of the unique values:
vec_unique_loc(x)
# Equivalent to `duplicated()`:
vec_duplicate_id(x) == seq_along(x)
}
\seealso{
\code{\link[=vec_unique]{vec_unique()}} for functions that work with the dual of duplicated
values: unique values.
}
vctrs/man/vec_seq_along.Rd 0000644 0001762 0000144 00000001355 13622451540 015270 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/size.R
\name{vec_seq_along}
\alias{vec_seq_along}
\alias{vec_init_along}
\title{Useful sequences}
\usage{
vec_seq_along(x)
vec_init_along(x, y = x)
}
\arguments{
\item{x, y}{Vectors}
}
\value{
\itemize{
\item \code{vec_seq_along()} an integer vector with the same size as \code{x}.
\item \code{vec_init_along()} a vector with the same type as \code{x} and the same size
as \code{y}.
}
}
\description{
\code{vec_seq_along()} is equivalent to \code{\link[=seq_along]{seq_along()}} but uses size, not length.
\code{vec_init_along()} creates a vector of missing values with size matching
an existing object.
}
\examples{
vec_seq_along(mtcars)
vec_init_along(head(mtcars))
}
vctrs/man/vec_list_cast.Rd 0000644 0001762 0000144 00000001421 13622451540 015277 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cast-list.R
\name{vec_list_cast}
\alias{vec_list_cast}
\title{Cast a list to vector of specific type}
\usage{
vec_list_cast(x, to, ..., x_arg = "", to_arg = "")
}
\arguments{
\item{x}{A list}
\item{to}{Type to coerce to}
\item{...}{These dots are for future extensions and must be empty.}
}
\description{
This is a function for developers to use when extending vctrs. It casts
a list to a more specific vectoring type, keeping the length constant.
It does this by discarding (with a warning), any elements after the 1.
It is called from \code{vec_cast.XYZ.list()} methods to preserve symmetry with
\code{vec_cast.list.XYZ()}.
}
\details{
See \code{vignette("s3-vector")} for details.
}
\keyword{internal}
vctrs/man/vec_ptype2.Rd 0000644 0001762 0000144 00000005320 13622451540 014537 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/type-bare.R, R/type2.R
\name{vec_ptype2.logical}
\alias{vec_ptype2.logical}
\alias{vec_ptype2.integer}
\alias{vec_ptype2.double}
\alias{vec_ptype2.complex}
\alias{vec_ptype2.character}
\alias{vec_ptype2.raw}
\alias{vec_ptype2.list}
\alias{vec_ptype2}
\alias{vec_default_ptype2}
\title{Find the common type for a pair of vector types}
\usage{
\method{vec_ptype2}{logical}(x, y, ..., x_arg = "x", y_arg = "y")
\method{vec_ptype2}{integer}(x, y, ..., x_arg = "x", y_arg = "y")
\method{vec_ptype2}{double}(x, y, ..., x_arg = "x", y_arg = "y")
\method{vec_ptype2}{complex}(x, y, ..., x_arg = "x", y_arg = "y")
\method{vec_ptype2}{character}(x, y, ..., x_arg = "x", y_arg = "y")
\method{vec_ptype2}{raw}(x, y, ..., x_arg = "x", y_arg = "y")
\method{vec_ptype2}{list}(x, y, ..., x_arg = "x", y_arg = "y")
vec_ptype2(x, y, ..., x_arg = "x", y_arg = "y")
vec_default_ptype2(x, y, ..., x_arg = "x", y_arg = "y")
}
\arguments{
\item{x, y}{Vector types.}
\item{...}{These dots are for future extensions and must be empty.}
\item{x_arg, y_arg}{Argument names for \code{x} and \code{y}. These are used
in error messages to inform the user about the locations of
incompatible types (see \code{\link[=stop_incompatible_type]{stop_incompatible_type()}}).}
}
\description{
\code{vec_ptype2()} finds the common type for a pair of vectors, or dies trying.
It forms the foundation of the vctrs type system, along with \code{\link[=vec_cast]{vec_cast()}}.
This powers type coercion but should not usually be called directly;
instead call \code{\link[=vec_ptype_common]{vec_ptype_common()}}.
}
\section{Coercion rules}{
vctrs thinks of the vector types as forming a partially ordered set, or
poset. Then finding the common type from a set of types is a matter of
finding the least-upper-bound; if the least-upper-bound does not exist,
there is no common type. This is the case for many pairs of 1d vectors.
The poset of the most important base vectors is shown below:
(where datetime stands for \code{POSIXt}, and date for \code{Date})
\figure{coerce.png}
}
\section{S3 dispatch}{
\code{vec_ptype2()} dispatches on both arguments. This is implemented by having
methods of \code{vec_ptype2()}, e.g. \code{vec_ptype2.integer()} also be S3 generics,
which call e.g. \code{vec_ptype2.integer.double()}. \code{vec_ptype2.x.y()} must
return the same value as \code{vec_ptype2.y.x()}; this is currently not enforced,
but should be tested.
Whenever you implement a \code{vec_ptype2.new_class()} generic/method,
make sure to always provide \code{vec_ptype2.new_class.default()}. It
should normally call \code{vec_default_ptype2()}.
See \code{vignette("s3-vector")} for full details.
}
\keyword{internal}
vctrs/man/new_rcrd.Rd 0000644 0001762 0000144 00000001674 13622451540 014272 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/type-rcrd.R
\name{new_rcrd}
\alias{new_rcrd}
\alias{ses}
\alias{rcrd}
\title{rcrd (record) S3 class}
\usage{
new_rcrd(fields, ..., class = character())
}
\arguments{
\item{fields}{A list. It must possess the following properties:
\itemize{
\item no attributes (apart from names)
\item syntactic names
\item length 1 or greater
\item elements are vectors
\item elements have equal length
}}
\item{...}{Additional attributes}
\item{class}{Name of subclass.}
}
\description{
The rcrd class extends \link{vctr}. A rcrd is composed of 1 or more \link{field}s,
which must be vectors of the same length. Is designed specifically for
classes that can naturally be decomposed into multiple vectors of the same
length, like \link{POSIXlt}, but where the organisation should be considered
an implementation detail invisible to the user (unlike a \link{data.frame}).
}
\keyword{internal}
vctrs/man/new_partial.Rd 0000644 0001762 0000144 00000001723 13622451540 014767 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/partial.R
\name{new_partial}
\alias{new_partial}
\alias{is_partial}
\alias{vec_ptype_finalise}
\title{Partial type}
\usage{
new_partial(..., class = character())
is_partial(x)
vec_ptype_finalise(x, ...)
}
\arguments{
\item{...}{Attributes of the partial type}
\item{class}{Name of subclass.}
}
\description{
Use \code{new_partial()} when constructing a new partial type subclass;
and use \code{is_partial()} to test if an type is partial. All subclasses
need to provide a \code{vec_ptype_finalise()} method.
}
\details{
As the name suggests, a partial type \emph{partially} specifies a type, and
it must be combined with data to yield a full type. A useful example
of a partial type is \code{\link[=partial_frame]{partial_frame()}}, which makes it possible to
specify the type of just a few columns in a data frame. Use this constructor
if you're making your own partial type.
}
\keyword{internal}
vctrs/man/faq/ 0000755 0001762 0000144 00000000000 13622451540 012737 5 ustar ligges users vctrs/man/faq/internal/ 0000755 0001762 0000144 00000000000 13622451540 014553 5 ustar ligges users vctrs/man/faq/internal/ptype2-identity.Rmd 0000644 0001762 0000144 00000006120 13622451540 020270 0 ustar ligges users
```{r, child = "setup.Rmd", include = FALSE}
```
## Promotion monoid
Promotions (i.e. automatic coercions) should always transform inputs to their richer type to avoid losing values of precision. `vec_ptype2()` returns the _richer_ type of two vectors, or throws an incompatible type error if none of the two vector types include the other. For example, the richer type of integer and double is the latter because double covers a larger range of values than integer.
`vec_ptype2()` is a [monoid](https://en.wikipedia.org/wiki/Monoid) over vectors, which in practical terms means that it is a well behaved operation for [reduction](https://purrr.tidyverse.org/reference/reduce.html). Reduction is an important operation for promotions because that is how the richer type of multiple elements is computed. As a monoid, `vec_ptype2()` needs an identity element, i.e. a value that doesn't change the result of the reduction. vctrs has two identity values, `NULL` and __unspecified__ vectors.
## The `NULL` identity
As an identity element that shouldn't influence the determination of the common type of a set of vectors, `NULL` is promoted to any type:
```{r}
vec_ptype2(NULL, "")
vec_ptype2(1L, NULL)
```
The common type of `NULL` and `NULL` is the identity `NULL`:
```{r}
vec_ptype2(NULL, NULL)
```
This way the result of `vec_ptype2(NULL, NULL)` does not influence subsequent promotions:
```{r}
vec_ptype2(
vec_ptype2(NULL, NULL),
""
)
```
## Unspecified vectors
In the vctrs coercion system, logical vectors of missing values are also automatically promoted to the type of any other vector, just like `NULL`. We call these vectors unspecified. The special coercion semantics of unspecified vectors serve two purposes:
1. It makes it possible to assign vectors of `NA` inside any type of vectors, even when they are not coercible with logical:
```{r}
x <- letters[1:5]
vec_assign(x, 1:2, c(NA, NA))
```
2. We can't put `NULL` in a data frame, so we need an identity element that behaves more like a vector. Logical vectors of `NA` seem a natural fit for this.
Unspecified vectors are thus promoted to any other type, just like `NULL`:
```{r}
vec_ptype2(NA, "")
vec_ptype2(1L, c(NA, NA))
```
## Finalising common types
vctrs has an internal vector type of class `vctrs_unspecified`. Users normally don't see such vectors in the wild, but they do come up when taking the common type of an unspecified vector with another identity value:
```{r}
vec_ptype2(NA, NA)
vec_ptype2(NA, NULL)
vec_ptype2(NULL, NA)
```
We can't return `NA` here because `vec_ptype2()` normally returns empty vectors. We also can't return `NULL` because unspecified vectors need to be recognised as logical vectors if they haven't been promoted at the end of the reduction.
```{r}
vec_ptype_finalise(vec_ptype2(NULL, NA))
```
See the output of `vec_ptype_common()` which performs the reduction and finalises the type, ready to be used by the caller:
```{r}
vec_ptype_common(NULL, NULL)
vec_ptype_common(NA, NULL)
```
Note that __partial__ types in vctrs make use of the same mechanism. They are finalised with `vec_ptype_finalise()`.
vctrs/man/faq/internal/setup.Rmd 0000644 0001762 0000144 00000000132 13622451540 016353 0 ustar ligges users
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
vctrs/man/vec_is_list.Rd 0000644 0001762 0000144 00000001545 13623045211 014762 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/assert.R
\name{vec_is_list}
\alias{vec_is_list}
\title{Is the object a list?}
\usage{
vec_is_list(x)
}
\arguments{
\item{x}{An object.}
}
\description{
\code{vec_is_list()} tests if \code{x} is considered a list in the vctrs sense. It
returns \code{TRUE} if:
\itemize{
\item \code{x} is a bare list with no class.
\item \code{x} is a list explicitly inheriting from \code{"list"} or \code{"vctrs_list_of"}.
\item \code{x} is an S3 list that \code{\link[=vec_is]{vec_is()}} returns \code{TRUE} for. For this to return
\code{TRUE}, the class must implement a \code{\link[=vec_proxy]{vec_proxy()}} method.
}
}
\details{
Notably, data frames and S3 record style classes like POSIXlt are not
considered lists.
}
\examples{
vec_is_list(list())
vec_is_list(list_of(1))
vec_is_list(data.frame())
}
vctrs/man/vctrs-conditions.Rd 0000644 0001762 0000144 00000006655 13622451540 016003 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/conditions.R
\name{vctrs-conditions}
\alias{vctrs-conditions}
\alias{stop_incompatible_type}
\alias{stop_incompatible_cast}
\alias{stop_incompatible_op}
\alias{stop_incompatible_size}
\alias{maybe_lossy_cast}
\alias{allow_lossy_cast}
\title{Custom conditions for vctrs package}
\usage{
stop_incompatible_type(
x,
y,
x_arg = "",
y_arg = "",
details = NULL,
...,
message = NULL,
class = NULL
)
stop_incompatible_cast(
x,
y,
details = NULL,
...,
x_arg = "",
to_arg = "",
message = NULL,
class = NULL
)
stop_incompatible_op(
op,
x,
y,
details = NULL,
...,
message = NULL,
class = NULL
)
stop_incompatible_size(
x,
y,
x_size,
y_size,
x_arg = "",
y_arg = "",
details = NULL,
...,
message = NULL,
class = NULL
)
maybe_lossy_cast(
result,
x,
to,
lossy = NULL,
locations = NULL,
details = NULL,
...,
x_arg = "",
to_arg = "",
message = NULL,
class = NULL,
.deprecation = FALSE
)
allow_lossy_cast(expr, x_ptype = NULL, to_ptype = NULL)
}
\arguments{
\item{x, y}{Vectors}
\item{details}{Any additional human readable details}
\item{..., message, class}{Only use these fields when creating a subclass.}
\item{result}{The result of a potentially lossy cast.}
\item{to}{Type to cast to.}
\item{lossy}{A logical vector indicating which elements of \code{result}
were lossy.
Can also be a single \code{TRUE}, but note that \code{locations} picks up
locations from this vector by default. In this case, supply your
own location vector, possibly empty.}
\item{locations}{An optional integer vector giving the
locations where \code{x} lost information.}
\item{.deprecation}{If \code{TRUE}, the error is downgraded to a
deprecation warning. This is useful for transitioning your class
to a stricter conversion scheme. The warning advises your users
to wrap their code with \code{allow_lossy_cast()}.}
\item{x_ptype, to_ptype}{Suppress only the casting errors where \code{x}
or \code{to} match these \link[=vec_ptype]{prototypes}.}
\item{subclass}{Use if you want to further customise the class}
}
\value{
\verb{stop_incompatible_*()} unconditionally raise an error of class
\code{"vctrs_error_incompatible_*"} and \code{"vctrs_error_incompatible"}.
}
\description{
These functions are called for their side effect of raising
errors and warnings.
These conditions have custom classes and structures to make
testing easier.
}
\section{Lossy cast errors}{
By default, lossy casts are an error. Use \code{allow_lossy_cast()} to
silence these errors and continue with the partial results. In this
case the lost values are typically set to \code{NA} or to a lower value
resolution, depending on the type of cast.
Lossy cast errors are thrown by \code{maybe_lossy_cast()}. Unlike
functions prefixed with \code{stop_}, \code{maybe_lossy_cast()} usually
returns a result. If a lossy cast is detected, it throws an error,
unless it's been wrapped in \code{allow_lossy_cast()}. In that case, it
returns the result silently.
}
\examples{
# Most of the time, `maybe_lossy_cast()` returns its input normally:
maybe_lossy_cast(c("foo", "bar"), NULL, "", lossy = c(FALSE, FALSE))
# If `lossy` has any `TRUE`, an error is thrown:
try(maybe_lossy_cast(c("foo", "bar"), NULL, "", lossy = c(FALSE, TRUE)))
# Unless lossy casts are allowed:
allow_lossy_cast(
maybe_lossy_cast(c("foo", "bar"), NULL, "", lossy = c(FALSE, TRUE))
)
}
\keyword{internal}
vctrs/man/vec_c.Rd 0000644 0001762 0000144 00000005631 13622451540 013543 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/c.R
\name{vec_c}
\alias{vec_c}
\title{Combine many vectors into one vector}
\usage{
vec_c(
...,
.ptype = NULL,
.name_spec = NULL,
.name_repair = c("minimal", "unique", "check_unique", "universal")
)
}
\arguments{
\item{...}{Vectors to coerce.}
\item{.ptype}{If \code{NULL}, the default, the output type is determined by
computing the common type across all elements of \code{...}.
Alternatively, you can supply \code{.ptype} to give the output known type.
If \code{getOption("vctrs.no_guessing")} is \code{TRUE} you must supply this value:
this is a convenient way to make production code demand fixed types.}
\item{.name_spec}{A name specification for combining
inner and outer names. This is relevant for inputs passed with a
name, when these inputs are themselves named, like \code{outer = c(inner = 1)}, or when they have length greater than 1: \code{outer = 1:2}. By default, these cases trigger an error. You can resolve
the error by providing a specification that describes how to
combine the names or the indices of the inner vector with the
name of the input. This specification can be:
\itemize{
\item A function of two arguments. The outer name is passed as a
string to the first argument, and the inner names or positions
are passed as second argument.
\item An anonymous function as a purrr-style formula.
\item A glue specification of the form \code{"{outer}_{inner}"}.
}
See the \link[=name_spec]{name specification topic}.}
\item{.name_repair}{How to repair names, see \code{repair} options in \code{\link[=vec_as_names]{vec_as_names()}}.}
}
\value{
A vector with class given by \code{.ptype}, and length equal to the
sum of the \code{vec_size()} of the contents of \code{...}.
The vector will have names if the individual components have names
(inner names) or if the arguments are named (outer names). If both
inner and outer names are present, an error is thrown unless a
\code{.name_spec} is provided.
}
\description{
Combine all arguments into a new vector of common type.
}
\section{Invariants}{
\itemize{
\item \code{vec_size(vec_c(x, y)) == vec_size(x) + vec_size(y)}
\item \code{vec_ptype(vec_c(x, y)) == vec_ptype_common(x, y)}.
}
}
\examples{
vec_c(FALSE, 1L, 1.5)
vec_c(FALSE, 1L, "x", .ptype = character())
# Date/times --------------------------
c(Sys.Date(), Sys.time())
c(Sys.time(), Sys.Date())
vec_c(Sys.Date(), Sys.time())
vec_c(Sys.time(), Sys.Date())
# Factors -----------------------------
c(factor("a"), factor("b"))
vec_c(factor("a"), factor("b"))
# By default, named inputs must be length 1:
vec_c(name = 1)
try(vec_c(name = 1:3))
# Pass a name specification to work around this:
vec_c(name = 1:3, .name_spec = "{outer}_{inner}")
# See `?name_spec` for more examples of name specifications.
}
\seealso{
\code{\link[=vec_cbind]{vec_cbind()}}/\code{\link[=vec_rbind]{vec_rbind()}} for combining data frames by rows
or columns.
}
vctrs/man/vec_empty.Rd 0000644 0001762 0000144 00000000615 13622451540 014454 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vctrs-deprecated.R
\name{vec_empty}
\alias{vec_empty}
\title{Is a vector empty}
\usage{
vec_empty(x)
}
\arguments{
\item{x}{An object.}
}
\description{
\Sexpr[results=rd, stage=render]{vctrs:::lifecycle("defunct")}
This function is defunct, please use \code{\link[=vec_is_empty]{vec_is_empty()}}.
}
\keyword{internal}
vctrs/man/internal-faq-ptype2-identity.Rd 0000644 0001762 0000144 00000010213 13623013722 020102 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/faq-internal.R
\name{internal-faq-ptype2-identity}
\alias{internal-faq-ptype2-identity}
\title{Internal FAQ - \code{vec_ptype2()}, \code{NULL}, and unspecified vectors}
\description{
\subsection{Promotion monoid}{
Promotions (i.e. automatic coercions) should always transform inputs to
their richer type to avoid losing values of precision. \code{vec_ptype2()}
returns the \emph{richer} type of two vectors, or throws an incompatible type
error if none of the two vector types include the other. For example,
the richer type of integer and double is the latter because double
covers a larger range of values than integer.
\code{vec_ptype2()} is a \href{https://en.wikipedia.org/wiki/Monoid}{monoid} over
vectors, which in practical terms means that it is a well behaved
operation for
\href{https://purrr.tidyverse.org/reference/reduce.html}{reduction}.
Reduction is an important operation for promotions because that is how
the richer type of multiple elements is computed. As a monoid,
\code{vec_ptype2()} needs an identity element, i.e. a value that doesn’t
change the result of the reduction. vctrs has two identity values,
\code{NULL} and \strong{unspecified} vectors.
}
\subsection{The \code{NULL} identity}{
As an identity element that shouldn’t influence the determination of the
common type of a set of vectors, \code{NULL} is promoted to any type:\if{html}{\out{ jOF.˗|WTn+-C>D )nŝІ"zhUHaFؗ4oaO/zޒyRɌJ-f<XA=PU[Yc!L| !>B|vK"sL
/-*EW«dlQ-*EE_ e-Ȓk^2 v6]Jx,a aik <ãhp^9rX#ܴ]z{;4mvS0p`HuAZ?o#~0 >CR%<< >"3u@h*)1MB)ǂ u9ɑ@*H26aFeimxFY5- G(u}x=6ʷ_\e ПϳXNG^堭
c`g |{'(ErA`Ѝ14[,HM T 6s
>;\Gt\x%{.1 \i5dZy#BAXy]|^?DFjTY@ @= (N01oH7ߣΨ b T/όԱ56T!
Vfȵ=:quVV4S
x}{
endstream
endobj
547 0 obj
<<
/Length 1371
/Filter /FlateDecode
>>
stream
xڵX[o6~=@͒HI{밤X ,3VYrD*
;H6m E#w`۫8]@0FQ̃c"\//a7 ^d3 hr ÔP]]wBOry= q@
(C,b=rl~`+KGúbBPG@Wo_^8XqΝ`Tb$EYJz>e8HQMkV4fam>18yo-L3ߩx [bBjkҝQ|F' 4'u2:4"SQeW
*Pe~_K0A,^߀ızOl-mPȺf(Ik"e|ҔbVvND ;? K#ry8
I͆QNzм禓&|mN{D+;٧{ %9> e㉿ IENDB` vctrs/man/figures/lifecycle-archived.svg 0000644 0001762 0000144 00000001707 13622451540 020104 0 ustar ligges users vctrs/man/figures/lifecycle-soft-deprecated.svg 0000644 0001762 0000144 00000001726 13622451540 021371 0 ustar ligges users vctrs/man/figures/lifecycle-questioning.svg 0000644 0001762 0000144 00000001714 13622451540 020662 0 ustar ligges users vctrs/man/figures/types.graffle 0000644 0001762 0000144 00000032540 13473164157 016345 0 ustar ligges users }isG_:7 >k; Ce9.|vrTxTP?R&Jl%{7X,Pլ1LLA@ic9pZsc#'He"SD5@H#K9=uZ"MTW*큘2iE6Jsb"ҒǂB sY...2
ƖEAZ l`UV?&L{N]H5kpk R#.n#YkF\l!Ot#0B<vڕ&L41p= pvc";DoH. ;AH@*QVQǜS H33> ݴlI=[j=+uAI83پDCI3_pA'+WHMM7P;n T%s@j @j @j @j @j@j @j @j l?Fš
endstream
endobj
504 0 obj
<<
/Length 1016
/Filter /FlateDecode
>>
stream
xڵWM6W\~h)(
urI@i[d {;EKw{H&g <` )$AAEXcBD#hXfOe;/
1AQ .v-l?QİWjLmH7G MR6NKci[YƨenJj6fymTFDsQNKUeYm /Ѹ,^;k?pri] }p/@ x8 ! +'` ?$Ē88e`A.&t8_5=Abx(Hg zt
C(EIL ;Mu1v2kjV@I[HSqA{dukjwk1:"9DSjf'<-̻,m oP ~\ij
(B#,;&|`&m+άemƇD0;ma(D>ńW!u{dm 1O6 e/hB#I*Ì ?e :@ګ;c)TvLM}"Ob 4!&qIr:C*pT
MU]O~?9rV[Kmo>^b$@+~g[|Ts>EoTu0' ??:ͱfeY`Nۦ**Pwz;}hgKy֤Z˷æ*$ ʞxٟ3 f Ս*I/Oy¾zY+m
_¨!w_7/#YɟwQwn\}x9@-EȉxL]!kiz5'P ObefI&^杆Kכ
P`=Bl˕ܬW'n|>?H/oUžڇjuFZڝ)}+\+|*>Ӹ~yog&'#\OO
endstream
endobj
407 0 obj
<<
/Type /ObjStm
/N 100
/First 874
/Length 1667
/Filter /FlateDecode
>>
stream
xYn[7+l79/
ТEZ# ǖ[Zv{Zqe[HH.9:;sAZ $HU0O2e<` T|*AkS!d V|^Bg
lXf̉Ccbd>!SUCfnɕC,jO_uîB,TC6W
c/*X | a&/H;5n@9%%'lŰ 6ADR ųbaɁ%!. 3aZ*%ءKCi00kbᆭr-fGpj2X3QixKT %x%;|">hvlH$78_̝
_˝!Rqa 9S
$k)p,U
#%u U)\$qbP]bA3>
V KTEG;.ۅKʠSOKvu %WN%]ZGذg+`{v`% ɮA R0s6
XW}c3 d
{a)2Hdž]=y2wƻGƯk 8D8A ȇP&Xol~zr Ջ0~3x zt ~ϱdv@k{p"y<9 < 6ȱw K Η +Uh0i:k4~6?;
;w /0qݘ%b!<5+t0af gq0K5O~WimK) FrىE$*WXL}092,}`; Y>zz(~d\Bf(m
t-xZ6x!0] 4Vb3]2ؕJj(-i|.gn)qb
u` #SU V vNiHY Lʱ{TiXd!X6[ DQV_cKGvg4ƽC(ϣ! {Cr `V,%ʺʹ^ #`SA1l}`t fH}`6:WRW>0Nduްo zוuW^ PCu`%E ,-N0 gX#[ H4&oXH
-[N'-|mI5u
Ã
QkTm'kJq83Po2G~
lq:9 O'G[Y_Pѯe4jPR>%gwt# L-Nu8\b5/~#XuG
)ԟ.Xt8$:O+f(ZtC >Ndo<&VuUU!1V= [$6NpZ'X%fi >{m ؏ʥûϵ*ZTjj-i7h$FÏrrD<ĸ{*G*m qu .0l`$ڑ-V7ސmy")6`
RAJÇ&|+ɛ/t;/? h˄
x~14ݺDR͖:]pr ,
~> k+ ry 綒4=
endstream
endobj
516 0 obj
<<
/Length 1308
/Filter /FlateDecode
>>
stream
xڵXMo8W ,% & Am^"Pd\n ,يͶR?y3 MO\3($|2$F`>4~{sIo$"$u1ߧD: ڎ`|mb 1%4|||'<3oNJ6$`D bMY .>M;nkm3*pwHu 5L* sN#NO]U5YY 3#r/X`%έD1gtb ٔ
2I60>R)=AqP `jW 3f J HS;j];,Vy3NhX+ ]5rvɊ<ό0.AJxvJ'2I\#{.ͳ@~PC讝
$7!1麛v}VKyl jf@cdԪ:YQ_Y[` \ރ5f o)j닦Ooha#<^i{!wM >xq#+i݂vW/Z( F0 mN|k@'b
endstream
endobj
512 0 obj
<<
/Type /ObjStm
/N 100
/First 879
/Length 2141
/Filter /FlateDecode
>>
stream
xZ]o\
}_E#R"%Z`a[#3ughw}iױ=ur>$ҽ{DQ!%YJO%I K'*?rϒxt