--- title: "Rule" language: "en" type: "Symbol" summary: "lhs -> rhs or lhs -> rhs represents a rule that transforms lhs to rhs." keywords: - arrow - immediate rules - replacements - lexical scoping - local scoping - -> canonical_url: "https://reference.wolfram.com/language/ref/Rule.html" source: "Wolfram Language Documentation" related_guides: - title: "Rules" link: "https://reference.wolfram.com/language/guide/Rules.en.md" - title: "Rules & Patterns" link: "https://reference.wolfram.com/language/guide/RulesAndPatterns.en.md" - title: "Scoping Constructs" link: "https://reference.wolfram.com/language/guide/ScopingConstructs.en.md" - title: "Wolfram Language Syntax" link: "https://reference.wolfram.com/language/guide/Syntax.en.md" - title: "Language Overview" link: "https://reference.wolfram.com/language/guide/LanguageOverview.en.md" - title: "Options Management" link: "https://reference.wolfram.com/language/guide/OptionsManagement.en.md" - title: "Programmable Linguistic Interface" link: "https://reference.wolfram.com/language/guide/ProgrammableLinguisticInterface.en.md" - title: "Expressions" link: "https://reference.wolfram.com/language/guide/Expressions.en.md" related_tutorials: - title: "Applying Transformation Rules" link: "https://reference.wolfram.com/language/tutorial/TransformationRulesAndDefinitions.en.md#18035" - title: "Some General Notations and Conventions" link: "https://reference.wolfram.com/language/tutorial/SomeGeneralNotationsAndConventions.en.md" - title: "Variables in Pure Functions and Rules" link: "https://reference.wolfram.com/language/tutorial/ModularityAndTheNamingOfThings.en.md#1131" - title: "Implementation notes: Basic System Features" link: "https://reference.wolfram.com/language/tutorial/SomeNotesOnInternalImplementation.en.md#16446" --- # Rule (->, ->) lhs -> rhs or lhs -> rhs represents a rule that transforms lhs to rhs. ## Details * Rules are very general constructs that can represent transformation, subcasing, correspondence and other relations between expressions. * The character `` -> `` can be entered as esc`` -> ``esc or [`∖[Rule]`](https://reference.wolfram.com/language/ref/character/Rule.en.md). * ``lhs -> rhs`` evaluates ``rhs`` immediately. * You can apply rules using ``Replace``. * The assignment ``lhs = rhs`` specifies that the rule ``lhs -> rhs`` should be used whenever it applies. * In ``StandardForm``, ``Rule`` is printed using `` -> ``. * Symbols that occur as pattern names in ``lhs`` are treated as local to the rule. This is true when the symbols appear on the right‐hand side of `` /; `` conditions in ``lhs``, and when the symbols appear anywhere in ``rhs``, even inside other scoping constructs. * ``Rule`` constructs can be nested in any way. ``Rule`` is treated as a scoping construct, so that inner variables are renamed if necessary. --- ## Background & Context ``Rule`` represents a rule that transforms one expression to another. The expression ``Rule[lhs, rhs]`` is commonly written and displayed using the shorthand syntax $$\text{\textit{lhs}}\text{-$>$}\text{\textit{rhs}}$$`` or ``$$\text{\textit{lhs}}\to \text{\textit{rhs}}$$``. Rule-based programming is an extremely powerful paradigm that allows many programs to be written both compactly and lucidly. A rule often contains patterns on the ``lhs`` that are replaced with appropriately transformed versions as indicated on the ``rhs``, e.g. ``$$\text{\textit{x$\_$}}\text{-$>$}\text{\textit{$x$}}{}^{\wedge}2$$``. Note, however, that ``$$\text{\textit{lhs}}\text{-$>$}\text{\textit{rhs}}$$ evaluates ``rhs`` immediately, so in situations where ``rhs`` should be evaluated only after the rule is used, ``RuleDelayed`` (written in shorthand as `` :> `` or `` :> ``) should be used instead. ``Rule`` replacement can be performed using functions like ``Replace``, ``ReplaceAll``, ``ReplaceRepeated``, ``ReplaceList``, ``ReplacePart``, and ``StringReplace``. Many functions in the Wolfram Language return their results as lists of rules, including ``Solve``, ``FindInstance``, and ``FindRoot``, e.g. ``Solve[x ^ 2 - 1 == 0, x]`` returns ``{{x -> -1}, {x -> 1}}``. This form is useful since it both keeps solutions associated with their respective variables (especially in the multivariate case) and allows convenient backsubstitution of the solutions in terms of the original variables via ``ReplaceAll`` or related functions. --- ## Examples (6) ### Basic Examples (1) Use a rule that replaces ``x`` by 3: ```wl In[1]:= {x, x ^ 2, a, b} /. x -> 3 Out[1]= {3, 9, a, b} ``` ### Scope (1) Any expression or pattern can appear in a rule: ```wl In[1]:= {x, x ^ 2, x ^ 3, a, b} /. x ^ 2 -> y Out[1]= {x, y, x^3, a, b} In[2]:= {x, x ^ 2, x ^ 3, a, b} /. x ^ n_ -> f[n] Out[2]= {x, f[2], f[3], a, b} ``` ### Properties & Relations (4) `` -> `` evaluates when it is first entered; `` :> `` when it is used: ```wl In[1]:= {x, x, x, x} /. x -> RandomReal[] Out[1]= {0.526621, 0.526621, 0.526621, 0.526621} In[2]:= {x, x, x, x} /. x :> RandomReal[] Out[2]= {0.123567, 0.815383, 0.768442, 0.930826} ``` --- `` -> `` groups to the right: ```wl In[1]:= x -> y -> z//FullForm Out[1]//FullForm= Rule[x, Rule[y, z]] In[2]:= x /. x -> y -> z Out[2]= y -> z ``` --- ``KeyValuePattern`` can be used to transform a list of rules: ```wl In[1]:= Replace[{a -> 1, b -> 2, c -> 3}, KeyValuePattern[{a -> x_, c -> y_}] -> {a -> f[x], c -> g[y]}] Out[1]= {a -> f[1], c -> g[3]} ``` --- ``KeyValuePattern`` distinguishes between ``Rule`` and ``RuleDelayed`` : ```wl In[1]:= Replace[{a -> 1, b -> 2, c -> 3}, KeyValuePattern[{a :> x_, c :> y_}] -> {a -> f[x], c -> g[y]}] Out[1]= {a -> 1, b -> 2, c -> 3} ``` ## See Also * [`RuleDelayed`](https://reference.wolfram.com/language/ref/RuleDelayed.en.md) * [`TwoWayRule`](https://reference.wolfram.com/language/ref/TwoWayRule.en.md) * [`DirectedEdge`](https://reference.wolfram.com/language/ref/DirectedEdge.en.md) * [`Replace`](https://reference.wolfram.com/language/ref/Replace.en.md) * [`ReplaceAll`](https://reference.wolfram.com/language/ref/ReplaceAll.en.md) * [`Set`](https://reference.wolfram.com/language/ref/Set.en.md) * [`Keys`](https://reference.wolfram.com/language/ref/Keys.en.md) * [`Values`](https://reference.wolfram.com/language/ref/Values.en.md) * [`Association`](https://reference.wolfram.com/language/ref/Association.en.md) * [`Lookup`](https://reference.wolfram.com/language/ref/Lookup.en.md) * [`KeyValuePattern`](https://reference.wolfram.com/language/ref/KeyValuePattern.en.md) * [`ArgumentsOptions`](https://reference.wolfram.com/language/ref/ArgumentsOptions.en.md) * [`PolynomialReduce`](https://reference.wolfram.com/language/ref/PolynomialReduce.en.md) * [`\[Rule]`](https://reference.wolfram.com/language/ref/character/Rule.en.md) ## Tech Notes * [Applying Transformation Rules](https://reference.wolfram.com/language/tutorial/TransformationRulesAndDefinitions.en.md#18035) * [Some General Notations and Conventions](https://reference.wolfram.com/language/tutorial/SomeGeneralNotationsAndConventions.en.md) * [Variables in Pure Functions and Rules](https://reference.wolfram.com/language/tutorial/ModularityAndTheNamingOfThings.en.md#1131) * [Implementation notes: Basic System Features](https://reference.wolfram.com/language/tutorial/SomeNotesOnInternalImplementation.en.md#16446) ## Related Guides * [`Rules`](https://reference.wolfram.com/language/guide/Rules.en.md) * [Rules & Patterns](https://reference.wolfram.com/language/guide/RulesAndPatterns.en.md) * [Scoping Constructs](https://reference.wolfram.com/language/guide/ScopingConstructs.en.md) * [Wolfram Language Syntax](https://reference.wolfram.com/language/guide/Syntax.en.md) * [Language Overview](https://reference.wolfram.com/language/guide/LanguageOverview.en.md) * [Options Management](https://reference.wolfram.com/language/guide/OptionsManagement.en.md) * [Programmable Linguistic Interface](https://reference.wolfram.com/language/guide/ProgrammableLinguisticInterface.en.md) * [`Expressions`](https://reference.wolfram.com/language/guide/Expressions.en.md) ## Related Links * [Fast Introduction for Programmers: Patterns](http://www.wolfram.com/language/fast-introduction-for-programmers/patterns/) * [An Elementary Introduction to the Wolfram Language: Options](https://www.wolfram.com/language/elementary-introduction/20-options.html) * [An Elementary Introduction to the Wolfram Language: Graphs and Networks](https://www.wolfram.com/language/elementary-introduction/21-graphs-and-networks.html) * [An Elementary Introduction to the Wolfram Language: Patterns](https://www.wolfram.com/language/elementary-introduction/32-patterns.html) * [An Elementary Introduction to the Wolfram Language: Expressions and Their Structure](https://www.wolfram.com/language/elementary-introduction/33-expressions-and-their-structure.html) * [NKS\|Online](http://www.wolframscience.com/nks/search/?q=Rule) * [A New Kind of Science](http://www.wolframscience.com/nks/) ## History * Introduced in 1988 (1.0) \| Updated in 1996 (3.0)