idlastro / Miscellaneous (Non-Astronomy) Procedures: MATCH

[Source code]

NAME
MATCH
PURPOSE
Routine to match values in two vectors.
CALLING SEQUENCE
match, a, b, suba, subb, [ COUNT =, /SORT, EPSILON =  ]
INPUTS
a,b - two vectors to match elements, numeric or string data types
OUTPUTS
suba - subscripts of elements in vector a with a match
        in vector b
subb - subscripts of the positions of the elements in
        vector b with matchs in vector a.
suba and subb are ordered such that a[suba] equals b[subb]
OPTIONAL INPUT KEYWORD
/SORT - By default, MATCH uses two different algorithm: (1) the
        /REVERSE_INDICES keyword to HISTOGRAM is used for integer data,
        while (2) a sorting algorithm is used for non-integer data.  The
        histogram algorithm is usually faster, except when the input
        vectors are sparse and contain very large numbers, possibly
        causing memory problems.   Use the /SORT keyword to always use
        the sort algorithm.
epsilon - if values are within epsilon, they are considered equal. Used only
        only for non-integer matching.  Note that input vectors should 
        be unique to within epsilon to provide one-to-one mapping.. 
        Default=0.
OPTIONAL KEYWORD OUTPUT
COUNT - set to the number of matches, integer scalar
SIDE EFFECTS
The obsolete system variable !ERR is set to the number of matches;
however, the use !ERR is deprecated in favor of the COUNT keyword
RESTRICTIONS
The vectors a and b should not have duplicate values within them.
You can use rem_dup function to remove duplicate values
in a vector
EXAMPLE
If a = [3,5,7,9,11]   & b = [5,6,7,8,9,10]
then
        IDL> match, a, b, suba, subb, COUNT = count
will give suba = [1,2,3], subb = [0,2,4],  COUNT = 3
and       a[suba] = b[subb] = [5,7,9]
METHOD
For non-integer data types, the two input vectors are combined and
sorted and the consecutive equal elements are identified.   For integer
data types, the /REVERSE_INDICES keyword to HISTOGRAM of each array
is used to identify where the two arrays have elements in common.
HISTORY
D. Lindler  Mar. 1986.
Fixed "indgen" call for very large arrays   W. Landsman  Sep 1991
Added COUNT keyword    W. Landsman   Sep. 1992
Fixed case where single element array supplied   W. Landsman Aug 95
Use a HISTOGRAM algorithm for integer vector inputs for improved
      performance                W. Landsman         March 2000
Work again for strings           W. Landsman         April 2000
Use size(/type)                  W. Landsman         December 2002
Work for scalar integer input    W. Landsman         June 2003
Assume since V5.4, use COMPLEMENT to WHERE() W. Landsman Apr 2006
Added epsilon keyword            Kim Tolbert         March 14, 2008