({{, (RefLink[KeyValuePattern, paclet:ref/KeyValuePattern])[{(Subscript[patt, 1]),…}]
is a pattern object that represents an association or list of rules that includes elements matching each of the (Subscript[patt, i]).}})

OpenersNotesSection(Spacer1)Details

The (Subscript[patt, i]) are often of the form (Subscript[key, i])->(Subscript[val, i]) but can be any pattern.

Elements matching the (Subscript[patt, i]) can appear in any order in the association or list of rules.

The (Subscript[patt, i]) are matched in the order they appear.

Each of the (Subscript[patt, i]) is taken to match a different element of the association or list of rules.

For a single pattern patt, (RefLink[KeyValuePattern, paclet:ref/KeyValuePattern])[patt] is equivalent to (RefLink[KeyValuePattern, paclet:ref/KeyValuePattern])[{patt}].

(RefLink[KeyValuePattern, paclet:ref/KeyValuePattern])[{}] matches any association or list of rules.

OpenersPrimaryExamplesSection(Spacer1)Examples  (16)

OpenersExampleSection0(Spacer1)Basic Examples  (3)

(RefLink[KeyValuePattern, paclet:ref/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]]

(RefLink[KeyValuePattern, paclet:ref/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[{_,_}]]

OpenersExampleSection1(Spacer1)Scope  (6)

(RefLink[KeyValuePattern, paclet:ref/KeyValuePattern]) distinguishes (RefLink[Rule, paclet:ref/Rule]) and (RefLink[RuleDelayed, paclet:ref/RuleDelayed]):

MatchQ[<|a->1|>,KeyValuePattern[{a:>1}]]

Extract the key from an (RefLink[Association, paclet:ref/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 (RefLink[Association, paclet:ref/Association]) is matched at most once:

ReplaceAll[<|a->1,b->2,c->3|>,KeyValuePattern[{_->x_,_->y_}]:>{x,y}]

A single pattern in (RefLink[KeyValuePattern, paclet:ref/KeyValuePattern]) does not need to be in a (RefLink[List, paclet:ref/List]):

MatchQ[<|a->1|>,KeyValuePattern[x_->y_]]

MatchQ[<|a->1|>,KeyValuePattern[{x_->y_}]]

An empty (RefLink[KeyValuePattern, paclet:ref/KeyValuePattern]) matches any association or list of rules:

MatchQ[<||>,KeyValuePattern[{}]]

MatchQ[<|a->1|>,KeyValuePattern[{}]]

MatchQ[{},KeyValuePattern[{}]]

MatchQ[{a->1},KeyValuePattern[{}]]

OpenersExampleSection3(Spacer1)Applications  (1)

Apply a filter to a list of associations:

Cases[{
<|"PartOfSpeech"->"Noun","Number"->"Singular"|>,
<|"PartOfSpeech"->"Verb"|>},
KeyValuePattern[{"PartOfSpeech"->"Noun"}]]

OpenersExampleSection4(Spacer1)Properties & Relations  (3)

(RefLink[KeyValuePattern, paclet:ref/KeyValuePattern]) matches in any order:

MatchQ[<|a->1,b->2|>,KeyValuePattern[{_->2,_->1}]]

A pattern containing an (RefLink[Association, paclet:ref/Association]) matches rules in exact order:

MatchQ[<|a->1,b->2|>,<|_->2,_->1|>]

An expression matched by (RefLink[KeyValuePattern, paclet:ref/KeyValuePattern]) may contain other rules besides those specified:

MatchQ[<|a->1,b->2|>,KeyValuePattern[{a->_}]]

A pattern containing an (RefLink[Association, paclet:ref/Association]) will attempt to match against all rules:

MatchQ[<|a->1,b->2|>,Association[a->_]]

MatchQ[<|a->1,b->2|>,Association[a->_,b->_]]

(RefLink[BlankNullSequence, paclet:ref/BlankNullSequence]) in (RefLink[KeyValuePattern, paclet:ref/KeyValuePattern]) matches only a single rule:

ReplaceAll[<|a->1,b->2,c->3|>,KeyValuePattern[{x___,y_}]:>{{x},{y}}]

In a pattern containing an (RefLink[Association, paclet:ref/Association]), (RefLink[BlankNullSequence, paclet:ref/BlankNullSequence]) may match more than one rule:

ReplaceAll[<|a->1,b->2,c->3|>,Association[x___,y_]:>{{x},{y}}]

OpenersExampleSection5(Spacer1)Possible Issues  (3)

Every pattern in (RefLink[KeyValuePattern, paclet:ref/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 (RefLink[Association, paclet:ref/Association]) can be matched by (RefLink[BlankNullSequence, paclet:ref/BlankNullSequence]) or (RefLink[RepeatedNull, paclet:ref/RepeatedNull]) patterns:

MatchQ[<||>,KeyValuePattern[{___}]]

MatchQ[{},KeyValuePattern[{(_)...}]]

(RefLink[KeyValuePattern, paclet:ref/KeyValuePattern]) matches only an (RefLink[Association, paclet:ref/Association]) or a list of rules, even if no patterns are specified:

MatchQ[{a},KeyValuePattern[{}]]

MatchQ[{a},KeyValuePattern[{_}]]

MatchQ[{a->b},KeyValuePattern[{}]]

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(RefLink[Association, paclet:ref/Association])  ▪  (RefLink[OptionsPattern, paclet:ref/OptionsPattern])  ▪  (RefLink[PatternSequence, paclet:ref/PatternSequence])  ▪  (RefLink[OrderlessPatternSequence, paclet:ref/OrderlessPatternSequence])}})}})

({{DocumentationFooterIconsRelatedTutorial.png, ({{Tutorials}, {▪(RefLinkPlain[Patterns and Transformation Rules, paclet:tutorial/PatternsAndTransformationRules])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Associations, paclet:guide/Associations])}, {▪(RefLinkPlain[Patterns, paclet:guide/Patterns])}})}})