vctrs

https://vctrs.r-lib.org/
Admin
vctrs is a developer-focused R package that provides a framework for creating new S3 vectors,...
Tokens:165,692
Snippets:1,531
Trust Score:8.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example Usage

Source: https://vctrs.r-lib.org/reference/vec_slice.html

Demonstrates how to use `vec_slice()` and `vec_assign()` for getting and setting vector elements, including examples with higher-dimensional objects and type stability.

```APIDOC
## Examples

__```
x <- sample(10)
vec_slice(x, 1:3)
#> [1] 6 5 7

# Assign with infix variant:
vec_slice(x, 2) <- 100

# Assign with regular variant (does not modify original):
y <- vec_assign(x, 3, 500)

# Slicing higher dimension objects:
vec_slice(mtcars, 1:3)

# Type stability example:
x <- 1:5
vec_slice(x, 2) <- 20.0
vec_ptype(x)
#> integer(0)

# Compare to base R [<-:
x[2] <- 20.0
vec_ptype(x)
#> numeric(0)
```__
```

--------------------------------

### Install vctrs Development Version

Source: https://vctrs.r-lib.org/index.html

Install the latest development version of vctrs using the pak package.

```r
# install.packages("pak")
pak::pak("r-lib/vctrs")
```

--------------------------------

### Example of vec_proxy_equal with rational vectors

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Demonstrates how vec_proxy_equal simplifies fractions for comparison, showing that 2/4 is equal to 1/2.

```R
vec_proxy_equal(x)
#>   n d
#> 1 1 1
#> 2 2 1
#> 3 1 2
#> 4 1 1

x == rational(1, 1)
#> [1]  TRUE FALSE FALSE  TRUE
```

--------------------------------

### vec_c() examples

Source: https://vctrs.r-lib.org/reference/vec_c.html

Illustrative examples of using vec_c() with different data types, including numeric, date/time, and factors, and demonstrating name specification for handling named inputs.

```APIDOC
## Examples

__```
vec_c(FALSE, 1L, 1.5)
#> [1] 0.0 1.0 1.5

# Date/times --------------------------
c(Sys.Date(), Sys.time())
#> [1] "2026-04-17" "2026-04-17"
c(Sys.time(), Sys.Date())
#> [1] "2026-04-17 13:54:04 UTC" "2026-04-17 00:00:00 UTC"

vec_c(Sys.Date(), Sys.time())
#> [1] "2026-04-17 00:00:00 UTC" "2026-04-17 13:54:04 UTC"
vec_c(Sys.time(), Sys.Date())
#> [1] "2026-04-17 13:54:04 UTC" "2026-04-17 00:00:00 UTC"

# Factors -----------------------------
c(factor("a"), factor("b"))
#> [1] a b
#> Levels: a b
vec_c(factor("a"), factor("b"))
#> [1] a b
#> Levels: a b


# By default, named inputs must be length 1:
vec_c(name = 1)
#> name 
#>    1 
try(vec_c(name = 1:3))
#> Error in vec_c(name = 1:3) : 
#>   Can't merge the outer name `name` with a vector of length > 1.
#> Please supply a `.name_spec` specification.

# Pass a name specification to work around this:
vec_c(name = 1:3, .name_spec = "{outer}_{inner}")
#> name_1 name_2 name_3 
#>      1      2      3 

# See `?name_spec` for more examples of name specifications.

```
```

--------------------------------

### Examples of vec_cast()

Source: https://vctrs.r-lib.org/reference/vec_cast.html

Demonstrates various use cases and error handling for vec_cast().

```APIDOC
## Examples

```R
# x is a double, but no information is lost
vec_cast(1, integer())
#> [1] 1

# When information is lost the cast fails
try(vec_cast(c(1, 1.5), integer()))
#> Error in eval(expr, envir) : 
#>   Can't convert from `c(1, 1.5)` <double> to <integer> due to loss of precision.
#> • Locations: 2
try(vec_cast(c(1, 2), logical()))
#> Error in eval(expr, envir) : 
#>   Can't convert from `c(1, 2)` <double> to <logical> due to loss of precision.
#> • Locations: 2

# You can suppress this error and get the partial results
allow_lossy_cast(vec_cast(c(1, 1.5), integer()))
#> [1] 1 1
allow_lossy_cast(vec_cast(c(1, 2), logical()))
#> [1] TRUE TRUE

# By default this suppress all lossy cast errors without
# distinction, but you can be specific about what cast is allowed
# by supplying prototypes
allow_lossy_cast(vec_cast(c(1, 1.5), integer()), to_ptype = integer())
#> [1] 1 1
try(allow_lossy_cast(vec_cast(c(1, 2), logical()), to_ptype = integer()))
#> Error in eval(expr, envir) : 
#>   Can't convert from `c(1, 2)` <double> to <logical> due to loss of precision.
#> • Locations: 2

# No sensible coercion is possible so an error is generated
try(vec_cast(1.5, factor("a")))
#> Error in eval(expr, envir) : 
#>   Can't convert `1.5` <double> to <factor<4d52a>>.

# Cast to common type
vec_cast_common(factor("a"), factor(c("a", "b")))
#> [[1]]
#> [1] a
#> Levels: a b
#> 
#> [[2]]
#> [1] a b
#> Levels: a b
#> 
```
```

--------------------------------

### Install vctrs from CRAN

