R: Find matching observations across vectors

vec_match {vctrs} | R Documentation

## Find matching observations across vectors

### Description

`vec_in()` returns a logical vector based on whether `needle` is found in haystack. `vec_match()` returns an integer vector giving location of `needle` in `haystack`, or `NA` if it's not found.

### Usage

    vec_match(
      needles,
      haystack,
      ...,
      na_equal = TRUE,
      needles_arg = "",
      haystack_arg = ""
    )

    vec_in(
      needles,
      haystack,
      ...,
      na_equal = TRUE,
      needles_arg = "",
      haystack_arg = ""
    )

### Arguments

`needles, haystack` | Vector of `needles` to search for in vector haystack. `haystack` should usually be unique; if not `vec_match()` will only return the location of the first match. `needles` and `haystack` are coerced to the same type prior to comparison.
`...` | These dots are for future extensions and must be empty.
`na_equal` | If `TRUE`, missing values in `needles` can be matched to missing values in `haystack`. If `FALSE`, they propagate, missing values in `needles` are represented as `NA` in the return value.
`needles_arg, haystack_arg` | Argument tags for `needles` and `haystack` used in error messages.

### Details

`vec_in()` is equivalent to %in%; `vec_match()` is equivalent to `match()`.

### Value

A vector the same length as `needles`. `vec_in()` returns a logical vector; `vec_match()` returns an integer vector.

### Missing values

In most cases places in R, missing values are not considered to be equal, i.e. `NA == NA` is not `TRUE`. The exception is in matching functions like `match()` and `merge()`, where an `NA` will match another `NA`. By `vec_match()` and `vec_in()` will match `NA`s; but you can control this behaviour with the `na_equal` argument.

### Dependencies

- `vec_cast_common()` with fallback

- `vec_proxy_equal()`

### Examples

    hadley <- strsplit("hadley", "")[[1]]
    vec_match(hadley, letters)

    vowels <- c("a", "e", "i", "o", "u")
    vec_match(hadley, vowels)
    vec_in(hadley, vowels)

    # Only the first index of duplicates is returned
    vec_match(c("a", "b"), c("a", "b", "a", "b"))

[Package vctrs version 0.3.2 Index]