R: Find the prototype of a set of vectors

vec_ptype {vctrs} | R Documentation

## Find the prototype of a set of vectors

### Description

`vec_ptype()` returns the unfinalised prototype of a single vector. `vec_ptype_common()` finds the common type of multiple vectors. `vec_ptype_show()` nicely prints the common type of any number of inputs, and is designed for interactive exploration.

### Usage

    vec_ptype(x)

    vec_ptype_common(..., .ptype = NULL)

    vec_ptype_show(...)

### Arguments

`..., x` | Vectors inputs
`.ptype` | If `NULL`, the default, the output type is determined by computing the common type across all elements of `...`. Alternatively, you can supply `.ptype` to give the output known type. If `getOption("vctrs.no_guessing")` is `TRUE` you must supply this value: this is a convenient way to make production code demand fixed types.

### Value

`vec_ptype()` and `vec_ptype_common()` return a prototype (a size-0 vector)

### `vec_ptype()`

`vec_ptype()` returns size 0 vectors potentially containing attributes but no data. Generally, this is just `vec_slice(x, 0L)`, but some inputs require special handling.

- While you can't slice `NULL`, the prototype of `NULL` is itself. This is because we treat `NULL` as an identity value in the `vec_ptype2()` monoid.

- The prototype of logical vectors that only contain missing values is the special unspecified type, which can be coerced to any other 1d type. This allows bare `NA`s to represent missing values for any 1d vector type.

See internal-faq-ptype2-identity for more information about identity values.

Because it may contain unspecified vectors, the prototype returned by `vec_ptype()` is said to be unfinalised. Call `vec_ptype_finalise()` to finalise it. Commonly you will need the finalised prototype as returned by `vec_slice(x, 0L)`.

### `vec_ptype_common()`

`vec_ptype_common()` first finds the prototype of each input, then successively calls `vec_ptype2()` to find a common type. It returns a finalised prototype.

### Examples

    # Unknown types ------------------------------------------
    vec_ptype_show()
    vec_ptype_show(NA)
    vec_ptype_show(NULL)

    # Vectors ------------------------------------------------
    vec_ptype_show(1:10)
    vec_ptype_show(letters)
    vec_ptype_show(TRUE)

    vec_ptype_show(Sys.Date())
    vec_ptype_show(Sys.time())
    vec_ptype_show(factor("a"))
    vec_ptype_show(ordered("a"))

    # Matrices -----------------------------------------------
    # The prototype of a matrix includes the number of columns
    vec_ptype_show(array(1, dim = c(1, 2)))
    vec_ptype_show(array("x", dim = c(1, 2)))

    # Data frames --------------------------------------------
    # The prototype of a data frame includes the prototype of
    # every column
    vec_ptype_show(iris)

    # The prototype of multiple data frames includes the prototype
    # of every column that in any data frame
    vec_ptype_show(
      data.frame(x = TRUE),
      data.frame(y = 2),
      data.frame(z = "a")
    )

[Package vctrs version 0.2.4 Index]