# vctrs v0.1.0

0

0th

Percentile

## Vector Helpers

Defines new notions of prototype and size that are used to provide tools for consistent and well-founded type-coercion and size-recycling, and are in turn connected to ideas of type- and size-stability useful for analyzing function interfaces.

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

## Details

 License GPL-3 URL https://github.com/r-lib/vctrs BugReports https://github.com/r-lib/vctrs/issues VignetteBuilder knitr Encoding UTF-8 Language en-GB LazyData true RoxygenNote 6.1.1 NeedsCompilation yes Packaged 2018-11-19 14:40:32 UTC; hadley Repository CRAN Date/Publication 2018-11-29 17:10:03 UTC
 imports backports , digest , glue , rlang , zeallot suggests covr , generics , knitr , pillar , pkgdown , rmarkdown , testthat , tibble depends R (>= 3.1) Contributors RStudio