FILTER function

Synopsis
This function filters an array by using a condition on each element, populating the returned array with only elements for which the condition returned true.
Variations
FILTER(SourceArray, Condition)
Extracts an array from the source array by applying the condition to each element and including only the elements that satisfy the condition.
Parameters
SourceArray

Specifies the array from which to extract the elements.

Supported types: Boolean array; String array; Numeric array; Point array; Object array.
Condition

Specifies the condition used on each element to filter the array.

Supported types: Boolean.
Returns
Returned types: Boolean array; String array; Numeric array; Point array; Object array.
Examples
1.

The following example filters the array to include only positive numbers, and the function returns the array [10].

FILTER([-10, 0, 10], Item > 0)
2.

The following example accesses array ArrayData, stored as a variable, and finds the remainder of each index when divided by 2. Since this yields an array of alternating '1's and '0's, [1, 0, 1, 0, 1, ...] the function evaluates this as a set of boolean values, or as the results of a condition statement applied on every element of ArrayData. The function returns the elements from ArrayData which correspond to 'true' results of the condition. So, if variable ArrayData contains the values shown below, this function returns the array of values at positions 1, 3, 5: [91,99,81].

  • ArrayData = [91, 87, 99, 92, 81, 78]

FILTER(Variables.ArrayData, Index MOD 2)
FILTER(SourceArray, Condition, Expression)
Extracts an array from the source array by applying the condition to each element and including only the elements that satisfy the condition. Afterwards, an expression is applied to each element of the filtered array.
Parameters
SourceArray

Specifies the array from which to extract the elements.

Supported types: Boolean array; String array; Numeric array; Point array; Object array.
Condition

Specifies the condition used on each element to filter the array.

Supported types: Boolean.
Expression

Specifies the expression to perform on each element of the array after filtering.

Supported types: Numeric; Boolean; String; Point; Object.
Returns
Returned types: Boolean array; String array; Numeric array; Point array; Object array.
Examples
1.

The following example filters the array to accept only positive values and 0. The expression then adds 5 to each element and the function returns [5, 15, 5, 25, 5, 35].

FILTER([-10, 0, 10, -20, 0, 20, -30, 0, 30], Item >= 0, Item + 5)
FILTER(SourceArray, Condition, Expression, MaxCount)
Extracts an array from the source array by applying the condition to each element and including only the elements that satisfy the condition. When the returned array reaches a maximum size, the function stops testing the remaining elements and returns the array of the specified size.
Parameters
SourceArray

Specifies the array from which to extract the elements.

Supported types: Boolean array; String array; Numeric array; Point array; Object array.
Condition

Specifies the condition used on each element to filter the array.

Supported types: Boolean.
Expression

Specifies the expression to perform on each element of the array after filtering.

Supported types: Numeric; Boolean; String; Point; Object.
MaxCount

Specifies the maximum number of values to include in the returned array. If more elements of the source array satisfy the condition than MaxCount, the function will stop filtering after enough elements are filtered.

Supported types: Numeric.
Returns
Returned types: Boolean array; String array; Numeric array; Point array; Object array.
Examples
1.

The following example filters the array to accept only positive values and 0. However, only 4 values are allowed in the resulting array, so the filtering stops after including 20 in the result. The expression then adds 5 to each element, and the function returns [5, 15, 5, 25].

FILTER([-10, 0, 10, -20, 0, 20, -30, 0, 30], Item >= 0, Item + 5, 4)
FILTER(SourceArray, StartIndex, Count, Condition, Expression)
Extracts an array from a subset of the source array by applying the condition to each element and including only the elements that satisfy the condition. Afterwards, an expression is applied to each element of the filtered array.
Parameters
SourceArray

Specifies the array from which to extract the elements.

Supported types: Boolean array; String array; Numeric array; Point array; Object array.
StartIndex

Specifies the index of the first element of the subset in the source array.

Supported types: Numeric.
Count

Specifies the number of elements (beginning at StartIndex) to include in the subset of the source array.

Supported types: Numeric.
Condition

Specifies the condition used on each element of the subset of SourceArray to filter the array.

Supported types: Boolean.
Expression

Specifies the expression to perform on each element of the array after filtering.

Supported types: Numeric; Boolean; String; Point; Object.
Returns
Returned types: Boolean array; String array; Numeric array; Point array; Object array.
Examples
1.

The following example only accepts positive values and 0 from the subset array specified by the index and count, [-20, 0, 20]. The expression then adds 5 to each element, and the function returns the array [5, 25].

FILTER([-10, 0, 10, -20, 0, 20, -30, 0, 30], 4, 3, Item >= 0, Item + 5)
FILTER(SourceArray, StartIndex, Count, Condition, Expression, MaxCount)
Extracts an array from a subset of the source array by applying the condition to each element and including only the elements that satisfy the condition. When the returned array reaches a maximum size, the function stops testing the remaining elements and returns the array of the specified size. Afterwards, an expression is applied to each element of the filtered array.
Parameters
SourceArray

Specifies the array from which to extract the elements.

Supported types: Boolean array; String array; Numeric array; Point array; Object array.
StartIndex

Specifies the index of the first element of the subset in the source array.

Supported types: Numeric.
Count

Specifies the number of elements (beginning at StartIndex) to include in the subset of the source array.

Supported types: Numeric.
Condition

Specifies the condition used on each element of the subset of SourceArray to filter the array.

Supported types: Boolean.
Expression

Specifies the expression to perform on each element of the array after filtering.

Supported types: Numeric; Boolean; String; Point; Object.
MaxCount

Specifies the maximum number of values to include in the returned array. If more elements of the source array satisfy the condition than MaxCount, the function will stop filtering after enough elements are filtered.

Supported types: Numeric.
Returns
Returned types: Boolean array; String array; Numeric array; Point array; Object array.
Examples
1.

The following example only accepts positive values and 0 from the subset array specified by the index and count, [10, -20, 0, 20, -30]. After a maximum of 2 values are found, the expression adds 5 to each element, and the function returns the array [15, 5].

FILTER([-10, 0, 10, -20, 0, 20, -30, 0, 30], 3, 5, Item >= 0, Item + 5, 2)