Name: filter

Type: command

Syntax: filter [lines of | items of] <container> {with | without | [not] matching} [wildcard pattern | regex pattern] <filterPattern> [into <targetContainer>]

Summary: Filters each line or item in a source container or expression, removing the lines or items that do or don't match a pattern.

Introduced: 1.0

OS: mac,windows,linux,ios,android

Platforms: desktop,server,web,mobile

Example:
filter myVariable without "*[a-zA-Z]*"

Example:
filter items of field 22 with regex pattern "b.*"

Example:
filter lines of theList not matching "foo*" into theFilteredList

Example:
filter field "my lines" matching wildcard pattern "[" & mySelection & "]"

Parameters:
container: A reference to or an expression that evaluates to a container.
filterPattern: An expression used to match certain lines or items.
targetContainer: 

It: If you filter a string without a <targetContainer>, the filtered string will be placed in the <it variable>.

Description:
Use the <filter> command to pick specific lines or items in a container or expression.

The <filter>...with form and the <filter>...matching form retain the lines or items that contain a match for the specified <filterPattern>.

The <filter>...without form and the <filter>...not matching form discard the lines or items that do not contain a match for the specified <filterPattern>.

If you don't specify lines or items, all lines of the container are filtered.

If a regex pattern is specified, the <filterPattern> evaluates to a regular expression.

If a wildcard <filterPattern> is specified, the <filterPattern> consists of a string of characters to match, which may be combined with any number of the following special characters:

* - Matches zero or more of any character. The filterPattern A*C matches "AC", "ABC", or "ADZXC".
? - Matches exactly one character. The filterPattern A?C matches "ABC", but not "AC" or "ADZXC".
[chars] - Matches any one of the characters inside the brackets. The filterPattern A[BC]D matches "ABD" or "ACD", but not "AD" or "ABCD".
[char-char] - Matches any character whose ASCII value is between the first character and the second character.

If no <filterPattern> type is specified, the filterPattern is handled as a wildcard.

If no <targetContainer> is specified, and you filter a container, the container contents will be replaced by the filtered result.

The ability to filter using a regular expression was added in version 6.1. In previous versions, the <filter> command only supported wildcard expressions.
The ability to filter an expression was added in version 6.1. In previous versions, the <filter> command could be used only for a container.
The <filter>...[not] matching form was added in version 6.1 to clarify the pattern handling.
The <filter>...into form was added in version 6.1. In previous versions, the filter command always replaced the contents of the original container.

Changes:
The <filter>...without form was added in version 2.1.1. In previous versions, the <filter> command could be used only to retrieve lines that matched a wildcard expression.
The <filter> items... form was added in version 6.1. In previous versions, the <filter> command could be used only to retrieve lines.

References: caseSensitive (property), it variable (keyword), replace (command), sort (command), matchChunk (function), matchText (function), replaceText (function)

Tags: text processing
