The `filter()` function filters the given array by invoking the specified
callback for each item of the input array and only keeping items for which
the callback returned a truish value.

Returns the filtered copy of the input array, maintaining the original order
of items. The input array is not modified.

Returns `null` if the first argument is not an array.

-- Testcase --
{%
	let numbers = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ];

	printf("%.J\n",
		filter(numbers, function(n) {
			return (n % 2) == 0;
		})
	);
%}
-- End --

-- Expect stdout --
[
	0,
	2,
	4,
	6,
	8
]
-- End --


Supplying an invalid callback will trigger an exception.

-- Testcase --
{%
	filter([1, 2, 3], "not_a_function")
%}
-- End --

-- Expect stderr --
Type error: left-hand side is not a function
In line 2, byte 36:

 `    filter([1, 2, 3], "not_a_function")`
  Near here ----------------------------^


-- End --


Supplying an invalid array will yield `null`.

-- Testcase --
{%
	printf("%.J\n", filter("not_an_array", function(i) { return i > 3 }));
%}
-- End --

-- Expect stdout --
null
-- End --


The callback is invoked with three argument for each item, the current item
value, the index position of the item and the input array being mapped.

-- Testcase --
{%
	let words = [ "foo", "bar", "baz", "qrx" ];

	print(join("\n",
		filter(words, function(word, idx, src) {
			printf("word=%s, idx=%d, src=%J\n", word, idx, src);

			return true;
		})
	), "\n");
%}
-- End --

-- Expect stdout --
word=foo, idx=0, src=[ "foo", "bar", "baz", "qrx" ]
word=bar, idx=1, src=[ "foo", "bar", "baz", "qrx" ]
word=baz, idx=2, src=[ "foo", "bar", "baz", "qrx" ]
word=qrx, idx=3, src=[ "foo", "bar", "baz", "qrx" ]
foo
bar
baz
qrx
-- End --


Exceptions in the callback terminate the filter process and are
propagated to the calling context.

-- Testcase --
{%
	filter([ 1, 2, 3 ], function() { die() });
%}
-- End --

-- Expect stderr --
Died
In [anonymous function](), line 2, byte 39:
  called from function filter ([C])
  called from anonymous function ([stdin]:2:42)

 `    filter([ 1, 2, 3 ], function() { die() });`
  Near here -------------------------------^


-- End --