Source: https://vctrs.r-lib.org/index.html

Use this command to install the stable version of the vctrs package from CRAN.

```r
install.packages("vctrs")
```

--------------------------------

### vec_as_names() Examples

Source: https://vctrs.r-lib.org/reference/vec_as_names.html

Demonstrates how `vec_as_names()` works with different repair options.

```APIDOC
## `vec_as_names()` Examples

By default, `vec_as_names()` returns minimal names:
```R
vec_as_names(c(NA, NA, "foo"))
#> [1] ""    ""    "foo"
```

You can make them unique:
```R
vec_as_names(c(NA, NA, "foo"), repair = "unique")
#> New names:
#> • `` -> `...1`
#> • `` -> `...2`
#> [1] "...1" "...2" "foo"
```

Universal repairing fixes any non-syntactic name:
```R
vec_as_names(c("_foo", "+"), repair = "universal")
#> New names:
#> • `_foo` -> `._foo`
#> • `+` -> `.`
#> [1] "._foo" "."
```
```

--------------------------------

### Example of Record-Style Object (POSIXlt)

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Demonstrates the structure of a record-style object using `POSIXlt`. Shows how `length()` and subsetting methods can conceal the underlying list-based implementation.

```R
x <- as.POSIXlt(ISOdatetime(2020, 1, 1, 0, 0, 1:3))
x
#> [1] "2020-01-01 00:00:01 UTC" "2020-01-01 00:00:02 UTC"
#> [3] "2020-01-01 00:00:03 UTC"

length(x)
#> [1] 3
length(unclass(x))
#> [1] 11

x[[1]] # the first date time
#> [1] "2020-01-01 00:00:01 UTC"
unclass(x)[[1]] # the first component, the number of seconds
#> [1] 1 2 3
```

--------------------------------

### Example: Data Frame for Matches Algorithm

Source: https://vctrs.r-lib.org/reference/internal-faq-matches-algorithm.html

Demonstrates the structure of 'needles' and 'haystack' data frames used in the matches algorithm.

```R
needles
#>   x y
#> 1 1 1
#> 2 1 2
#> 3 2 3
#> 4 2 4
#> 5 2 5
#> 6 3 3

haystack
#>   x y
#> 1 1 2
#> 2 1 3
#> 3 2 4
#> 4 2 4
#> 5 3 1
```

--------------------------------

### Example: Initializing Haystack Locations

Source: https://vctrs.r-lib.org/reference/internal-faq-matches-algorithm.html

Initializes lower and upper match locations for the haystack. Used when no needle values are present.

```R
loc_lower_match_haystack <- 3L
loc_upper_match_haystack <- 2L
```

--------------------------------

### Example of polynomial vector creation and display

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Constructs a polynomial vector and displays its formatted output, showing coefficients and powers.

```R
p <- poly(1, c(1, 0, 0, 0, 2), c(1, 0, 1))
p
#> <polynomial[3]>
#> [1] 1         1⋅x^4 + 2 1⋅x^2 + 1
```

--------------------------------

### Example of vec_proxy_compare with rational vectors

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Demonstrates how converting to floating-point numbers fixes comparison issues, ensuring 2/4 is correctly compared to 2/3.

```R
rational(2, 4) < rational(2, 3)
#> [1] TRUE
```

--------------------------------

### Example usage of decimal2 constructor

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Demonstrates creating a `vctrs_decimal2` vector with different values for the right-hand side of the decimal, showing how the `scale` attribute affects the output.

```R
decimal2(10, c(0, 5, 99))
```

--------------------------------

### Parallel any() and all() Usage

Source: https://vctrs.r-lib.org/reference/parallel-operators.html

Shows the basic usage of vec_pany() and vec_pall() with example vectors, demonstrating default behavior with missing values and comparison to base R operators.

```R
a <- c(TRUE, TRUE, TRUE, FALSE, FALSE, FALSE, NA, NA, NA)
b <- c(TRUE, FALSE, NA, TRUE, FALSE, NA, TRUE, FALSE, NA)

# Default behavior treats missings like `|` does
vec_pany(a, b)
#> [1]  TRUE  TRUE  TRUE  TRUE FALSE    NA  TRUE    NA    NA
a | b
#> [1]  TRUE  TRUE  TRUE  TRUE FALSE    NA  TRUE    NA    NA

# Default behavior treats missings like `&` does
vec_pall(a, b)
#> [1]  TRUE FALSE    NA FALSE FALSE FALSE    NA FALSE    NA
a & b
#> [1]  TRUE FALSE    NA FALSE FALSE FALSE    NA FALSE    NA
```

--------------------------------

### Example: Calculating Midpoint for Needles (Second Instance)

Source: https://vctrs.r-lib.org/reference/internal-faq-matches-algorithm.html

Calculates the midpoint location for needles. This is a step in finding matches within a range.

```R
loc_mid_needles <- 6L
```

--------------------------------

### Example usage of vec_order_radix and vec_sort_radix

Source: https://vctrs.r-lib.org/reference/order-radix.html

Demonstrates the basic usage of `vec_order_radix()` and `vec_sort_radix()` with numeric vectors including NA values, and their application to data frames.

