Wolfram Research

Function Repository Resource:

MultiReplace (2.2.0) current version: 2.2.3 »

Source Notebook

Perform replacements and also give positions at which they occur

Contributed by: Nikolay Murzin

ResourceFunction["MultiReplace"][expr, rule]

returns all possible subexpressions of expr after application of rule with information about each replacement.

ResourceFunction["MultiReplace"][expr, {rule1,rule2,}]

returns result after applying a list of rules.

ResourceFunction["MultiReplace"][expr,{x1,x2,}{y1,y2,}]

use a list of patterns to replace subexpression tuples/subsets.

ResourceFunction["MultiReplace"][expr,rules,level]

specify a level spec.

ResourceFunction["MultiReplace"][expr,rules,level, head]

uses a custom head to specify subexpression tuples/subsets.

ResourceFunction["MultiReplace"][expr,subexpr,]

return subexpression matches without performing substitution.

Details and Options

ResourceFunction["MultiReplace"] returns an association with keys containing a rule index and list of positions of a tuple/subset of subexpressions where the corresponding rule was applied.
If one rule is given, keys contain positions only.
Association values are results of applying ReplaceList at corresponding positions, so for a given position multiple results of substitution are possible.
The left-hand-side of a rule can be a list or a custom head to replace tuples/subsets of subexpressions, similar to SequenceReplace and SubsetReplace but for all positions.
When a list of patterns is specified as a left-hand side, replacement is applied at multiple positions with all elements of a list being matched based on the specified "Mode".
If a rule returns a list (or a head) of expressions they are substituted for the corresponding tuple/subset positions on the left-hand-side.
ResourceFunction["MultiReplace"] takes the same options as the resource function SubexpressionPositions for subexpression selection.
ResourceFunction["MultiReplace"] takes the following options:
"Mode""Tuples"how to match multiple subexpressions: "Tuples", "OrderedTuples", "Subsets" or "OrderlessSubsets"
"PatternSubstitutions"Falsewhether to include pattern substitutions
"ReturnMatches"Falsereturn subexpression matches by ignoring right-hand-side of rules if present
Method"Substitution"substitution strategy to use: "Susbtitution", "Cosubstitution" or "Bisubstitution"
HeadsTruewhether to match heads of expressions and their parts

Examples

Basic Examples (3) 

Apply a rule at each possible position of an expression:

In[1]:=
ResourceFunction["MultiReplace"][f[x, g[y]], a_ :> h[a]]
Out[1]=

Apply multiple rules:

In[2]:=
ResourceFunction["MultiReplace"][f[x, g[y]], {a_ :> h[a], b_ -> 1}]
Out[2]=

Apply tuple replacement rule:

In[3]:=
ResourceFunction["MultiReplace"][{x, y, x, y}, {x, y} -> {A, B}]
Out[3]=

Scope (6) 

Subexpressions are being spliced in the order of matched elements:

In[4]:=
ResourceFunction["MultiReplace"][f[a, b], {b, a} :> {XXXX, YYYY}]
Out[4]=

Splicing continues after the last element:

In[5]:=
ResourceFunction["MultiReplace"][
 f[a, b], {b, a} :> {XXXX, YYYY, ZZZZ}]
Out[5]=

Single element can be matched more than once:

In[6]:=
ResourceFunction["MultiReplace"][f[a, b], {a, a, a} :> XXXX]
Out[6]=

Specify a level:

In[7]:=
ResourceFunction["MultiReplace"][{a, b, f[c]}, x_ :> g[x], {1}]
Out[7]=

Specify an explicit list of positions to replace at:

In[8]:=
ResourceFunction["MultiReplace"][{a, b, f[c]}, x_ :> g[x], {{1}, {-1}}]
Out[8]=

Use a custom head for designating tuples:

In[9]:=
ResourceFunction["MultiReplace"][{a, b}, tuple[b, a] :> tuple[XXX, YYY, ZZZZ], All, tuple]
Out[9]=
In[10]:=
ResourceFunction["MultiReplace"][{a, b}, tuple[b, a] :> {XXX, YYY, ZZZZ}, All, tuple]
Out[10]=
In[11]:=
ResourceFunction["MultiReplace", ResourceVersion->"2.2.0"][{a, b}, {b, a} :> {XXX, YYY, ZZZZ}, All, tuple]
Out[11]=

Specify a matching condition:

In[12]:=
ResourceFunction["MultiReplace", ResourceVersion->"2.2.0"][{1, 2, 4}, {x_, y_} /; x + y == 3 :> {a, b}]
Out[12]=

Options (8) 

Heads (1) 

Ignore heads:

In[13]:=
ResourceFunction["MultiReplace"][f[x], a_ :> g[a], Heads -> False]
Out[13]=

Mode (1) 

