SYNOPSIS
	mixed *filter_array(mixed *arr, string fun, object ob, mixed extra)
	mixed *filter_array(mixed *arr, closure cl, mixed extra)

DESCRIPTION
	Returns an array holding the items of arr filtered through
	ob->fun(element, extra) or the closure cl. The function fun in
	ob is called for each element in arr with that element as
	parameter. A second parameter extra is sent in each call if
	given. If ob->fun(arr[index], extra) returns 1 the element is
	included in the returned array.
	
	If arr is not an array, then 0 will be returned.
	
	The extra argument is optional. ob can also be a file_name. If
	ob is omitted, this_object() is default.

EXAMPLE
	int check_if_idle(object user) { return query_idle(user); }

	...

	object *idle_users;

	idle_users = filter_array(users(), "check_if_idle");
	/* equivalent but smaller and faster */
	idle_users = filter_array(users(), #'query_idle );

	Now idle_users contains all users that have been idle for more
	than 1 second.

SEE ALSO
	map_array(E)