```r
x <- round(sample(runif(5), 9, replace = TRUE), 3)
x <- c(x, NA)

vec_order_radix(x)
vec_sort_radix(x)
vec_sort_radix(x, direction = "desc")

# Can also handle data frames
df <- data.frame(g = sample(2, 10, replace = TRUE), x = x)
vec_order_radix(df)
vec_sort_radix(df)
vec_sort_radix(df, direction = "desc")
```

--------------------------------

### Minimal names example

Source: https://vctrs.r-lib.org/reference/vec_as_names.html

Demonstrates how `vec_as_names()` ensures names are not NULL and uses empty strings for unnamed elements.

```r
Original names of a vector with length 3: NULL
                           minimal names: "" "" ""

                          Original names: "x" NA
                           minimal names: "x" ""
```

--------------------------------

### Example of maybe_lossy_cast with and without allowed lossy casts

Source: https://vctrs.r-lib.org/reference/vctrs-conditions.html

Demonstrates the behavior of `maybe_lossy_cast`. Normally, it returns the input. If `lossy` is TRUE, it throws an error unless `allow_lossy_cast()` is used.

```R
# Most of the time, `maybe_lossy_cast()` returns its input normally:
maybe_lossy_cast(
  c("foo", "bar"),
  NA,
  "",
  lossy = c(FALSE, FALSE),
  x_arg = "",
  to_arg = ""
)
#> [1] "foo" "bar"

# If `lossy` has any `TRUE`, an error is thrown:
try(maybe_lossy_cast(
  c("foo", "bar"),
  NA,
  "",
  lossy = c(FALSE, TRUE),
  x_arg = "",
  to_arg = ""
))
#> Error in eval(expr, envir) : 
#>   Can't convert from <logical> to <character> due to loss of precision.
#> • Locations: 2

# Unless lossy casts are allowed:
allow_lossy_cast(
  maybe_lossy_cast(
    c("foo", "bar"),
    NA,
    "",
    lossy = c(FALSE, TRUE),
    x_arg = "",
    to_arg = ""
  )
)
#> [1] "foo" "bar"



```

--------------------------------

### Display vctrs_percent vector

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Example output of a vctrs_percent vector after implementing the format() method, showing how it is printed.

```R
x
#> <vctrs_percent[5]>
#> [1] 0%    33.3% 66.7% 100%  <NA>
```

--------------------------------

### User-Friendly Constructor for Rational Vector

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Creates a user-friendly constructor `rational` that casts and recycles inputs before calling the low-level constructor. Example usage provided.

```R
rational <- function(n = integer(), d = integer()) {
  c(n, d) %<-% vec_cast_common(n, d, .to = integer())
  c(n, d) %<-% vec_recycle_common(n, d)

  new_rational(n, d)
}

x <- rational(1, 1:10)
```

--------------------------------

### Delayed Method Registration Example

Source: https://vctrs.r-lib.org/reference/s3_register.html

For R 3.6.0 and later, delayed method registration can be achieved by placing this directive in your NAMESPACE file.

```R
if (getRversion() >= "3.6.0") {
  S3method(package::generic, class)
}
```

--------------------------------

### Common Type Combination Example

Source: https://vctrs.r-lib.org/reference/faq-compatibility-types.html

Shows how integer and logical vectors are combined into a common integer type when binding rows of data frames.

```R
df1 <- data.frame(x = 1:3)
df2 <- data.frame(x = FALSE)
dplyr::bind_rows(df1, df2)
```

--------------------------------

### Creating Totally Ordered Haystack Containers

Source: https://vctrs.r-lib.org/reference/internal-faq-matches-algorithm.html

Demonstrates how to partition a 'haystack' into containers where values within each container are totally ordered, enabling correct matching.

```R
haystack[1:4,]
#> # A tibble: 4 × 2
#>       x     y
#>   <dbl> <dbl>
#> 1     1     2
#> 2     1     3
#> 3     2     4
#> 4     2     4

haystack[5,]
#> # A tibble: 1 × 2
#>       x     y
#>   <dbl> <dbl>
#> 1     3     1
```

--------------------------------

### Identify runs in a vector

Source: https://vctrs.r-lib.org/reference/runs.html

Use `vec_identify_runs()` to get identifiers for elements that start a new run of repeated values. Adjacent missing values are treated as identical.

```r
x <- c("a", "z", "z", "c", "a", "a")

vec_identify_runs(x)
#> [1] 1 2 2 3 4 4
#> attr(,"n")
#> [1] 4
```

--------------------------------

### Universal Names Transformation Examples

Source: https://vctrs.r-lib.org/reference/vec_as_names.html

Illustrates the conversion of original vector names into 'universal' names, which are syntactic and unique. This transformation ensures names can be directly used in code.

```R
 Original names:     ""     "x"    NA      "x"
universal names: "...1" "x...2" "...3" "x...4"

  Original names: "(y)"  "_z"  ".2fa"  "FALSE"
 universal names: ".y." "._z" ".2fa" ".FALSE"
```

--------------------------------

### Demonstrate list_of() with .ptype and .size

Source: https://vctrs.r-lib.org/news/index.html

Shows how to use the `.ptype` and `.size` arguments in `list_of()` to control element type and size restrictions.

```R
# Restricts the element type, but not the size (default behavior)
list_of(1:2, 3:4, .ptype = integer(), .size = zap())

# Restricts the element size, but not the type
list_of(1:2, 3:4, .ptype = zap(), .size = 2)

# Restricts the element type and size
list_of(1:2, 3:4, .ptype = integer(), .size = 2)
```

