vctrs: vec_match – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

vec_match

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 NAs; 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"))

vctrs

Vector Helpers

v0.3.8

MIT + file LICENSE

Authors

Hadley Wickham [aut], Lionel Henry [aut, cre], Davis Vaughan [aut], data.table team [cph] (Radix sort based on data.table's forder() and their contribution to R's order()), RStudio [cph]

Initial release