idlastro / Miscellaneous (Non-Astronomy) Procedures: MATCH2

[Source code]

NAME
MATCH2
PURPOSE
Routine to cross-match values in two vectors (including non-matches)
EXPLANATION
MATCH2 reports matching elements of two arrays.
This procedure *appears* similar to MATCH of the IDL astronomy
library.  However, this routine is quite different in that it
reports an index value for each element of the input arrays.
In other words, while MATCH reports the *existence* of
matching elements in each array, MATCH2 reports explicitly
*which* elements match.
Furthermore, while MATCH reports only unique matching
elements, MATCH2 will always report a cross-match for every
element in each array, even if it is a repeat.
In cases where no match was found, an index of -1 is
reported.  
CALLING SEQUENCE
match2, a, b, suba, subb
INPUTS
a,b - two vectors to match elements, numeric or string data
      types.  (See below for RESTRICTIONS on A and B)
OUTPUTS
suba - vector with same number of elements as A, such that
       A EQ B[SUBA], except non-matches which are indicated
       by SUBA EQ -1
subb - vector with same number of elements as B, such that
       B EQ A[SUBB], except non-matches which are indicated
       by SUBB EQ -1
RESTRICTIONS
The vectors A and B are allowed to have duplicates in them,
but for matching purposes, only the first one found will
be reported.
MATCH2 internally converts values to double precision and so 
cannot be used with long64 integers that cannot be converted to double.
Best to convert such long64 integers to strings before matching.
If A and B are string arrays, then non-printable ASCII values
1B and 2B will confuse the algorithm.  Don't use these
non-printable characters in strings.
EXAMPLE
A = [0,7,14,23,24,30]
B = [7,8,14,25,14]
IDL> match2, a, b, suba, subb
-> suba = [ -1 ,  0,  4,  -1, -1, -1 ]
indicates that A[1] matches B[1] and A[3] matches B[2])
-> subb = [  1 , -1,  2,  -1,  2 ]
indicates that B[1] matches A[1] and B[2] matches A[3])
are to the results of the original MATCH procedure,
IDL> match, a, b, suba, subb
-> suba = [  1,  3]
icates that A[1] and A[3] match elements in B, but not which ones)
-> subb = [  1,  2]
icates that B[1] and B[2] match elements in A, but not which ones)
MODIFICATION HISTORY
Derived from the IDL Astronomy Library MATCH, 14 Feb 2007
Updated documentation, 17 Jul 2007
More updated documentation (example), 03 Sep 2007
Bug fix for string arrays with numerical contents; the subset
string is now 1B and 2B; this is now documented, 2014-10-20 CM
Added warning about problems with LONG64 values WL 2020-10-29