--------------------------------

### Get Number of Fields in a Record

Source: https://vctrs.r-lib.org/reference/fields.html

Use `n_fields()` to get the number of fields in a record, similar to `length()` for vectors.

```R
x <- new_rcrd(list(x = 1:3, y = 3:1, z = letters[1:3]))
n_fields(x)
#> [1] 3
```

--------------------------------

### Get unspecified prototype

Source: https://vctrs.r-lib.org/reference/vctrs-unspecified.html

Use `vec_ptype()` to get the prototype of `NA` or `c(NA, NA)`, which results in an `<unspecified>` type.

```r
vec_ptype(NA)
#> <unspecified> [0]
vec_ptype(c(NA, NA))
#> <unspecified> [0]
```

--------------------------------

### Use usethis to add packages to DESCRIPTION

Source: https://vctrs.r-lib.org/articles/pillar.html

Use the usethis package to programmatically add 'vctrs' and 'pillar' to your package's DESCRIPTION file.

```r
usethis::use_package("vctrs")
usethis::use_package("pillar")
```

--------------------------------

### Get sizes of runs in a vector

Source: https://vctrs.r-lib.org/reference/runs.html

Use `vec_run_sizes()` to get the size of each run of repeated values. This is faster than `vec_unrep()` if only sizes are needed.

```r
x <- c("a", "z", "z", "c", "a", "a")

vec_run_sizes(x)
#> [1] 1 2 1 2
```

--------------------------------

### Algorithm Walkthrough for Multi-Column Data Frames

Source: https://vctrs.r-lib.org/reference/internal-faq-matches-algorithm.html

This example demonstrates the recursive algorithm for `vec_locate_matches()` with multi-column data frames. It shows how bounds are refined through recursive calls for each column.

```R
# these are sorted already for simplicity
needles <- data_frame(x = c(1, 1, 2, 2, 2, 3), y = c(1, 2, 3, 4, 5, 3))
haystack <- data_frame(x = c(1, 1, 2, 2, 3), y = c(2, 3, 4, 4, 1))

needles
#>   x y
#> 1 1 1
#> 2 1 2
#> 3 2 3
#> 4 2 4
#> 5 2 5
#> 6 3 3

haystack
#>   x y
#> 1 1 2
#> 2 1 3
#> 3 2 4
#> 4 2 4
#> 5 3 1

## Column 1, iteration 1

# start at midpoint in needles
# this corresponds to x==2
loc_mid_needles <- 3L

# finding all x==2 values in needles gives us:
loc_lower_duplicate_needles <- 3L
loc_upper_duplicate_needles <- 5L

# finding matches in haystack give us:
loc_lower_match_haystack <- 3L
loc_upper_match_haystack <- 4L

# compute LHS/RHS bounds for next needle
lhs_loc_lower_bound_needles <- 1L # original lower bound
lhs_loc_upper_bound_needles <- 2L # lower_duplicate-1

rhs_loc_lower_bound_needles <- 6L # upper_duplicate+1
rhs_loc_upper_bound_needles <- 6L # original upper bound

# We still have a 2nd column to check. So recurse and pass on the current
# duplicate and match bounds to start the 2nd column with.

## Column 2, iteration 1

# midpoint of [3, 5]
# value y==4
loc_mid_needles <- 4L

loc_lower_duplicate_needles <- 4L
loc_upper_duplicate_needles <- 4L

loc_lower_match_haystack <- 3L
loc_upper_match_haystack <- 4L

# last column, so record matches
# - this was location 4 in needles
# - lower match in haystack is at loc 3
# - match size is 2

# Now handle LHS and RHS of needle midpoint
lhs_loc_lower_bound_needles <- 3L # original lower bound
lhs_loc_upper_bound_needles <- 3L # lower_duplicate-1

rhs_loc_lower_bound_needles <- 5L # upper_duplicate+1
rhs_loc_upper_bound_needles <- 5L # original upper bound

## Column 2, iteration 2 (using LHS bounds)

# midpoint of [3,3]
# value of y==3
loc_mid_needles <- 3L

loc_lower_duplicate_needles <- 3L
loc_upper_duplicate_needles <- 3L

# no match! no y==3 in haystack for x==2

```

--------------------------------

### Get repaired names with vec_names2()

Source: https://vctrs.r-lib.org/reference/vec_names.html

Use `vec_names2()` to get the repaired names from a vector, even if it is unnamed. It handles name repair according to specified strategies.

```r
vec_names2(1:3)
#> [1] "" "" ""
vec_names2(1:3, repair = "unique")
#> New names:
#> • `` -> `...1`
#> • `` -> `...2`
#> • `` -> `...3`
#> [1] "...1" "...2" "...3"
vec_names2(c(a = 1, b = 2))
#> [1] "a" "b"
```

--------------------------------

### Get sizes of runs in a data frame

Source: https://vctrs.r-lib.org/reference/runs.html

Use `vec_run_sizes()` to get the size of each run when applied rowwise to a data frame. This is faster than `vec_unrep()` if only sizes are needed.

```r
x <- c("a", "z", "z", "c", "a", "a")
y <- c(1, 1, 1, 2, 2, 3)

# With multiple columns, the runs are constructed rowwise
df <- data_frame(
  x = x,
  y = y
)

vec_run_sizes(df)
#> [1] 1 2 1 1 1
```

