KeyValuePattern
KeyValuePattern[{patt1,…}]
is a pattern object that represents an association or list of rules that includes elements matching each of the patti.
Details
- The patti are often of the form keyivali but can be any pattern.
- Elements matching the patti can appear in any order in the association or list of rules.
- The patti are matched in the order they appear.
- Each of the patti is taken to match a different element of the association or list of rules.
- For a single pattern patt, KeyValuePattern[patt] is equivalent to KeyValuePattern[{patt}].
- KeyValuePattern[{}] matches any association or list of rules.
Examples
open all close allBasic Examples (3)
KeyValuePattern lets you match any element in an association:
MatchQ[<|a -> 1, b -> 2, c -> 3|>, KeyValuePattern[b -> 2]]It also works on lists of rules:
MatchQ[{a -> 1, b -> 2, c -> 3}, KeyValuePattern[b -> 2]]KeyValuePattern matches elements that appear anywhere in an association:
Replace[<|a -> 1, b -> 2, c -> 3|>, KeyValuePattern[{a -> x_, c -> y_}] -> {x, y}]Match any association with two entries:
MatchQ[<|a -> 1, b -> 2|>, KeyValuePattern[{_, _}]]Scope (6)
KeyValuePattern distinguishes Rule and RuleDelayed:
MatchQ[<|a -> 1|>, KeyValuePattern[{a :> 1}]]Extract the key from an Association that matches a rule:
ReplaceAll[<|a -> 1, b -> 2, c -> 3|>, KeyValuePattern[{x_ -> 1}] :> x]Extract a rule based on a condition:
ReplaceAll[<|a -> 1, b -> 2|>, KeyValuePattern[{x_ -> y_ ? EvenQ}] :> (x -> y)]Every rule in Association is matched at most once:
ReplaceAll[<|a -> 1, b -> 2, c -> 3|>, KeyValuePattern[{_ -> x_, _ -> y_}] :> {x, y}]A single pattern in KeyValuePattern does not need to be in a List:
MatchQ[<|a -> 1|>, KeyValuePattern[x_ -> y_]]MatchQ[<|a -> 1|>, KeyValuePattern[{x_ -> y_}]]An empty KeyValuePattern matches any association or list of rules:
MatchQ[<||>, KeyValuePattern[{}]]MatchQ[<|a -> 1|>, KeyValuePattern[{}]]MatchQ[{}, KeyValuePattern[{}]]MatchQ[{a -> 1}, KeyValuePattern[{}]]Applications (1)
Apply a filter to a list of associations:
Cases[{
<|"PartOfSpeech" -> "Noun", "Number" -> "Singular"|>,
<|"PartOfSpeech" -> "Verb"|>},
KeyValuePattern[{"PartOfSpeech" -> "Noun"}]]This works similarly to the following:
Select[{<|"PartOfSpeech" -> "Noun", "Number" -> "Singular"|>, <|"PartOfSpeech" -> "Verb"|>}, #PartOfSpeech == "Noun"&]Properties & Relations (3)
KeyValuePattern matches in any order:
MatchQ[<|a -> 1, b -> 2|>, KeyValuePattern[{_ -> 2, _ -> 1}]]A pattern containing an Association matches rules in exact order:
MatchQ[<|a -> 1, b -> 2|>, <|_ -> 2, _ -> 1|>]An expression matched by KeyValuePattern may contain other rules besides those specified:
MatchQ[<|a -> 1, b -> 2|>, KeyValuePattern[{a -> _}]]A pattern containing an Association will attempt to match against all rules:
MatchQ[<|a -> 1, b -> 2|>, Association[a -> _]]MatchQ[<|a -> 1, b -> 2|>, Association[a -> _, b -> _]]BlankNullSequence in KeyValuePattern matches only a single rule:
ReplaceAll[<|a -> 1, b -> 2, c -> 3|>, KeyValuePattern[{x___, y_}] :> {{x}, {y}}]In a pattern containing an Association, BlankNullSequence may match more than one rule:
ReplaceAll[<|a -> 1, b -> 2, c -> 3|>, Association[x___, y_] :> {{x}, {y}}]Possible Issues (4)
Every pattern in KeyValuePattern may match only one rule:
ReplaceAll[<|a -> 1, b -> 2, c -> 3|>, KeyValuePattern[{x___}] :> {x}]ReplaceAll[<|a -> 1, b -> 2, c -> 3|>, KeyValuePattern[{x_, y__}] :> {x, y}]Empty list or Association can be matched by BlankNullSequence or RepeatedNull patterns:
MatchQ[<||>, KeyValuePattern[{___}]]MatchQ[{}, KeyValuePattern[{(_)...}]]KeyValuePattern matches only an Association or a list of rules, even if no patterns are specified:
MatchQ[{a}, KeyValuePattern[{}]]MatchQ[{a}, KeyValuePattern[{_}]]MatchQ[{a -> b}, KeyValuePattern[{}]]KeyValuePattern will not match RuleDelayed if Rule is specified:
MatchQ[<|"key" :> 1|>, KeyValuePattern["key" -> _]]MatchQ[<|"key" :> 1|>, KeyValuePattern["key" :> _]]Text
Wolfram Research (2016), KeyValuePattern, Wolfram Language function, https://reference.wolfram.com/language/ref/KeyValuePattern.html.
CMS
Wolfram Language. 2016. "KeyValuePattern." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/KeyValuePattern.html.
APA
Wolfram Language. (2016). KeyValuePattern. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/KeyValuePattern.html