Skip to content

Join

Status: Stable

documented, exercised by the test suite and/or worked examples, with no known limitations recorded.

Description

Join[list1, list2, ...]
    Concatenates lists or other expressions that share the same head.
Join[list1, list2, ..., n]
    Joins the objects at level n in each of the lists.
    Handles ragged arrays by concatenating successive elements at level n.

Examples

All examples below are verified against the current Mathilda build.

In[1]:= Join[{a, b, c}, {x, y}, {u, v, w}]
Out[1]= {a, b, c, x, y, u, v, w}

In[2]:= Join[{1, 2}, {3, 4}]
Out[2]= {1, 2, 3, 4}

In[3]:= Join[f[a, b], f[c, d]]
Out[3]= f[a, b, c, d]

In[4]:= Join[{{a, b}, {c, d}}, {{1, 2}, {3, 4}}, 2]
Out[4]= {{a, b, 1, 2}, {c, d, 3, 4}}

In[5]:= Join[{{1}, {5, 6}}, {{2, 3}, {7}}, {{4}, {8}}, 2]
Out[5]= {{1, 2, 3, 4}, {5, 6, 7, 8}}

In[6]:= Join[{{x}}, {{1, 2}, {3, 4}}, 2]
Out[6]= {{x, 1, 2}, {3, 4}}

Implementation notes

builtin_join (in src/list.c) concatenates its arguments via the helper join_at_level. A trailing integer argument is interpreted as a level specification (default 1): at level 1 the arguments' top-level elements are spliced into a single result sharing the first list's head; deeper levels splice element-wise at the corresponding depth. Returns NULL if no lists remain or the level is below 1.

  • Protected.
  • All arguments must share the same head; returns unevaluated if heads differ.
  • Works on any head, not just List (e.g., Join[f[a], f[b]] gives f[a, b]).
  • Join[list1, list2, ..., n] handles ragged arrays by concatenating successive elements at level n.

Attributes: Protected.

Implementation status

Stable — documented, exercised by the test suite and/or worked examples, with no known limitations recorded.

References