match                  package: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)

