Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

 MapCases

Source Notebook

Map a function at parts of an expression that match a given pattern

Contributed by: Richard Hennigan (Wolfram Research)

ResourceFunction["MapCases"][f,{e1,e2,…},pattern]

applies f to each ei that matches pattern.

ResourceFunction["MapCases"][f,expr,pattern,levelspec]

applies at levels specified by levelspec.

ResourceFunction["MapCases"][f,pattern]

represents an operator form of ResourceFunction["MapCases"] that can be applied to an expression.

Details and Options

The expr can have any head, not just List.
ResourceFunction["MapCases"][f,pattern][expr] is equivalent to ResourceFunction["MapCases"][f,expr,pattern].
When used on an Association, ResourceFunction["MapCases"] matches elements according to their values.
ResourceFunction["MapCases"] uses standard level specifications:
nlevels 1 through n
Infinitylevels 1 through Infinity
{n}level n only
{n1,n2}levels n1 through n2
The default value for levelspec in ResourceFunction["MapCases"] is {1}.
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 -1 consists of numbers, symbols and other objects that do not have subparts.
Level 0 corresponds to the whole expression.
With the option setting Heads→True, ResourceFunction["MapCases"] looks at heads of expressions and their parts.
ResourceFunction["MapCases"] traverses the parts of expr in a depth-first order, with leaves visited before roots.
ResourceFunction["MapCases"] has the following options:
HeadsFalsewhether to check heads of subexpressions
EvaluateCasesFalsewhether to evaluate f[ei] inside held expressions

Examples

Basic Examples (3) 

Map a function at integers only:

In[1]:=
ResourceFunction[ "MapCases"][f, {1, 1, g[a], 2, 3, y, g[8], 9, g[10]}, _Integer]
Out[1]=

Map a function at anything other than integers:

In[2]:=
ResourceFunction["MapCases"][f, {1, 1, g[a], 2, 3, y, g[8], 9, g[10]}, Except[_Integer]]
Out[2]=

Use the operator form of MapCases:

In[3]:=
ResourceFunction["MapCases"][f, _Integer]
Out[3]=
In[4]:=
%[{1, 1, g[a], 2, 3, y, g[8], 9, g[10]}]
Out[4]=

Map at matching elements in an Association:

In[5]:=
ResourceFunction[ "MapCases"][f, <|1 -> "a", 2 -> "b", 3 -> c, 4 -> d|>, _Symbol]
Out[5]=

Scope (4) 

Apply a function to strings only:

In[6]:=
ResourceFunction[ "MapCases"][StringLength, {1, 2, "a", x, "testing"}, _String]
Out[6]=

Apply a function to cases of lists of integers:

In[7]:=
ResourceFunction[ "MapCases"][Total, {{1, 2}, {x}, {3, 4, 1}, "Hello", a, b}, {__Integer}]
Out[7]=

Apply a function to nonzero values only:

