match                  package:base                  R Documentation

_V_a_l_u_e _M_a_t_c_h_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

     '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.

_U_s_a_g_e:

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

     x %in% table

_A_r_g_u_m_e_n_t_s:

       x: vector or 'NULL': the values to be matched.

   table: vector or 'NULL': 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.  For historical reasons, 'FALSE' is equivalent to
          'NULL'.

_D_e_t_a_i_l_s:

     '%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'.

_V_a_l_u_e:

     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'.

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     'pmatch' and 'charmatch' for (_partial_) string matching,
     'match.arg', etc for function argument matching. 'findInterval'
     similarly returns a vector of positions, but finds numbers within
     intervals, rather than exact matches.

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

_E_x_a_m_p_l_e_s:

     ## 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, slightly more careful
     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)