
```{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)
```

`vec_ptype_finalise()` is an S3 generic, but the only time you should ever need to write an S3 method for it is if your class _wraps_ another vector in some way and needs special handling to propagate the default finalisation. For example, the ivs package contains an interval class that wraps `start` and `end` vectors of the same type and has a `vec_ptype_finalize()` method that finalises those wrapped vectors:

```{r, eval = FALSE}
vec_ptype_finalise.ivs_iv <- function(x, ...) {
  start <- unclass(x)[[1L]]
  ptype <- vec_ptype_finalise(start, ...)
  new_bare_iv(ptype, ptype)
}
```

This ensures that `vec_ptype_finalise(vec_ptype(ivs::iv(NA, NA)))` correctly finalises to `<iv<logical>>` rather than `<iv<unspecified>>`.

Note that data frames are already recursively finalised, so you don't need a `vec_ptype_finalise()` method for a data frame subclass.
