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, incomparables = FALSE)

     x %in% table

_A_r_g_u_m_e_n_t_s:

       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.

_D_e_t_a_i_l_s:

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

_V_a_l_u_e:

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

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

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

_E_x_a_m_p_l_e_s:

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