match {base} | R Documentation

## Value Matching

### Description

`match` returns a vector of the positions of (first) matches of its first argument in its second.

`%in%` is a more intuitive interface as a binary operator, which returns a logical vector indicating if there is a match or not for its left operand.

### Usage

    match(x, table, nomatch = NA, incomparables = FALSE)
    x %in% table

### Arguments

`x` | the values to be matched.
`table` | the values to be matched against.
`nomatch` | the value to be returned in the case when no match is found.
`incomparables` | a vector of values that cannot be matched. Any value in `x` matching a value in this vector is assigned the `nomatch` value. Currently, `FALSE` is the only possible value, meaning that all values can be matched.

### Details

`%in%` is currently defined as
`"%in%" <- function(x, table) match(x, table, nomatch = 0) > 0`

Factors are converted to character vectors, and then `x` and `table` are coerced to a common type (the later of the two types in R's ordering, logical < integer < numeric < complex < character) before matching.

### Value

In both cases, a vector of the same length as `x`.
`match`: A numeric vector giving the position in `table` of the first match if there is a match, otherwise `nomatch`.
If `x[i]` is found to equal `table[j]` then the value returned in the `i`-th position of the return value is `j`, for the smallest possible `j`. If no match is found, the value is `nomatch`.
`%in%`: A logical vector, indicating if a match was located for each element of `x`.

### See Also

`pmatch` and `charmatch` for (partial) string matching, `match.arg`, etc for function argument matching.

`is.element` for an S-compatible equivalent of `%in%`.

### Examples

    ## The intersection of two sets :
    intersect <- function(x, y) y[match(x, y, nomatch = 0)]
    intersect(1:10,7:20)

    1:10 %in% c(1,3,5,9)
    sstr <- c("c","ab","B","bba","c","@","bla","a","Ba","%")
    sstr[sstr %in% c(letters,LETTERS)]

    "%w/o%" <- function(x,y) x[!x %in% y] #--  x without y
    (1:10) %w/o% c(3,7,12)