Skip to content

ReplaceAll

Status: Stable

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

Description

expr /. rules or ReplaceAll[expr, rules] traverses expr top-down and applies the first matching rule at each subexpression. A matched subexpression is replaced and NOT recursed into further -- ReplaceAll is a single pass, not a fixed point.

Examples (10)

Every input below was run against the current Mathilda build and its output recorded.

Basic examples (2)

In[1]:= {x, x^2, y, z} /. x -> 1
Out[1]= {1, 1, y, z}

In[2]:= {f[2], f[x, y], h[], f[]} /. f[x__] -> "OK"
Out[2]= {"OK", "OK", h[], f[]}

Options (2)

In[3]:= Sin[x] /. Sin -> Cos
Out[3]= Cos[x]

In[4]:= {1, 3, 2, x, 6, Pi} /. _?PrimeQ -> "prime"
Out[4]= {1, "prime", "prime", x, 6, Pi}

Applications (6)

In[5]:= x + y /. x -> 2
Out[5]= 2 + y

In[6]:= {x, y, z} /. {x -> 1, z -> 3}
Out[6]= {1, y, 3}

In[7]:= x^2 + x /. x -> a + 1
Out[7]= 1 + a + (1 + a)^2

In[8]:= D[x^x, x] /. Log[x] -> L
Out[8]= x^(-1 + x) (x + L x)

In[9]:= {{1, 2}, {3, 4}} /. {a_, b_} :> a + b
Out[9]= {4, 6}

In[10]:= x^4 + 1 /. x -> Sqrt[2]
Out[10]= 5

Implementation notes

Algorithm. builtin_replace_all (/., in src/replace.c) drives apply_replace_all_nested, which first collects the rule(s) into a flat ReplaceRule[] (pattern, replacement, delayed flag). A List of rules whose first element is not itself a Rule/RuleDelayed is treated as a list of alternative rule-sets and threaded ā€” one result per sub-list. The core traversal is do_replace_all: at each node it tries every rule in order via match(e, rule.pattern, env) (the structural matcher in src/match.c); on the first match it builds the result with replace_bindings(rule.replacement, env) and returns immediately without descending into the matched subexpression ā€” this is the defining top-down, non-re-entrant ReplaceAll semantic. If no rule matches the node, it recurses into the head and every argument and rebuilds the function node. Rule-creation timing (immediate Rule vs delayed RuleDelayed) is honoured by replace_bindings/the surrounding evaluator rather than re-applied here.

Data structures. ReplaceRule array holding borrowed pointers into the user's rule expressions; a fresh MatchEnv (from env_new) per match attempt holds the pattern-variable bindings consumed by replace_bindings.

  • Protected.
  • Evaluates the entire expression top-down. The first rule that applies to a particular part is used; no further rules are tried on that part or on any of its subparts.
  • Applies a rule only once to an expression.
  • Returns expr unmodified if no rules apply.
  • Maps across lists of rules appropriately.
  • Inside an association the rules reach the values only, never the keys: <|a -> 1, b -> 2|> /. b -> a is unchanged. An association is itself a rule set with literal keys: {x, y} /. <|x -> 1|> is {1, y} (see Association atomicity).

Attributes: Protected.

References

Notes & additional examples

Notes

expr /. rules is the shorthand for ReplaceAll[expr, rules]. It traverses expr top-down and rewrites each subexpression that matches a rule's left-hand side. A single rule or a list of rules may be supplied; with a list, the first matching rule wins at each position. Replacement is not re-applied to the result of a match (that is ReplaceRepeated, //.). Patterns with named blanks (f[a_, b_] -> a + b) bind variables for use on the right-hand side.