Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

 KeyReplace

Source Notebook

Replace keys in an association

Contributed by: Richard Hennigan (Wolfram Research)

ResourceFunction["KeyReplace"][assoc,rules]

applies a rule or list of rules in an attempt to transform the keys of assoc.

ResourceFunction["KeyReplace"][assoc,rules,levelspec]

applies rules to keys at levels specified by levelspec.

ResourceFunction["KeyReplace"][rules]

represents an operator form of KeyReplace that can be applied to an expression.

Details and Options

The rules must be of the form lhs→rhs or lhs⧴rhs.
A list of rules can be given. The rules are tried in order. The result of the first one that applies is returned. If none of the rules apply, the original assoc is returned.
Delayed rules defined with ⧴ can contain /; conditions.
KeyReplace uses standard level specifications:
nlevels 1 through n
Infinitylevels 1 through Infinity
Allall levels, including zero
{n}level n only
{n1,n2}levels n1 through n2
The default value for levelspec in KeyReplace is {0}, corresponding to the whole expression.
A positive level n consists of all parts of assoc specified by n indices.
A negative level -n consists of all parts of assoc with depth n.
Level -1 consists of numbers, symbols and other objects that do not have subparts.
If levelspec includes multiple levels, expressions at deeper levels in a given subexpression are matched first.
With the option setting Heads→True, KeyReplace includes heads of expressions and their parts.
Replacements are performed to parts specified by levelspec even when those parts have Hold or related wrappers.
KeyReplace[rules][expr] is equivalent to KeyReplace[expr,rules].

Examples

Basic Examples (6) 

Replace a key in an Association:

In[1]:=
ResourceFunction["KeyReplace"][<|"a" -> 1, "b" -> 2|>, "a" -> "A"]
Out[1]=

Replace a key in a list of rules:

In[2]:=
ResourceFunction["KeyReplace"][{"a" -> 1, "b" -> 2}, "a" -> "A"]
Out[2]=

Replace multiple keys:

In[3]:=
ResourceFunction[ "KeyReplace"][<|"a" -> 1, "b" -> 2|>, {"a" -> "A", "b" -> "B"}]
Out[3]=

Use the operator form of KeyReplace:

In[4]:=
ResourceFunction["KeyReplace"][{"a" -> "A", "b" -> "B"}][<|"a" -> 1, "b" -> 2|>]
Out[4]=

Replace keys at deeper levels in the expression:

In[5]:=
ResourceFunction["KeyReplace"][<|"a" -> <|"b" -> 2|>|>, "b" -> "B", {1}]
Out[5]=

Use RuleDelayed to replace keys without evaluation:

In[6]:=
ResourceFunction["KeyReplace"][<|"a" -> 1, "b" -> 2|>, "a" :> Echo["A"]]
Out[6]=

Scope (3) 

Retrieve the ResourceFunction:

In[7]:=
ResourceFunction["KeyReplace"]
Out[7]=

Retrieve the ResourceObject:

In[8]:=
ResourceObject["KeyReplace"]
Out[8]=

Use patterns for key replacements:

In[9]:=
ResourceFunction["KeyReplace"][<|f[1] -> 2, g[2] -> 3|>, f[x_] :> g[x]]
Out[9]=

Applications (1) 

Rename keys in data:

In[10]:=
SystemInformation["Small"]
Out[10]=
In[11]:=
ResourceFunction[ "KeyReplace"][%, {"SystemID" -> "Platform", "ReleaseID" -> "Version"}, 2]
Out[11]=

Properties and Relations (2) 

KeyReplace avoids unpacking/evaluating initialized associations:

In[12]:=
assoc = Block[{Print, Echo}, <|Print["a"] -> Echo[1]|>]
Out[12]=
In[13]:=
ResourceFunction["KeyReplace"][assoc, HoldPattern[Print[x_]] :> Echo[x]]
Out[13]=

This avoids potentially undesired evaluation leaks in some other methods:

In[14]:=
KeyMap[Replace[HoldPattern[Print[x_]] :> Echo[x]], assoc]
Out[14]=

Possible Issues (2) 

When multiple keys match a given pattern, only the first key that matches is replaced:

In[15]:=
ResourceFunction["KeyReplace"][{"a" -> 1, "b" -> 2}, s_?LowerCaseQ :> ToUpperCase[s]]
Out[15]=

Replacements may need to be repeated in order to get all the keys:

In[16]:=
FixedPoint[ ResourceFunction["KeyReplace"][ s_?LowerCaseQ :> ToUpperCase[s]], {"a" -> 1, "b" -> 2}]
Out[16]=

Requirements

Wolfram Language 11.3 (March 2018) or above

Version History

  • 1.0.0 – 31 August 2018

Related Resources

License Information