Skip to content

DeleteCases

Status: Stable

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

Description

DeleteCases[expr, pattern] removes all elements of expr that match pattern.
DeleteCases[expr, pattern, levelspec] removes all parts of expr on levels specified by levelspec that match pattern.
DeleteCases[expr, pattern, levelspec, n] removes the first n parts of expr that match pattern.
DeleteCases[pattern] represents an operator form of DeleteCases that can be applied to an expression.
The default levelspec is {1}. With Heads -> True, the heads of expressions are also tested; deleting a head is equivalent to applying FlattenAt at that location.
DeleteCases traverses expr in depth-first post-order (leaves before roots).

Examples

All examples below are verified against the current Mathilda build.

In[1]:= Cases[<|"a" -> 1, "b" -> 2, "c" -> 3|>, x_ /; x > 1]
Out[1]= {2, 3}

In[2]:= Count[<|"a" -> 1, "b" -> 2, "c" -> 3|>, x_ /; x > 1]
Out[2]= 2

In[3]:= DeleteCases[<|"a" -> 1, "b" -> 2, "c" -> 3|>, x_ /; x > 1]
Out[3]= <|"a" -> 1|>

Implementation notes

Algorithm. builtin_delete_cases (src/patterns.c) returns a copy of the input with every subexpression matching the pattern (within the level-spec) removed. Level-spec, Heads option, and an optional deletion-count budget n are parsed as in Cases (default level {1,1}). The worker do_delete_cases_at_level is a depth-first post-order rebuild ("leaves before roots"): it recursively transforms the head (only if heads) and each argument, dropping any child flagged for deletion and splicing any Sequence[...] a head-deletion produced, then rebuilds the node. After rebuilding, it tests the original node against the pattern via match; a match sets the parent's *delete_me flag so the node is dropped from its parent's argument list. A matching head (under Heads -> True) turns the call into Sequence[args…] (FlattenAt-style), which the enclosing loop splices outward. The n budget (count_remaining: -1 unlimited, else decremented per deletion) caps the number removed.

Data structures. Per-node freshly-allocated Expr** argument buffer (grown as needed); a bool* delete_me out-parameter threads the removal decision up to the parent; one MatchEnv per match test.

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]:= DeleteCases[{1,2,3,2},2]
Out[1]= {1, 3}

In[1]:= DeleteCases[{1,a,2,b,3},_Integer]
Out[1]= {a, b}

In[1]:= DeleteCases[{{1,2},{a,b},{3,c}}, {_Integer, _Integer}]
Out[1]= {{a, b}, {3, c}}

In[1]:= DeleteCases[{a + b, c d, e^2, f}, _Power, Infinity]
Out[1]= {a + b, c d, f}

Notes

Removes every element matching the pattern; combine with _Integer or _?OddQ to filter by head or predicate. The pattern can be structural — {_Integer, _Integer} deletes only the sublists that are pairs of integers. With a level specification such as Infinity, DeleteCases descends into subexpressions and removes matching parts at any depth (here every Power subterm), traversing in depth-first post-order. The default level is {1} (top-level elements).