Name

filter — Filter a list by matching and extracting patterns

Syntax

filter(list, regex)
filter(list, regex, translation)
              

The FILTER function has the following arguments:

list

A list to be filtered

regex

A regular expression that will be used to select elements from the list

translation

(Optional) A template string that translates the matched string value in to the value added to the output list.

Description

The filter command selects elements from an input list and copies the matched items to the output list. Each element in the input list is converted to a string value and tested against the regular expression. If a match is found the element will be copied to the output list. If a translation template is provided then the matched item is translated prior to adding to the output list.

The translation template contains characters and substitution symbols that will be used to derive the output value. Substitution symbols are digits enclosed by braces (e.g. {1}). The numbers in the substitution symbols refer to the corresponding match group within the regular expression. Substitution symbol {1} refers to the first match group. Substitution symbol {0} refers to the entire matched sequence. Consider the following expression:

filter({'a1','abc45','99','a'},'\w*(\d+)','v={1}')

The regular expression contains a match group to capture all numeric characters that follow an optional sequence of letters. The translation string contains a the string 'v=' followed by a reference to the first match group. The resulting list will contain the sequence

{'v=1','v=45','v=99'}

Note that list element 'a' does not match with the regular expression and is not copied to the output.

Multiple match groups are allowed, but it is an error to refer to a non-existent match group. Match group references may be repeated multiple times.

The resulting list will contain string values.

Examples

Formula

Description

Result

filter({'a','b','c','a'},'a')Filter the list for an exact match{'a', 'a'}
filter({'bat','cat','bag'},'.*at')Filter the list for a matching suffix{'bat','cat'}
filter({'%f.Seral.old'},'.*Seral.(.*)','{1}')Filter a list and translate the output{'old'}