[ RDocumentation ](/)

Moon  [ ](https://github.com/datacamp/rdocumentation-2.0) [ Learn R
](https://www.datacamp.com/learn/r)

Search all packages and functions

[ base  (version  3.6.2  ) ](/packages/base/versions/3.6.2)

#  match: 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_integer_, incomparables = NULL)
    
    x %in% table

##  Arguments

x

vector or ` NULL ` : the values to be matched. [ Long vectors
](/link/Long%20vectors?package=base&version=3.6.2) are supported.

table

vector or ` NULL ` : the values to be matched against. [ Long vectors
](/link/Long%20vectors?package=base&version=3.6.2) are not supported.

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. For historical reasons, `
FALSE ` is equivalent to ` NULL ` .

##  Value

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 ` : thus the values are ` TRUE ` or ` FALSE ` and never ` NA `
.

##  Details

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

Factors, raw vectors and lists 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. If ` incomparables ` has positive length it is coerced to the common
type.

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

Exactly what matches what is to some extent a matter of definition. For all
types, ` NA ` matches ` NA ` and no other value. For real and complex values,
` NaN ` values are regarded as matching any other ` NaN ` value, but not
matching ` NA ` , where for complex ` x ` , real and imaginary parts must
match both (unless containing at least one ` NA ` ).

Character strings will be compared as byte sequences if any input is marked as
` "bytes" ` , and otherwise are regarded as equal if they are in different
encodings but would agree when translated to UTF-8 (see ` [ Encoding
](/link/Encoding?package=base&version=3.6.2) ` ).

That ` %in% ` never returns ` NA ` makes it particularly useful in ` if `
conditions.

##  References

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

##  See Also

` [ pmatch ](/link/pmatch?package=base&version=3.6.2) ` and ` [ charmatch
](/link/charmatch?package=base&version=3.6.2) ` for ( _partial_ ) string
matching, ` [ match.arg ](/link/match.arg?package=base&version=3.6.2) ` , etc
for function argument matching. ` [ findInterval
](/link/findInterval?package=base&version=3.6.2) ` similarly returns a vector
of positions, but finds numbers within intervals, rather than exact matches.

` [ is.element ](/link/is.element?package=base&version=3.6.2) ` for an
S-compatible equivalent of ` %in% ` .

` [ unique ](/link/unique?package=base&version=3.6.2) ` (and ` [ duplicated
](/link/duplicated?package=base&version=3.6.2) ` ) are using the same
definitions of “match” or “equality” as ` match() ` , and these are less
strict than ` [ == ](/link/%3D%3D?package=base&version=3.6.2) ` , e.g., for `
[ NA ](/link/N