Change the mode of matching multiple subexpressions:

In[14]:=
ResourceFunction["MultiReplace"][{a, b, a}, {a, a} :> {XXXX, YYYY}, "Mode" -> "Tuples"]
Out[14]=
In[15]:=
ResourceFunction["MultiReplace"][{a, b, a}, {a, a} :> {XXXX, YYYY}, "Mode" -> "OrderedTuples"]
Out[15]=
In[16]:=
ResourceFunction["MultiReplace"][{a, b, a}, {a, a} :> {XXXX, YYYY}, "Mode" -> "OrderlessSubsets"]
Out[16]=
In[17]:=
ResourceFunction["MultiReplace"][{a, b, a}, {a, a} :> {XXXX, YYYY}, "Mode" -> "Subsets"]
Out[17]=

Method (2) 

Three substitution strategies are supported, based on the direction of pattern unification:

In[18]:=
ResourceFunction["MultiReplace"][{f[a, b], f[y_, x_], f[a, x_]}, f[z_, b] -> c, 1, Method -> "Substitution"]
Out[18]=
In[19]:=
ResourceFunction["MultiReplace"][{f[a, b], f[y_, x_], f[a, x_]}, f[z_, b] -> c, 1, Method -> "Cosubstitution"]
Out[19]=
In[20]:=
ResourceFunction["MultiReplace"][{f[a, b], f[y_, x_], f[a, x_]}, f[z_, b] -> c, 1, Method -> "Bisubstitution"]
Out[20]=

Get all tuple bisubstitutions:

In[21]:=
ResourceFunction["MultiReplace", ResourceVersion->"2.2.0"][{f[a, x_], f[b, y_], f[c, z_], g[x_, y_, z_]}, {f[u_, 1], f[v_, 2]} -> {u, v}, 1, Method -> "Bisubstitution"]
Out[21]=

ReturnMatches (2) 

Return corresponding matches only without performing a substitution (note HoldForm wrapping of individual matched subexpressions to prevent evaluation):

In[22]:=
ResourceFunction["MultiReplace", ResourceVersion->"2.2.0"][{f[a, x_], f[b, y_], f[c, z_], g[x_, y_, z_]}, {f[u_, 1], f[v_, 2]} -> {u, v}, 1, Method -> "Bisubstitution", "ReturnMatches" -> True] // InputForm
Out[22]=

This is also equivalent to just dropping the right-hand-side of a rule:

In[23]:=
ResourceFunction["MultiReplace", ResourceVersion->"2.2.0"][{f[a, x_], f[b, y_], f[c, z_], g[x_, y_, z_]}, {f[u_, 1], f[v_, 2]}, 1, Method -> "Bisubstitution"] // InputForm
Out[23]=

PatternSubstitutions (2) 

Include all corresponding pattern substitutions:

In[24]:=
ResourceFunction["MultiReplace"][f[1, 2, 3], f[___, x_, ___] -> x, "PatternSubstitutions" -> True]
Out[24]=

Cosubstitution and Bisubstitution include substitutions of patterns from the expression to subexpressions from left-hand-side of the rule:

In[25]:=
ResourceFunction["MultiReplace"][f[y_, x_], f[z_, b] -> c, Method -> "Cosubstitution", "PatternSubstitutions" -> True]
Out[25]=
In[26]:=
ResourceFunction["MultiReplace"][f[a, x_], f[z_, b] -> c, Method -> "Bisubstitution", "PatternSubstitutions" -> True]
Out[26]=

Properties and Relations (2) 

Replacement is done in all possible ways similar to ReplaceList but at multiple positions:

In[27]:=
ReplaceList[f[a, f[b, c]], f[___, x_, ___] :> g[x]]
Out[27]=
In[28]:=
ResourceFunction["MultiReplace"][f[a, f[b, c]], f[___, x_, ___] :> g[x]]
Out[28]=

SequenceReplace and SubsetReplace replace all the matches and destroy subexpressions, while MultiReplace does all possible single replacements and preserves subexpressions:

In[29]:=
SequenceReplace[{a, b, x, x, a, c}, {a, e_} :> f[e]]
Out[29]=
In[30]:=
SubsetReplace[{a, b, x, x, a, c}, {a, e_} :> f[e]]
Out[30]=
In[31]:=
ResourceFunction["MultiReplace"][{a, b, x, x, a, c}, {a, e_} :> f[e]]
Out[31]=

Version History

  • 2.2.3 – 05 January 2024
  • 2.2.2 – 27 September 2023
  • 2.2.1 – 22 February 2023
  • 2.2.0 – 03 February 2023
  • 2.1.0 – 15 June 2022
  • 2.0.0 – 01 February 2022
  • 1.0.0 – 08 November 2021

Related Resources

License Information