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` vector: the values to be matched. `table` vector: the values to be matched against. `nomatch` the value to be returned in the case when no match is found. Note that it is coerced to `integer`. `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 < list) before matching.

Matching for lists is potentially very slow and best avoided except in simple cases.

### Value

In both cases, a vector of the same length as `x`.
`match`: An integer 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`.

### References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.

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

[Package base version 2.2.1 Index]