<doc>
	<legacy_id>2401</legacy_id>
	<name>filter</name>
	<type>command</type>

	<syntax>
		<example>filter [lines of | items of] <i>container</i> {with | without | [not] matching} [wildcard pattern | regex pattern] <i>filterPattern</i> [into <i>targetContainer</i>]</example>
	</syntax>

	<synonyms>
	</synonyms>

	<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.</summary>

	<examples>
<example>filter myVariable without "*[a-zA-Z]*"</example>
<example>filter items of field 22 with regex pattern "b.*"</example>
<example><p>filter lines of theList not matching "foo*" into theFilteredList</p></example>
<example>filter field "my lines" matching wildcard pattern "[" &amp; mySelection &amp; "]"</example>
	</examples>

	<history>
		<introduced version="1.0">Added.</introduced>
		<deprecated version=""></deprecated>
		<removed version=""></removed>
		<changed version="2.1.1">2.1.1</changed>
<changed version="6.1">6.1</changed>
		<experimental version=""></experimental>
		<nonexperimental version=""></nonexperimental>
	</history>

	<objects>
	</objects>

	<platforms>
		<mac/>
		<windows/>
		<linux/>
		<ios/>
		<android/>
	</platforms>

	<classes>
		<desktop/>
		<server/>
		<web/>
		<mobile/>
	</classes>

	<security>
	</security>


	<classification>
		<category>Text and Data Processing</category>
	</classification>

	<references>
		<function tag="matchChunk">matchChunk Function</function>
		<function tag="matchText">matchText Function</function>
		<function tag="replaceText">replaceText Function</function>
		<command tag="replace">replace Command</command>
		<command tag="sort">sort Command</command>
		<property tag="caseSensitive">caseSensitive Property</property>
	</references>

	<description>
	<overview>Use the <b>filter</b> command to pick specific lines or items in a container or expression.</overview>

		<parameters>
<parameter>
<name>container</name>
<description>A reference to or an expression that evaluates to a container.</description>
</parameter>
<parameter>
<name>filterPattern</name>
<description>An expression used to match certain lines or items.</description>
</parameter>		</parameters>

	<value></value>
	<comments>The <b>filter</b>...with form and the <b>filter</b>...matching form retain the lines or items that contain a match for the specified <i>filterPattern</i>.<p></p><p>The <b>filter</b>...without form and the <b>filter</b>...not matching form discard the lines or items that do not contain a match for the specified <i>filterPattern</i>.</p><p></p><p>If you don't specify lines or items, all lines of the container are filtered.</p><p></p><p>If a regex pattern is specified, the <i>filterPattern</i> evaluates to a regular expression.</p><p></p><p>If a wildcard <i>filterPattern</i> is specified, the <i>filterPattern</i> consists of a string of characters to match, which may be combined with any number of the following special characters:</p><p></p><p>* - Matches zero or more of any character. The filterPattern A*C matches "AC", "ABC", or "ADZXC".</p><p>? - Matches exactly one character. The filterPattern A?C matches "ABC", but not "AC" or "ADZXC".</p><p>[chars] - Matches any one of the characters inside the brackets. The filterPattern A[BC]D matches "ABD" or "ACD", but not "AD" or "ABCD".</p><p>[char-char] - Matches any character whose ASCII value is between the first character and the second character.</p><p></p><p>If no <i>filterPattern</i> type is specified, the filterPattern is handled as a wildcard.</p><p></p><p>If no <i>targetContainer</i> is specified, and you filter a container, the container contents will be replaced by the filtered result.</p><p></p><p>If you filter a string without a <i>targetContainer</i>, the filtered string will be placed in the <keyword tag="it">it variable</keyword>.</p><p></p><p><change></p><p>The <b>filter</b>...without form was added in version 2.1.1. In previous versions, the <b>filter</b> command could be used only to retrieve lines that matched a wildcard expression.<p>The <b>filter</b> items... form was added in version 6.1. In previous versions, the <b>filter</b> command could be used only to retrieve lines.</change><p>The ability to filter using a regular expression was added in version 6.1. In previous versions, the <b>filter</b> command only supported wildcard expressions.</p><p>The ability to filter an expression was added in version 6.1. In previous versions, the <b>filter</b> command could be used only for a container.</p><p>The <b>filter</b>...[not] matching form was added in version 6.1 to clarify the pattern handling.</p><p>The <b>filter</b>...into form was added in version 6.1. In previous versions, the filter command always replaced the contents of the original container.</p></comments>
	</description>
</doc>