Value Matching

Description

match returns a vector of the positions of (first) matches ofits 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 notfor its left operand.

Usage

match(x, table, nomatch = NA_integer_, incomparables = NULL)x %in% table

Arguments

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, andthenx andtable are coerced to a common type (the laterof the two types inR's ordering, logical < integer < numeric <complex < character) before matching. Ifincomparables haspositive length it is coerced to the common type.

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

Exactly what matches what is to some extent a matter of definition.For all types,NA matchesNA and no other value.For real and complex values,NaN values are regardedas matching any otherNaN value, but not matchingNA,where for complexx, real and imaginary parts must match both(unless containing at least oneNA).

Character strings will be compared as byte sequences if any input ismarked as"bytes", and otherwise are regarded as equal if they arein different encodings but would agree when translated to UTF-8 (seeEncoding).

That%in% never returnsNA makes it particularlyuseful inif conditions.

Value

A vector of the same length asx.

match: An integer vector giving the position intable ofthe first match if there is a match, otherwisenomatch.

Ifx[i] is found to equaltable[j] then the valuereturned in thei-th position of the return value isj,for the smallest possiblej. If no match is found, the valueisnomatch.

%in%: A logical vector, indicating if a match was located foreach element ofx: thus the values areTRUE orFALSE and neverNA.

References

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

See Also

pmatch andcharmatch for (partial)string matching,match.arg, etc for function argumentmatching.findInterval similarly returns a vector of positions, butfinds numbers within intervals, rather than exact matches.

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

unique (andduplicated) are using the samedefinitions of “match” or “equality” asmatch(),and these are less strict than==, e.g., forNA andNaN in numeric or complex vectors,or for strings with different encodings, see also above.

Examples

## The intersection of two sets can be defined via match():## Simple version:## intersect <- function(x, y) y[match(x, y, nomatch = 0)]intersect # the R function in base is slightly more carefulintersect(1:10, 7:20)1:10 %in% c(1,3,5,9)sstr <- c("c","ab","B","bba","c",NA,"@","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)## Note that setdiff() is very similar and typically makes more sense:        c(1:6,7:2) %w/o% c(3,7,12)  # -> keeps duplicatessetdiff(c(1:6,7:2),      c(3,7,12)) # -> unique values## Illuminating example about NA matchingr <- c(1, NA, NaN)zN <- c(complex(real = NA , imaginary =  r ), complex(real =  r , imaginary = NA ),        complex(real =  r , imaginary = NaN), complex(real = NaN, imaginary =  r ))zM <- cbind(Re=Re(zN), Im=Im(zN), match = match(zN, zN))rownames(zM) <- format(zN)zM ##--> many "NA's" (= 1) and the four non-NA's (3 different ones, at 7,9,10)length(zN) # 12unique(zN) # the "NA" and the 3 different non-NA NaN'sstopifnot(identical(unique(zN), zN[c(1, 7,9,10)]))## very strict equality would have 4 duplicates (of 12):symnum(outer(zN, zN, Vectorize(identical,c("x","y")),                     FALSE,FALSE,FALSE,FALSE))## removing "(very strictly) duplicates",i <- c(5,8,11,12)  # we get 8 pairwise non-identicals :Ixy <- outer(zN[-i], zN[-i], Vectorize(identical,c("x","y")),                     FALSE,FALSE,FALSE,FALSE)stopifnot(identical(Ixy, diag(8) == 1))