--------------------------------

### Name Specification Examples

Source: https://vctrs.r-lib.org/reference/name_spec.html

Demonstrates various ways to use name specifications with `vec_c()`, including glue strings, functions, purrr-style formulas, the 'inner' keyword, and `rlang::zap()`.

```APIDOC
## Examples
__```
# By default, named inputs must be length 1:
vec_c(name = 1)         # ok
#> name 
#>    1 
try(vec_c(name = 1:3))  # bad
#> Error in vec_c(name = 1:3) : 
#>   Can't merge the outer name `name` with a vector of length > 1.
#> Please supply a `.name_spec` specification.

# They also can't have internal names, even if scalar:
try(vec_c(name = c(internal = 1)))  # bad
#> Error in vec_c(name = c(internal = 1)) : 
#>   Can't merge the outer name `name` with a named vector.
#> Please supply a `.name_spec` specification.

# Pass a name specification to work around this. A specification
# can be a glue string referring to `outer` and `inner`:
vec_c(name = 1:3, other = 4:5, .name_spec = "{outer}")
#>  name  name  name other other 
#>     1     2     3     4     5 
vec_c(name = 1:3, other = 4:5, .name_spec = "{outer}_{inner}")
#>  name_1  name_2  name_3 other_1 other_2 
#>       1       2       3       4       5 

# They can also be functions:
my_spec <- function(outer, inner) paste(outer, inner, sep = "_")
vec_c(name = 1:3, other = 4:5, .name_spec = my_spec)
#>  name_1  name_2  name_3 other_1 other_2 
#>       1       2       3       4       5 

# Or purrr-style formulas for anonymous functions:
vec_c(name = 1:3, other = 4:5, .name_spec = ~ paste0(.x, .y))
#>  name1  name2  name3 other1 other2 
#>      1      2      3      4      5 

# Or the string "inner" to only use inner names
vec_c(name = 1:3, outer = 4:5, .name_spec = "inner")
#> [1] 1 2 3 4 5
vec_c(name = c(a = 1, b = 2, c = 3), outer = 4:5, .name_spec = "inner")
#> a b c     
#> 1 2 3 4 5 
# This can be useful when you want outer names mentioned in error messages,
# but you don't want them interfering with the result
try(vec_c(x = c(a = 1), y = c(b = "2"), .name_spec = "inner"))
#> Error in vec_c(x = c(a = 1), y = c(b = "2"), .name_spec = "inner") : 
#>   Can't combine `x` <double> and `y` <character>.

# Or `rlang::zap()` to ignore both outer and inner names entirely
vec_c(name = c(a = 1, b = 2), outer = c(c = 3), .name_spec = rlang::zap())
#> [1] 1 2 3

```
```

--------------------------------

### Create sequences with vec_seq_along() and vec_init_along()

Source: https://vctrs.r-lib.org/news/index.html

vec_seq_along() and vec_init_along() create useful sequences based on vector length.

```R
# Example usage for vec_seq_along() and vec_init_along() would go here, but is not provided in the source.
```

--------------------------------

### Get Unfinalised Prototype

Source: https://vctrs.r-lib.org/reference/vec_ptype.html

Use `vec_ptype()` to get an unfinalised prototype, which can be coerced to any other type. `vec_ptype2()` also returns unfinalised prototypes when combining two unfinalised types.

```R
vec_ptype(NA)
#> <unspecified> [0]
```

```R
vec_ptype2(NA, NA)
#> <unspecified> [0]
```

--------------------------------

### Instantiate 'my_natural' class

Source: https://vctrs.r-lib.org/reference/howto-faq-coercion.html

Demonstrates creating instances of the 'my_natural' class with integers and with NA values.

```R
new_natural(1:3)
#> <natural>
#> [1] 1 2 3
new_natural(c(1, NA))
#> <natural>
#> [1]  1 NA
```

--------------------------------

### Get Vector Size

Source: https://vctrs.r-lib.org/reference/vec_size.html

Use `vec_size()` to get the number of observations (rows) of a vector. It is equivalent to `NROW()` but errors on non-vector inputs. The size of `NULL` is hard-coded to 0.

```r
vec_size(1:100)
#> [1] 100
vec_size(mtcars)
#> [1] 32
vec_size(array(dim = c(3, 5, 10)))
#> [1] 3
```

--------------------------------

### Create and inspect a Percent vector

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Demonstrates creating a 'vctrs_percent' vector with some values and NA, then inspecting its structure.

```r
x <- new_percent(c(seq(0, 1, length.out = 4), NA))
x
#> <vctrs_percent[5]>
#> [1] 0.0000000 0.3333333 0.6666667 1.0000000        NA

str(x)
#>  vctrs_pr [1:5] 0.0000000, 0.3333333, 0.6666667, 1.0000000,        NA
```

--------------------------------

### Get Group IDs for a Vector

Source: https://vctrs.r-lib.org/reference/vec_group.html

Use `vec_group_id()` to get an integer vector where each element indicates the group ID it belongs to. The total number of unique groups is returned as an attribute named 'n'.

```r
purrr <- c("p", "u", "r", "r", "r")
vec_group_id(purrr)
#> [1] 1 2 3 3 3
#> attr(,"n")
#> [1] 3
```

