The Array method filter() in Apps Script
The Array method filter() is used to filter an array based on a set of conditions. This method returns a new array with the filtered values.
Prerequisites
This tutorial assumes that you're familiar with:
Syntaxarray.filter(callbackFunction)
Parameters
array.filter(callbackFunction)callbackFunction (required):
This is the function that will be executed once for every element in the array. This function is where you need to specifyhow the conditions that need to be checked. If all the conditions are met, the corresponding value will be included in the filtered array.
The callbackFunction can accept three arguments:
value(required): The current value being processed.index(optional): The index of the value in the array.array(optional): The original array that thefilter()method was called on.
Return value
The filter() method returns a new array containing values from the original array that meet the conditions set forth in the callbackFunction.
How does the filter() Array method work?
The filter() method will execute the callbackFunction once for every element in the array. If the callbackFunction returns true (or a value that is treated as true by Apps Script), the element will be included in the filtered array that is returned by the filter() method. If the callbackFunction returns false, the corresponding value will not be included in the filtered array.
Note
The following values in Apps Script are treated as false:
false: The boolean value false0: The number 0"": An empty stringnull: The null valueundefined: An undefined valueNaN: A value that represents "not a number"
Other values are treated as true by Apps Script. Interestingly, even empty arrays and empty objects are treated as true by Apps Script.
ExamplesExample 1: Using the filter() Array method to filter out values that are not a number
Example 1.1
In the code below, the function isNumber(value) is the callbackFunction parameter in the filter() method. This function is executed once for every element in the array values and it returns true if the element is a number and false otherwise.The array filteredValues is returned by the filter() method and it only contains numeric values from the original array.
function filterEx1_1() {
var values = [1, -10, "apple", 25, "orange"];
var filteredValues = values.filter(isNumber);
Logger.log(filteredValues);
}
function isNumber(value) {
return typeof value === "number";
}Output
[1.0, -10.0, 25.0]
How does the above code work?
The filter() method will execute the callback function once for every element in the array values. If the callback function returns true, the corresponding element will be included in the array filteredValues.
The function isNumber() will be called 5 times, once for every element in the array values.
isNumber(1); //returns true so 1 will be included in filteredValues
isNumber(-10); //returns true so -10 will be included
isNumber("apple"); //returns false so "apple" will NOT be included
isNumber(25); //returns true so 25 will be included
isNumber("orange"); //returns false so "orange" will NOT be includedThe values 1, -10 and 25 will be included in the array filteredValues returned by the filter() method. This is because the callbackFunction isNumber() returned true for these values.
Example 1.2
Instead of defining the function isNumber() separately and then passing it as a parameter, you can also define it in-line. The code below shows you how to do this.
function filterEx1_2() {
var values = [1, -10, "apple", 25, "orange"];
var filteredValues = values.filter(function(value) {
return typeof value === "number";
});
Logger.log(filteredValues);
}Output
[1.0, -10.0, 25.0]
Note
Notice that there is no name for the function in the above example.
This is because, in Apps Script (which is a version of JavaScript), a function is basically a variable with a value of type function.
Consider the function addTwoNumbers() below.
function addTwoNumbers(num1, num2) {
return num1 + num2;
}This function can also be rewritten in the following way:
var addTwoNumbers = function(num1, num2) {
return num1 + num2;
}Here the variable addTwoNumbers contains a value of type function. In Apps Script, both of the above code snippets have the exact same result.
When you pass a function as a parameter to the filter() method, you're really passing the function value. Therefore, the following statement values.filter(isNumber); in Example 1.1 is the same as the code snippet below in Example 1.2
values.filter(function(value) {
return typeof value === 'number'
});This is because isNumber is just a variable that contains the following function value:
function(value) {
return typeof value === 'number'
}Conclusion
In this tutorial, you learned how to use the filter() Array method to create a new array that only contains those elements from the original array that meet a set of conditions.