Wolfram Computation Meets Knowledge

KeyReplace

Contributed by: Richard Hennigan (Wolfram Research)

Replace keys in an association

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 lhsrhs 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:
n levels 1 through n
Infinity levels 1 through Infinity
All all levels, including zero
{ n } level n only
{ n 1 , n 2 } 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 HeadsTrue,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

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

More Examples

Scope

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

Rename keys in data:

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

Properties and Relations

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

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

Resource History