In[8]:=
ResourceFunction["MapCases"][ 1/# &, {1, 0, Sqrt[2], -10, 3, Pi, 5, 0, x}, Except[0]]
Out[8]=

Apply a function to cases of lists of integers at any level:

In[9]:=
ResourceFunction[ "MapCases"][Total, {g[{1, 2}], {x}, {{3, 4}, {5, 6}}, "Hello", a, {b, 2}}, {__Integer}, Infinity]
Out[9]=

Options (4) 

Heads (2) 

Map at symbols among the elements of an expression:

In[10]:=
ResourceFunction["MapCases"][f, {a, 5, \[Pi]}, _Symbol]
Out[10]=

Also include the head of the expression in the search:

In[11]:=
ResourceFunction["MapCases"][f, {a, 5, \[Pi]}, _Symbol, Heads -> True]
Out[11]=

EvaluateCases (2) 

By default, the f[ei] will remain unevaluated if the ei is found within a held expression:

In[12]:=
ResourceFunction["MapCases"][Minus, Hold[1 + 1, 2*2, 3 + 3], _Plus]
Out[12]=

Evaluate each of the f[ei] when applying:

In[13]:=
ResourceFunction["MapCases"][Minus, Hold[1 + 1, 2*2, 3 + 3], _Plus, "EvaluateCases" -> True]
Out[13]=

Applications (2) 

Convert all symbols in an expression to strings:

In[14]:=
ResourceFunction["MapCases"][ ResourceFunction["FullSymbolName"], {1, 1 + x, f[a], 2, 3, y, f[8], 9, f[10]}, _Symbol, Infinity]
Out[14]=

Include heads:

In[15]:=
ResourceFunction["MapCases"][ ResourceFunction["FullSymbolName"], {1, 1 + x, f[a], 2, 3, y, f[8], 9, f[10]}, _Symbol, Infinity, Heads -> True]
Out[15]=

Properties and Relations (4) 

MapCases[f,expr,_] is equivalent to Map[f,expr]:

In[16]:=
expr = {1, 1 + x, g[a], 2, 3, y, g[8], 9, g[10]}
Out[16]=
In[17]:=
ResourceFunction["MapCases"][f, expr, _]
Out[17]=
In[18]:=
Map[f, expr]
Out[18]=

MapCases[f,expr,pattern,levelspec] is equivalent to Replace[expr,e:pattern⧴f[e],levelspec]:

In[19]:=
expr = {1, 1 + x, g[a], 2, 3, y, g[8], 9, g[10]}
Out[19]=
In[20]:=
ResourceFunction["MapCases"][f, expr, _Integer, {1}]
Out[20]=
In[21]:=
Replace[expr, e : _Integer :> f[e], {1}]
Out[21]=

MapCases[f,expr,pattern,levelspec] is equivalent to MapAt[f,expr,Position[expr,pattern,levelspec]]:

In[22]:=
expr = {1, 1 + x, g[a], 2, 3, y, g[8], 9, g[10]}
Out[22]=
In[23]:=
ResourceFunction["MapCases"][f, expr, _Integer, {1}]
Out[23]=
In[24]:=
MapAt[f, expr, Position[expr, _Integer, {1}]]
Out[24]=

When using the option "EvaluateCases"→True, these equivalencies no longer necessarily hold:

In[25]:=
expr = Hold[1 + 1, 2*2, 3 + 3]
Out[25]=
In[26]:=
ResourceFunction["MapCases"][Minus, expr, _, "EvaluateCases" -> True]
Out[26]=
In[27]:=
Map[Minus, expr]
Out[27]=
In[28]:=
ResourceFunction["MapCases"][Minus, expr, _Plus, {1}, "EvaluateCases" -> True]
Out[28]=
In[29]:=
Replace[expr, e : _Plus :> Minus[e], {1}]
Out[29]=

Possible Issues (2) 

MapCases by default starts at level 1, so it does not apply the function to the whole expression:

In[30]:=
ResourceFunction["MapCases"][f, h1[h2[h3[x]]], _, -1]
Out[30]=
In[31]:=
ResourceFunction["MapCases"][f, h1[h2[h3[x]]], _, {0, -1}]
Out[31]=

In MapCases[f,expr,pattern], the pattern will evaluate before matching unless wrapped in HoldPattern:

In[32]:=
ResourceFunction["MapCases"][Minus, Hold[1 1, 2 2, 3 3, 4 1], 1*_, "EvaluateCases" -> True]
Out[32]=
In[33]:=
ResourceFunction["MapCases"][Minus, Hold[1 1, 2 2, 3 3, 4 1], HoldPattern[1*_], "EvaluateCases" -> True]
Out[33]=

Neat Examples (1) 

Highlight integers in an expression:

In[34]:=
Integrate[1/(x^3 - 1), x]
Out[34]=
In[35]:=
ResourceFunction["MapCases"][ Style[#, Background -> Green] &, %, _Integer, Infinity]
Out[35]=

Requirements

Wolfram Language 11.3 (March 2018) or above

Version History

  • 1.0.0 – 18 February 2019

Related Resources

License Information