Function Repository Resource:

GroupCases

Source Notebook

Group elements of a list using patterns

Contributed by: Sjoerd Smit

ResourceFunction["GroupCases"][{e₁,e₂,…},patt]

groups the e_i by whether or not they match patt and returns the Association <|patt→{…}, _→{…}|>.

ResourceFunction["GroupCases"][{e₁,e₂,…},patt⧴rhs]

applies a transformation to the elements that match patt.

ResourceFunction["GroupCases"][list, {spec₁,spec₂,…}]

returns <|spec₁→{…},spec₂→{…},_→{…}|>.

ResourceFunction["GroupCases"][list,<|key₁→spec₁,key₂→spec₂,…|>]

returns <|key₁→{…},key₂→{…},_→{…}|>.

ResourceFunction["GroupCases"][spec]

represents an operator form of ResourceFunction["GroupCases"].

Details and Options

Every element of the List will be returned exactly once, grouped according to the first pattern that it matches.

Unless explicit keys are given in the input as in ResourceFunction["GroupCases"][list,<|key₁→spec₁,key₂→spec₂,…|>], every pattern will be included as a key in the returned Association. If the default pattern _ is not already included in the list of patterns, it will be appended at the end.

Examples

Basic Examples (4)

Find all integers and non-integers in a List:

In[1]:=

$ResourceFunction[ "GroupCases"][{1, 2, 3/2, 3., 1 + I, Pi, x}, _Integer]$

Out[1]=

Apply a transformation to the matching elements:

In[2]:=

$ResourceFunction["GroupCases"][{1, 2, 3/2, 3., 1 + I, Pi, x}, i_Integer :> i + Pi]$

Out[2]=

Use multiple patterns to split the values by type:

In[3]:=

$ResourceFunction[ "GroupCases"][{1, 2, 3/2, 3., 1 + I, Pi, x}, {_Integer, _Rational, _Real, _Complex , _?NumericQ}]$

Out[3]=

Transformations can mixed with normal patterns:

In[4]:=

$ResourceFunction[ "GroupCases"][{1, 2, 3/2, 3., 1 + I, Pi, x}, {i_Integer :> i + Pi, _Rational, _Real, _Complex , _?NumericQ}]$

Out[4]=

Scope (2)

Define custom keys for labeling the returned values:

In[5]:=

$ResourceFunction["GroupCases"][{1, 2, 3/2, 3., 1 + I, Pi, x}, <|"Int" -> _Integer, "Frac" -> _Rational, "Float" -> _Real, "Complex" -> _Complex , "Num" -> _?NumericQ, "NAN" -> _|> ]$

Out[5]=

Replacement rules can also be labeled:

In[6]:=

$ResourceFunction["GroupCases"][{1, 2, 3/2, 3., 1 + I, Pi, x}, <|"Int" -> i_Integer :> i + Pi, "Frac" -> _Rational, "Float" -> _Real, "Complex" -> _Complex , "Num" -> _?NumericQ, "NAN" -> _|> ]$

Out[6]=

GroupCases can be defined as an operator:

In[7]:=

$splitNums = ResourceFunction["GroupCases"][ <|"Int" -> _Integer, "Frac" -> _Rational, "Float" -> _Real, "Complex" -> _Complex , "Num" -> _?NumericQ, "NAN" -> _|> ]; splitNums@{1, 2, 3/2, 3., 1 + I, Pi, x}$

Out[8]=

Properties and Relations (2)

GroupCases always matches each element exactly once and all elements are returned under one of the keys in the output:

In[9]:=

$list = {1, 2, 3/2, 3., 1 + I, Pi, x}; ResourceFunction["GroupCases"][list, {_Integer, _?NumericQ}]$

Out[10]=

If no transformations are used, the following relation will hold:

In[11]:=

Out[11]=

All specified patterns will be included as a key in the output Association, even if no value is found for that pattern:

In[12]:=

$ResourceFunction["GroupCases"][{1, 2, 3}, {_Integer, _List}]$

Out[12]=

Possible Issues (2)

Matching a List at the first level of the input is only possible by specifying a List of patterns to match. The following will match every element in the input because of ambiguity:

In[13]:=

$ResourceFunction["GroupCases"][{1, {}, {2}, 3}, {___}]$