Skip to content

Level

Status: Stable

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

Description

Level[expr, levelspec]
    gives a list of all subexpressions of expr on levels specified by levelspec.
Level[expr, levelspec, f]
    applies f to the sequence of subexpressions.

Level uses standard level specifications:
  n            levels 1 through n
  Infinity     levels 1 through Infinity
  {n}          level n only
  {n1, n2}     levels n1 through n2

Level[expr, {-1}] gives a list of all "atomic" objects in expr.
A positive level n consists of all parts of expr specified by n indices.
A negative level -n consists of all parts of expr with depth n.
Level 0 corresponds to the whole expression.
With the option setting Heads->True, Level includes heads of expressions and their parts.
Level traverses expressions in depth-first order, so that the subexpressions in the final list are ordered lexicographically by their indices.

Examples

All examples below are verified against the current Mathilda build.

In[1]:= Level[a + f[x, y^n], {-1}]
Out[1]= {a, x, y, n}

In[2]:= Level[a + f[x, y^n], 2]
Out[2]= {a, x, y^n, f[x, y^n]}

In[3]:= Level[x^2 + y^3, 3, Heads -> True]
Out[3]= {Plus, Power, x, 2, x^2, Power, y, 3, y^3}

Implementation notes

Algorithm. builtin_level collects the subexpressions of e that lie at the depths selected by the level spec (an integer n = levels 1..n, Infinity, {n} = exactly level n, or {min, max}). It descends with the recursive level_rec, tracking the current depth and appending matching nodes into a growable Expr** buffer, then wraps them in a List. The option Heads -> True additionally includes function heads as level elements.

  • Protected.
  • Default option: Heads -> False.
  • Standard level specifications:
  • n: levels 1 through n.
  • Infinity: levels 1 through Infinity.
  • {n}: level n only.
  • {n1, n2}: levels n1 through n2.
  • Positive level n refers to distance from the top (level 0 is the whole expression).
  • Negative level -n refers to distance from the bottom (depth n).
  • Level -1 corresponds to atomic objects.
  • Lists subexpressions in post-order (depth-first), resulting in lexicographic ordering of indices.

Attributes: Protected.

Implementation status

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

References

Notes & additional examples

Worked examples

In[1]:= Level[a + b c, {1}]
Out[1]= {a, b c}

Level {2} reaches one step deeper, into the factors of b c:

In[1]:= Level[a + b c, {2}]
Out[1]= {b, c}

{-1} extracts the atomic leaves; {-2} the parts of depth two:

In[1]:= Level[f[g[h[x]]], {-1}]
Out[1]= {x}

In[2]:= Level[(1 + x)^2 + y, {-2}]
Out[2]= {1 + x}

A full depth-first walk traverses subexpressions in lexicographic index order:

In[1]:= Level[{{a, b}, {c, {d, e}}}, Infinity]
Out[1]= {a, b, {a, b}, c, d, e, {d, e}, {c, {d, e}}}

With Heads -> True, the head of each expression and its parts are included:

In[1]:= Level[f[g[x], y], 2, Heads -> True]
Out[1]= {f, g, x, g[x], y}

Notes

Level[expr, levelspec] returns the subexpressions of expr on the specified levels. A positive level n selects parts reachable by n indices; a negative level -n selects parts of depth n; {-1} gives all atoms and level 0 is the whole expression. Level[expr, levelspec, f] applies f to the sequence of subexpressions, and Heads -> True includes expression heads in the traversal.