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]=
Image

Replace a key in a list of rules:

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

Replace multiple keys:

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

Use the operator form of KeyReplace:

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

Replace keys at deeper levels in the expression:

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

Use RuleDelayed to replace keys without evaluation:

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

Scope (3) 

Retrieve the ResourceFunction:

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

Retrieve the ResourceObject:

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

Use patterns for key replacements:

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

Applications (1) 

Rename keys in data:

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

Properties and Relations (2) 

KeyReplace avoids unpacking/evaluating initialized associations:

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

This avoids potentially undesired evaluation leaks in some other methods:

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

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]=
Image

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]=
Image

Requirements

Wolfram Language 11.3 (March 2018) or above

Version History

  • 1.0.0 – 31 August 2018

Related Resources

License Information