```r
groups <- mtcars[c("vs", "am")]
vec_group_id(groups)
#>  [1] 1 1 2 3 4 3 4 3 3 3 3 4 4 4 4 4 4 2 2 2 3 4 4 4 4 2 1 2 1 1 1 2
#> attr(,"n")
#> [1] 4
```

```r
# `vec_group_id()` is equivalent to
vec_match(groups, vec_unique(groups))
```

--------------------------------

### vec_size()

Source: https://vctrs.r-lib.org/reference/index.html

Get the number of observations (size) of a vector. This is equivalent to `length()` for most vectors.

```APIDOC
## vec_size()

### Description
Number of observations.

### Method
`vec_size(x, ...)`

### Parameters
* `x` (vector) - The vector to get the size of.
* `...` - Additional arguments.

### Response
* Returns the size (number of observations) of the vector.
```

--------------------------------

### list_of_size()

Source: https://vctrs.r-lib.org/reference/index.html

Get the size of a `vctrs_list_of` object. This function returns the number of elements in the list.

```APIDOC
## list_of_size()

### Description
`list_of` attributes.

### Method
`list_of_size(x, ...)`

### Parameters
* `x` (`vctrs_list_of`) - The list of homogenous vectors.
* `...` - Additional arguments.

### Response
* Returns the size of the `vctrs_list_of` object.
```

--------------------------------

### vec_slice()

Source: https://vctrs.r-lib.org/reference/index.html

Get observations from a vector based on indices. This function allows you to subset a vector.

```APIDOC
## vec_slice()

### Description
Get observations in a vector.

### Method
`vec_slice(x, i, ...)`

### Parameters
* `x` (vector) - The vector to slice.
* `i` (integer or logical) - The indices to select.
* `...` - Additional arguments.

### Response
* Returns a subset of the vector `x`.
```

--------------------------------

### vec_seq_along()

Source: https://vctrs.r-lib.org/reference/index.html

Generate a sequence of integers from 1 to the length of a vector. This is a convenient way to get indices.

```APIDOC
## vec_seq_along()

### Description
Useful sequences.

### Method
`vec_seq_along(x, ...)`

### Parameters
* `x` (vector) - The vector to determine the sequence length from.
* `...` - Additional arguments.

### Response
* Returns an integer sequence from 1 to `length(x)`.
```

--------------------------------

### vec_order()

Source: https://vctrs.r-lib.org/reference/index.html

Get the order of elements in a vector. This function returns the indices that would sort the vector.

```APIDOC
## vec_order()

### Description
Order vectors.

### Method
`vec_order(x, ...)`

### Parameters
* `x` (vector) - The vector to order.
* `...` - Additional arguments.

### Response
* Returns an integer vector representing the order of elements.
```

--------------------------------

### list_sizes()

Source: https://vctrs.r-lib.org/reference/index.html

Get the sizes of all vectors within a list. This function returns a named list of sizes.

```APIDOC
## list_sizes()

### Description
Get the sizes of all vectors within a list.

### Method
`list_sizes(x, ...)`

### Parameters
* `x` (list) - The list containing vectors.
* `...` - Additional arguments.

### Response
* Returns a named list of the sizes of the vectors in `x`.
```

--------------------------------

### Basic arithmetic on 'meter' objects

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Demonstrates that basic aggregation functions like sum() and mean() work on the custom 'meter' class due to its double vector base.

```R
sum(x)
#> <vctrs_meter[1]>
#> [1] 55 m
mean(x)
#> <vctrs_meter[1]>
#> [1] 5.5 m
```

--------------------------------

### vec_proxy_equal()

Source: https://vctrs.r-lib.org/reference/index.html

Get a proxy for equality operations on vectors. Used for implementing custom equality logic.

```APIDOC
## vec_proxy_equal()

### Description
Equality proxy.

### Method
`vec_proxy_equal(x, ...)`

### Parameters
* `x` (vector) - The vector to get an equality proxy for.
* `...` - Additional arguments.

### Response
* Returns a proxy object for equality.
```

--------------------------------

### Create a User-Friendly Percent Constructor

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Defines a convenient `as_percent()` function that leverages `vec_cast()` for converting various types to a percent vector. This is useful when direct casting is desired.

```R
as_percent <- function(x) {
  vec_cast(x, new_percent())
}
```

--------------------------------

### vec_proxy_order()

Source: https://vctrs.r-lib.org/reference/index.html

Get a proxy for ordering operations on vectors. Used for implementing custom ordering logic.

```APIDOC
## vec_proxy_order()

### Description
Order proxy.

### Method
`vec_proxy_order(x, ...)`

### Parameters
* `x` (vector) - The vector to get an order proxy for.
* `...` - Additional arguments.

### Response
* Returns a proxy object for ordering.
```

--------------------------------

### Import vctrs Namespace and Add Dummy Documentation

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Use #' @import vctrs and dummy documentation for internal vctrs methods to avoid R CMD check warnings. This should be placed in package-level docs or a class-focused file.

```R
#' Internal vctrs methods
#'
#' @import vctrs
#' @keywords internal
#' @name pizza-vctrs
NULL
```

--------------------------------

### vec_proxy_compare()

Source: https://vctrs.r-lib.org/reference/index.html

Get a proxy for comparison operations on vectors. Used for implementing custom comparison logic.

