--- title: "UpValues" language: "en" type: "Symbol" summary: "UpValues[f] gives a list of transformation rules corresponding to all upvalues (values for g[..., f[...], ...]) defined for the symbol f. UpValues[symbol] gives a list of transformation rules corresponding to all upvalues defined for the symbol named symbol if it exists." keywords: - assignments - definitions - evaluation - symbol table canonical_url: "https://reference.wolfram.com/language/ref/UpValues.html" source: "Wolfram Language Documentation" related_guides: - title: "Assignments" link: "https://reference.wolfram.com/language/guide/Assignments.en.md" - title: "Symbol Handling" link: "https://reference.wolfram.com/language/guide/SymbolHandling.en.md" related_workflows: - title: "Find All Defined Functions" link: "https://reference.wolfram.com/language/workflow/FindAllDefinedFunctions.en.md" - title: "Clear Definitions for Symbols and Functions" link: "https://reference.wolfram.com/language/workflow/ClearDefinitionsForSymbolsAndFunctions.en.md" related_functions: - title: "UpSet" link: "https://reference.wolfram.com/language/ref/UpSet.en.md" - title: "UpSetDelayed" link: "https://reference.wolfram.com/language/ref/UpSetDelayed.en.md" - title: "TagSetDelayed" link: "https://reference.wolfram.com/language/ref/TagSetDelayed.en.md" - title: "TagSet" link: "https://reference.wolfram.com/language/ref/TagSet.en.md" - title: "HoldAllComplete" link: "https://reference.wolfram.com/language/ref/HoldAllComplete.en.md" - title: "DownValues" link: "https://reference.wolfram.com/language/ref/DownValues.en.md" - title: "SubValues" link: "https://reference.wolfram.com/language/ref/SubValues.en.md" - title: "OwnValues" link: "https://reference.wolfram.com/language/ref/OwnValues.en.md" - title: "Information" link: "https://reference.wolfram.com/language/ref/Information.en.md" - title: "ValueQ" link: "https://reference.wolfram.com/language/ref/ValueQ.en.md" - title: "Clear" link: "https://reference.wolfram.com/language/ref/Clear.en.md" - title: "ClearAll" link: "https://reference.wolfram.com/language/ref/ClearAll.en.md" - title: "Save" link: "https://reference.wolfram.com/language/ref/Save.en.md" related_tutorials: - title: "Manipulating Value Lists" link: "https://reference.wolfram.com/language/tutorial/TransformationRulesAndDefinitions.en.md#30951" --- # UpValues UpValues[f] gives a list of transformation rules corresponding to all upvalues (values for g[…, f[…], …]) defined for the symbol f. UpValues["symbol"] gives a list of transformation rules corresponding to all upvalues defined for the symbol named "symbol" if it exists. ## Details and Options * ``UpValues[f]`` also gives rules corresponding to ``g[…, f, …]``. * When evaluating an expression, matching upvalues are applied before matching downvalues. » * If a function has attribute ``HoldAllComplete``, no upvalues are applied prior to entering the body of the function. » * ``UpValues`` are typically defined using ``UpSet``, ``UpSetDelayed``, ``TagSet`` or ``TagSetDelayed``. * You can specify the upvalues for ``f`` by making an assignment of the form ``UpValues[f] = list``. * The list returned by ``UpValues`` has elements of the form ``HoldPattern[lhs] :> rhs``. --- ## Examples (13) ### Basic Examples (1) Define an upvalue for a symbol ``g`` using ``TagSetDelayed`` : ```wl In[1]:= g/:f[g[x_]] := h[x] ``` Define an upvalue using ``UpSetDelayed`` : ```wl In[2]:= f[g] ^:= h[1] ``` These are the upvalues associated with ``g`` : ```wl In[3]:= UpValues[g] Out[3]= {HoldPattern[f[g]] :> h[1], HoldPattern[f[g[x_]]] :> h[x]} ``` ### Scope (3) ``UpValues`` returns rules corresponding to upvalues defined for a symbol: ```wl In[1]:= g/:g[x_] + g[y_] := gplus[x, y] In[2]:= UpValues[g] Out[2]= {HoldPattern[g[x_] + g[y_]] :> gplus[x, y]} ``` --- Create several values: ```wl In[1]:= f[x1] ^= 1;f[x2] ^= 3;f[y] ^= 5; ``` Obtain the upvalues of symbols whose names start with ``x`` : ```wl In[2]:= UpValues /@ Names["x*"] Out[2]= {{HoldPattern[f[x1]] :> 1}, {HoldPattern[f[x2]] :> 3}} ``` --- ``UpValues`` can be used to set the values directly: ```wl In[1]:= UpValues[h] = {h[x_] * h[y_] :> htimes[x, y]}; In[2]:= Definition[h] Out[2]= h[x_] h[y_] ^:= htimes[x, y] In[3]:= h[a] h[b] Out[3]= htimes[a, b] ``` ### Applications (2) The resulting rules are in the order given: ```wl In[1]:= x/:x + y_ /; y > -2 := f[y] x/:x + y_ /; y < 2 := g[y] In[2]:= UpValues[x] Out[2]= {HoldPattern[x + y_ /; y > -2] :> f[y], HoldPattern[x + y_ /; y < 2] :> g[y]} In[3]:= x + 1 Out[3]= f[1] ``` Now reorder the definitions: ```wl In[4]:= UpValues[x] = Reverse[UpValues[x]] Out[4]= {HoldPattern[x + y_ /; y < 2] :> g[y], HoldPattern[x + y_ /; y > -2] :> f[y]} In[5]:= x + 1 Out[5]= g[1] ``` --- Copy a symbol's definitions to another symbol: ```wl In[1]:= g/:g[x_] + g[y_] := plus[x, y] In[2]:= UpValues[h] = UpValues[g] /. g -> h Out[2]= {HoldPattern[h[x_] + h[y_]] :> plus[x, y]} In[3]:= h[a] + h[b] Out[3]= plus[a, b] In[4]:= % == g[a] + g[b] Out[4]= True ``` ### Properties & Relations (7) Values can be defined by immediate or delayed assignments: ```wl In[1]:= g/:f[g[_]] = 17; g/:h[g[x_]] := h[x]; In[2]:= UpValues[g] Out[2]= {HoldPattern[f[g[_]]] :> 17, HoldPattern[h[g[x_]]] :> h[x]} ``` --- ``HoldPattern`` is used to protect the rules from their own definitions: ```wl In[1]:= g/:f[g[x_]] := h[x] In[2]:= UpValues[g] Out[2]= {HoldPattern[f[g[x_]]] :> h[x]} In[3]:= f[g[x_]] :> h[x] Out[3]= h[x_] :> h[x] ``` --- ``UpValues["sym"]`` will issue a message if the specified symbol does not exist: ```wl In[1]:= UpValues["x"] ``` UpValues::sym: Argument x at position 1 is expected to be a symbol. ```wl Out[1]= UpValues["x"] ``` If the symbol exists but has no definitions, an empty list is returned: ```wl In[2]:= x; UpValues["x"] Out[2]= {} ``` --- ``Definition`` and ``Information`` display upvalues but do not return them as values: ```wl In[1]:= g/:f[g[x_]] := h[x] In[2]:= Definition[g] Out[2]= f[g[x_]] ^:= h[x] In[3]:= %//FullForm Out[3]//FullForm= Definition[g] ``` ``UpValues`` returns a value that can be used in a program: ```wl In[4]:= UpValues[g] Out[4]= {HoldPattern[f[g[x_]]] :> h[x]} ``` --- Evaluation of an expression involves applying matching upvalues: ```wl In[1]:= g/:f[g[x_]] := h[x] In[2]:= Hold[f[g[a]]] /. UpValues[g] Out[2]= Hold[h[a]] ``` --- Matching upvalues are used before matching downvalues in evaluation: ```wl In[1]:= f[g[x_]] ^:= h[x] In[2]:= f[x_] := 1 In[3]:= {UpValues[g], DownValues[f]} Out[3]= {{HoldPattern[f[g[x_]]] :> h[x]}, {HoldPattern[f[x_]] :> 1}} ``` The upvalue for ``g`` is used prior to the downvalue for ``f`` : ```wl In[4]:= f[g[2]] Out[4]= h[2] ``` Compare with a manual application of the upvalue and downvalue: ```wl In[5]:= HoldComplete[f[g[2]]] /. UpValues[g] Out[5]= HoldComplete[h[2]] In[6]:= HoldComplete[f[g[2]]] /. DownValues[f] Out[6]= HoldComplete[1] ``` --- Define an upvalue for ``g`` that applies for all heads: ```wl In[1]:= _[g[x_]] ^= 1 Out[1]= 1 In[2]:= UpValues[g] Out[2]= {HoldPattern[_[g[x_]]] :> 1} ``` Even if a function has attribute ``HoldAll``, the upvalue will be applied during evaluation: ```wl In[3]:= Hold[g[x]] Out[3]= 1 ``` If a function has attribute ``HoldAllComplete``, the upvalue will not be applied: ```wl In[4]:= HoldComplete[g[x]] Out[4]= HoldComplete[g[x]] ``` ## See Also * [`UpSet`](https://reference.wolfram.com/language/ref/UpSet.en.md) * [`UpSetDelayed`](https://reference.wolfram.com/language/ref/UpSetDelayed.en.md) * [`TagSetDelayed`](https://reference.wolfram.com/language/ref/TagSetDelayed.en.md) * [`TagSet`](https://reference.wolfram.com/language/ref/TagSet.en.md) * [`HoldAllComplete`](https://reference.wolfram.com/language/ref/HoldAllComplete.en.md) * [`DownValues`](https://reference.wolfram.com/language/ref/DownValues.en.md) * [`SubValues`](https://reference.wolfram.com/language/ref/SubValues.en.md) * [`OwnValues`](https://reference.wolfram.com/language/ref/OwnValues.en.md) * [`Information`](https://reference.wolfram.com/language/ref/Information.en.md) * [`ValueQ`](https://reference.wolfram.com/language/ref/ValueQ.en.md) * [`Clear`](https://reference.wolfram.com/language/ref/Clear.en.md) * [`ClearAll`](https://reference.wolfram.com/language/ref/ClearAll.en.md) * [`Save`](https://reference.wolfram.com/language/ref/Save.en.md) ## Tech Notes * [Manipulating Value Lists](https://reference.wolfram.com/language/tutorial/TransformationRulesAndDefinitions.en.md#30951) ## Related Guides * [`Assignments`](https://reference.wolfram.com/language/guide/Assignments.en.md) * [Symbol Handling](https://reference.wolfram.com/language/guide/SymbolHandling.en.md) ## Related Workflows * [Find All Defined Functions](https://reference.wolfram.com/language/workflow/FindAllDefinedFunctions.en.md) * [Clear Definitions for Symbols and Functions](https://reference.wolfram.com/language/workflow/ClearDefinitionsForSymbolsAndFunctions.en.md) ## History * Introduced in 1991 (2.0) \| Updated in 1996 (3.0)