def join_by(key, r1, r2, jointype='<STR_LIT>', r1postfix='<STR_LIT:1>', r2postfix='<STR_LIT:2>',<EOL>defaults=None, usemask=True, asrecarray=False):
<EOL>if jointype not in ('<STR_LIT>', '<STR_LIT>', '<STR_LIT>'):<EOL><INDENT>raise ValueError(<EOL>"<STR_LIT>"<EOL>"<STR_LIT>" % jointype<EOL>)<EOL><DEDENT>if isinstance(key, basestring):<EOL><INDENT>key = (key,)<EOL><DEDENT>for name in key:<EOL><INDENT>if name not in r1.dtype.names:<EOL><INDENT>raise ValueError('<STR_LIT>' % name)<EOL><DEDENT>if name not in r2.dtype.names:<EOL><INDENT>raise ValueError('<STR_LIT>' % name)<EOL><DEDENT><DEDENT>r1 = r1.ravel()<EOL>r2 = r2.ravel()<EOL>nb1 = len(r1)<EOL>(r1names, r2names) = (r1.dtype.names, r2.dtype.names)<EOL>if (set.intersection(set(r1names), set(r2names)).difference(key) and<EOL>not (r1postfix or r2postfix)):<EOL><INDENT>msg = "<STR_LIT>"<EOL>msg += "<STR_LIT>"<EOL>raise ValueError(msg)<EOL><DEDENT>r1k = drop_fields(r1, [n for n in r1names if n not in key])<EOL>r2k = drop_fields(r2, [n for n in r2names if n not in key])<EOL>aux = ma.concatenate((r1k, r2k))<EOL>idx_sort = aux.argsort(order=key)<EOL>aux = aux[idx_sort]<EOL>flag_in = ma.concatenate(([False], aux[<NUM_LIT:1>:] == aux[:-<NUM_LIT:1>]))<EOL>flag_in[:-<NUM_LIT:1>] = flag_in[<NUM_LIT:1>:] + flag_in[:-<NUM_LIT:1>]<EOL>idx_in = idx_sort[flag_in]<EOL>idx_1 = idx_in[(idx_in < nb1)]<EOL>idx_2 = idx_in[(idx_in >= nb1)] - nb1<EOL>(r1cmn, r2cmn) = (len(idx_1), len(idx_2))<EOL>if jointype == '<STR_LIT>':<EOL><INDENT>(r1spc, r2spc) = (<NUM_LIT:0>, <NUM_LIT:0>)<EOL><DEDENT>elif jointype == '<STR_LIT>':<EOL><INDENT>idx_out = idx_sort[~flag_in]<EOL>idx_1 = np.concatenate((idx_1, idx_out[(idx_out < nb1)]))<EOL>idx_2 = np.concatenate((idx_2, idx_out[(idx_out >= nb1)] - nb1))<EOL>(r1spc, r2spc) = (len(idx_1) - r1cmn, len(idx_2) - r2cmn)<EOL><DEDENT>elif jointype == '<STR_LIT>':<EOL><INDENT>idx_out = idx_sort[~flag_in]<EOL>idx_1 = np.concatenate((idx_1, idx_out[(idx_out < nb1)]))<EOL>(r1spc, r2spc) = (len(idx_1) - r1cmn, <NUM_LIT:0>)<EOL><DEDENT>(s1, s2) = (r1[idx_1], r2[idx_2])<EOL>ndtype = [list(_) for _ in r1k.dtype.descr]<EOL>ndtype.extend(list(_) for _ in r1.dtype.descr if _[<NUM_LIT:0>] not in key)<EOL>names = list(_[<NUM_LIT:0>] for _ in ndtype)<EOL>for desc in r2.dtype.descr:<EOL><INDENT>desc = list(desc)<EOL>name = desc[<NUM_LIT:0>]<EOL>if name in names:<EOL><INDENT>nameidx = ndtype.index(desc)<EOL>current = ndtype[nameidx]<EOL>if name in key:<EOL><INDENT>current[-<NUM_LIT:1>] = max(desc[<NUM_LIT:1>], current[-<NUM_LIT:1>])<EOL><DEDENT>else:<EOL><INDENT>current[<NUM_LIT:0>] += r1postfix<EOL>desc[<NUM_LIT:0>] += r2postfix<EOL>ndtype.insert(nameidx + <NUM_LIT:1>, desc)<EOL><DEDENT><DEDENT>else:<EOL><INDENT>names.extend(desc[<NUM_LIT:0>])<EOL>ndtype.append(desc)<EOL><DEDENT><DEDENT>ndtype = [tuple(_) for _ in ndtype]<EOL>cmn = max(r1cmn, r2cmn)<EOL>output = ma.masked_all((cmn + r1spc + r2spc,), dtype=ndtype)<EOL>names = output.dtype.names<EOL>for f in r1names:<EOL><INDENT>selected = s1[f]<EOL>if f not in names or (f in r2names and not r2postfix and f not in key):<EOL><INDENT>f += r1postfix<EOL><DEDENT>current = output[f]<EOL>current[:r1cmn] = selected[:r1cmn]<EOL>if jointype in ('<STR_LIT>', '<STR_LIT>'):<EOL><INDENT>current[cmn:cmn + r1spc] = selected[r1cmn:]<EOL><DEDENT><DEDENT>for f in r2names:<EOL><INDENT>selected = s2[f]<EOL>if f not in names or (f in r1names and not r1postfix and f not in key):<EOL><INDENT>f += r2postfix<EOL><DEDENT>current = output[f]<EOL>current[:r2cmn] = selected[:r2cmn]<EOL>if (jointype == '<STR_LIT>') and r2spc:<EOL><INDENT>current[-r2spc:] = selected[r2cmn:]<EOL><DEDENT><DEDENT>output.sort(order=key)<EOL>kwargs = dict(usemask=usemask, asrecarray=asrecarray)<EOL>return _fix_output(_fix_defaults(output, defaults), **kwargs)<EOL>
Join arrays `r1` and `r2` on key `key`.

The key should be either a string or a sequence of string corresponding
to the fields used to join the array.  An exception is raised if the
`key` field cannot be found in the two input arrays.  Neither `r1` nor
`r2` should have any duplicates along `key`: the presence of duplicates
will make the output quite unreliable. Note that duplicates are not
looked for by the algorithm.

Parameters
----------
key : {string, sequence}
    A string or a sequence of strings corresponding to the fields used
    for comparison.
r1, r2 : arrays
    Structured arrays.
jointype : {'inner', 'outer', 'leftouter'}, optional
    If 'inner', returns the elements common to both r1 and r2.
    If 'outer', returns the common elements as well as the elements of
    r1 not in r2 and the elements of not in r2.
    If 'leftouter', returns the common elements and the elements of r1
    not in r2.
r1postfix : string, optional
    String appended to the names of the fields of r1 that are present
    in r2 but absent of the key.
r2postfix : string, optional
    String appended to the names of the fields of r2 that are present
    in r1 but absent of the key.
defaults : {dictionary}, optional
    Dictionary mapping field names to the corresponding default values.
usemask : {True, False}, optional
    Whether to return a MaskedArray (or MaskedRecords is
    `asrecarray==True`) or a ndarray.
asrecarray : {False, True}, optional
    Whether to return a recarray (or MaskedRecords if `usemask==True`)
    or just a flexible-type ndarray.

Notes
-----
* The output is sorted along the key.
* A temporary array is formed by dropping the fields not in the key for
  the two arrays and concatenating the result. This array is then
  sorted, and the common entries selected. The output is constructed by
  filling the fields with the selected entries. Matching is not
  preserved if there are some duplicates...