```APIDOC
## vec_proxy_compare()

### Description
Comparison proxy.

### Method
`vec_proxy_compare(x, ...)`

### Parameters
* `x` (vector) - The vector to get a comparison proxy for.
* `...` - Additional arguments.

### Response
* Returns a proxy object for comparison.
```

--------------------------------

### vec_proxy()

Source: https://vctrs.r-lib.org/reference/index.html

Experimental function to get a proxy representation of a vector. This can be useful for custom vector types.

```APIDOC
## vec_proxy()

### Description
Experimental: Proxy and restore.

### Method
`vec_proxy(x, ...)`

### Parameters
* `x` (vector) - The vector to get a proxy for.
* `...` - Additional arguments.

### Response
* Returns a proxy representation of the vector.
```

--------------------------------

### Define print and subset methods for 'my_natural'

Source: https://vctrs.r-lib.org/reference/howto-faq-coercion.html

Implements S3 print and subset methods for the 'my_natural' class. The print method adds a custom prefix, and the subset method ensures the result is also a 'my_natural' class.

```R
print.my_natural <- function(x, ...) {
  cat("<natural>\n")
  x <- unclass(x)
  NextMethod()
}
`[.my_natural` <- function(x, i, ...) {
  new_natural(NextMethod())
}
```

--------------------------------

### list_of_ptype()

Source: https://vctrs.r-lib.org/reference/index.html

Get the prototype of a `vctrs_list_of` object. This function returns the type of the homogenous elements within the list.

```APIDOC
## list_of_ptype()

### Description
`list_of` attributes.

### Method
`list_of_ptype(x, ...)`

### Parameters
* `x` (`vctrs_list_of`) - The list of homogenous vectors.
* `...` - Additional arguments.

### Response
* Returns the prototype of the elements in the `vctrs_list_of` object.
```

--------------------------------

### Combine Unfinalised Prototypes with Default

Source: https://vctrs.r-lib.org/reference/vec_ptype.html

This example demonstrates a rare scenario where unfinalised prototypes are combined with a default value. An error occurs if the default is incompatible, but combining with `.finalise = FALSE` allows for successful type coercion.

```R
xs <- list(NA, NA)
default <- "a"
try(vec_ptype2(vec_ptype_common(!!!xs), default))
#> Error in eval(expr, envir) :
#>   Can't combine `vec_ptype_common(!!!xs)` <logical> and `default` <character>.
vec_ptype2(vec_ptype_common(!!!xs, .finalise = FALSE), default)
#> character(0)
```

--------------------------------

### vec_run_sizes()

Source: https://vctrs.r-lib.org/reference/index.html

Get the sizes of consecutive runs of identical values in a vector. This function returns a vector of run lengths.

```APIDOC
## vec_run_sizes()

### Description
Runs.

### Method
`vec_run_sizes(x, ...)`

### Parameters
* `x` (vector) - The vector to get run sizes from.
* `...` - Additional arguments.

### Response
* Returns a vector of sizes for consecutive runs of identical values.
```

--------------------------------

### Get Field Names of a Record

Source: https://vctrs.r-lib.org/reference/fields.html

Use `fields()` to retrieve the names of the fields in a record, analogous to `names()` for lists.

```R
fields(x)
#> [1] "x" "y" "z"
```

--------------------------------

### Implement Generic as_percent with Default and Character Methods

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Provides a generic `as_percent()` function with a default method for casting and a specific method for character vectors, allowing for more flexible conversion by parsing strings.

```R
as_percent <- function(x, ...) {
  UseMethod("as_percent")
}

as_percent.default <- function(x, ...) {
  vec_cast(x, new_percent())
}

as_percent.character <- function(x) {
  value <- as.numeric(gsub(" *% *$", "", x)) / 100
  new_percent(value)
}
```

--------------------------------

### Load vctrs and pillar packages

Source: https://vctrs.r-lib.org/articles/pillar.html

Load the necessary packages for vector manipulation and custom printing.

```r
library(vctrs)
library(pillar)
```

--------------------------------

### Example: Calculating Midpoint for Needles

Source: https://vctrs.r-lib.org/reference/internal-faq-matches-algorithm.html

Calculates the midpoint location for needles. This is a step in finding matches within a range.

```R
loc_mid_needles <- 1L
```

--------------------------------

### vec_init_along()

Source: https://vctrs.r-lib.org/reference/index.html

Initialize a vector of the same size as another vector. This is useful for creating placeholder vectors.

```APIDOC
## vec_init_along()

### Description
Useful sequences.

### Method
`vec_init_along(x, ..., ptype = NULL)`

### Parameters
* `x` (vector) - The vector to determine the size from.
* `...` - Additional arguments.
* `ptype` (vector) - The prototype for the new vector.

### Response
* Returns an initialized vector of the same size as `x`.
```

--------------------------------

### Get Common Finalised Prototype

Source: https://vctrs.r-lib.org/reference/vec_ptype.html

By default, `vec_ptype_common()` returns a finalised prototype, suitable for direct use in other vctrs functions.

```R
vec_ptype_common(NA, NA)
#> logical(0)
```

--------------------------------

### Create list columns

Source: https://vctrs.r-lib.org/reference/data_frame.html

Illustrates the creation of list columns within a data frame. For optimal display, converting to a tibble is recommended.

```r
# List columns can be easily created
df <- data_frame(x = list(1:2, 2, 3:4), y = 3:1)

# However, the base print method is suboptimal for displaying them,
# so it is recommended to convert them to tibble
if (rlang::is_installed("tibble")) {
  tibble::as_tibble(df)
}
#> # A tibble: 3 × 2
#>   x             y
#>   <list>    <int>
#> 1 <int [2]>     3
#> 2 <dbl [1]>     2
#> 3 <int [2]>     1
```

--------------------------------

### Get Size of list_of

Source: https://vctrs.r-lib.org/reference/list-of-attributes.html

Use `list_of_size()` to retrieve the size of a `list_of` vector. Returns `NULL` if no specific size is required.

```r
x <- list_of(1, 2)
list_of_size(x)
#> NULL

x <- list_of(.ptype = integer(), .size = 5)
list_of_size(x)
#> [1] 5
```

--------------------------------

### Example: Calculating Match Bounds for Second Column with '<='

Source: https://vctrs.r-lib.org/reference/internal-faq-matches-algorithm.html

Calculates match bounds for the second column ('y') with a '<=' condition, demonstrating a case where the automatic bound extension rule might fail.

```R
# needles range of [3, 5]
# y == 4
loc_mid_needles <- 4L

loc_lower_duplicate_needles <- 4L
loc_upper_duplicate_needles <- 4L

# finding exact matches in haystack give us:
loc_lower_match_haystack <- 3L
loc_upper_match_haystack <- 4L

# lets try using our rule, which tells us we should be able to extend the upper
# bound:
loc_lower_match_haystack <- 3L
loc_upper_match_haystack <- 5L

# but the haystack value of y at location 5 is y==1, which is not less than y==4
```

--------------------------------

### vec_init()

Source: https://vctrs.r-lib.org/reference/index.html

Initialize a vector. This function creates a vector of a specified size and type, often filled with default values.

```APIDOC
## vec_init()

### Description
Initialize a vector.

### Method
`vec_init(x, size, ...)`

### Parameters
* `x` (vector) - The prototype vector to initialize from.
* `size` (integer) - The desired size of the new vector.
* `...` - Additional arguments.

### Response
* Returns a new vector of the specified size and type.
```

--------------------------------

### Get Prototype of list_of

Source: https://vctrs.r-lib.org/reference/list-of-attributes.html

Use `list_of_ptype()` to retrieve the prototype of a `list_of` vector. Returns `NULL` if no specific prototype is required.

```r
x <- list_of(1, 2)
list_of_ptype(x)
#> numeric(0)

x <- list_of(.ptype = integer(), .size = 5)
list_of_ptype(x)
#> integer(0)
```

--------------------------------

### Show prototypes of factors and ordered factors

Source: https://vctrs.r-lib.org/articles/type-size.html

Illustrates the prototype representation for factor and ordered factor types, showing a hash for levels.

```r
vec_ptype_show(factor("a"))
#> Prototype: factor<4d52a>
vec_ptype_show(ordered("b"))
#> Prototype: ordered<9b7e3>
```

--------------------------------

### Implement User-Friendly Constructor Function

Source: https://vctrs.r-lib.org/articles/s3-vector.html

Create an exported, user-friendly constructor function that casts input to the appropriate type and calls the low-level constructor. Includes Roxygen documentation for export and examples.

```R
#' `percent` vector
#'
#' This creates a double vector that represents percentages so when it is
#' printed, it is multiplied by 100 and suffixed with `%`.
#'
#' @param x A numeric vector
#' @return An S3 vector of class `pizza_percent`.
#' @export
#' @examples
#' percent(c(0.25, 0.5, 0.75))
percent <- function(x = double()) {
  x <- vec_cast(x, double())
  new_percent(x)
}
```

--------------------------------

### vec_proxy() and vec_restore() Usage

Source: https://vctrs.r-lib.org/reference/vec_proxy.html

Provides the basic usage signature for vec_proxy() and vec_restore().

```APIDOC
## vec_proxy() and vec_restore()

### Description
`vec_proxy()` returns the data structure containing the values of a vector. `vec_restore()` is the inverse operation.

### Usage
```R
vec_proxy(x, ...)
vec_restore(x, to, ...)
```

### Arguments

* `x`: A vector.
* `...`: These dots are for future extensions and must be empty.
* `to`: The original vector to restore to.
```

--------------------------------

### Display full vector type

Source: https://vctrs.r-lib.org/reference/vec_ptype_full.html

Use `vec_ptype_full()` to get the complete type string of a vector. This is useful for detailed type information.

```R
cat(vec_ptype_full(1:10))
```

```R
cat(vec_ptype_full(iris))
```

--------------------------------

### Order a data frame

Source: https://vctrs.r-lib.org/reference/vec_order.html

Use `vec_order()` to get the order of rows in a data frame. It sorts based on columns from left to right.

```r
# Can also handle data frames
df <- data.frame(g = sample(2, 10, replace = TRUE), x = x)
vec_order(df)
```

--------------------------------

### Create and Print Instances of Custom Tibble

Source: https://vctrs.r-lib.org/reference/howto-faq-coercion-data-frame.html

Demonstrates creating instances of the 'my_tibble' subclass and printing them, showing the custom header with the 'colour' attribute.

```R
red <- my_tibble("red", x = 1, y = 1:2)
red

red[2]

green <- my_tibble("green", z = TRUE)
green
```
Tokens:
Raw