# vctrs v0.0.0.9000

0

0th

Percentile

## Vector Helpers

Functions that help you work with vectors, particularly numeric. Provides a full set of summary, cumulative, rolling, and vectorised functions for both R and C.

# vctrs

There are three main goals to the vctrs package, each described in a vignette:

• To propose vec_size() and vec_type() as alternatives to length() and class(); vignette("type-size"). These definitions are paired with a framework for type-coercion and size-recycling.

• To define type- and size-stability as desirable function properties, use them to analyse existing base function, 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 focused 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

vctrs is not currently on CRAN. Install the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("r-lib/vctrs")


## Usage

library(vctrs)

# Prototypes
str(vec_type_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 # 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


## Motivation

The original motivation for vctrs from two separate, but related problems. The first problem is that base::c() has rather undesirable behaviour when you mix different S3 vectors:

# combining factors makes integers
c(factor("a"), factor("b"))
#> [1] 1 1

# combing dates and date-times give incorrect values
dt <- as.Date("2020-01-1")
dttm <- as.POSIXct(dt)

c(dt, dttm)
#> [1] "2020-01-01"    "4321940-06-07"
c(dttm, dt)
#> [1] "2019-12-31 18:00:00 CST" "1969-12-31 23:04:22 CST"


This behaviour arises because c() has dual purposes: as well as it’s 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.

## Functions in vctrs

 Name Description vec_coerce Coerce vectors to common type list_of list_of S3 class for homogenous lists dims Vector dimensions vec_ptype Find the prototype of a set of vectors vec_recycle Vector recycling unknown A vector of unknown type vctrs-conditions Custom conditions for vctrs package vec_shape Compute and alter "shape" of a vector vec_type2 Find the common type for a pair of vector types vec_c Combine many vectors into one vector vec_type_string Vector type as a string vec_cast Cast a vector to specified type vec_list_cast Cast a list to vector of specific type vctrs-package vctrs: Vector Helpers vec_bind Combine many data frames into one data frame new_vctr vctr (vector) S3 class vec_grp vctr group generics vec_data Extract underlying data vec_ptype_full Vector type as a string new_record record S3 class fields Tools for accessing the fields of a record. vec_proxy Equality and ordering proxies vec_duplicate Find duplicated values vec_unique Find and count unique values vec_count Count unique values in a vector new_rcrd rcrd (record) S3 class vec_match Find matching observations across vectors vec_method_register Register a method for a suggested dependency %0% Default value for empty vectors vec_proxy_compare Comparison proxy vec_compare Compare two vectors vec_proxy_numeric Numeric proxy vec_equal Test if two vectors are equal vec_proxy_equal Equality proxy vec_proxy_logical Logical proxy vec_arith Arithmetic operations %<-% Destructuring assignment new_list_of Create list_of subclass vec_math Mathematical operations vec_print print() andstr() generics. partial_frame Partially specify columns of a data frame new_partial Partial type new_factor Factor/ordered factor S3 class new_date Date, date-time, and duration S3 classes vec_type2.data.frame Find the common type for a pair of vector types unspecified A 1d vector of unspecified type new_data_frame Data frame class vec_type2.tbl_df Find the common type for a pair of vector types vec_obs Number of observations vec_slice Get or set observations in a vector obj_print print() and str() generics. vec_size Number of observations s3_register Register a method for a suggested dependency vec_na Create a missing vector vec_type Find the prototype of a set of vectors vec_assert Assert an argument has known prototype and/or size No Results!

## Vignettes of vctrs

 Name arithmetic.Rmd base-classes.Rmd double-dispatch.Rmd extending-vctrs.Rmd function-types.Rmd proxies.Rmd s3-base.Rmd s3-proxy.Rmd s3-vector.Rmd size.Rmd stability.Rmd theory.Rmd type-size.Rmd type.Rmd vctrs-vs-base.Rmd No Results!