filter

NAME

filter

SYNOPSIS

mixed filter(string|mapping|mixed* source,
             string filter_function,
             object|string ob,
             mixed *extra...)
mixed filter(string|mapping|mixed* source,
             function f,
             mixed *extra... )

DESCRIPTION

Returns a new string, array or mapping with the same elements as 'source'
whose elements pass the test implemented by the filter function.

A string is considered an array of integers, so the filter function is
called with the integer value of each character in the string.

The filter function must accept at least one argument, the element to be
tested and return a truthy value if the element should be included in the
result, or a falsy value if it should be excluded.

In the case of a mapping, filter will pass the key and value to the filter
function.

Any additional arguments given to filter() will be passed to the filter
function after the required arguments.

If the first syntax is used, the filter function is performed as a
call_other. If ob is a string, it is assumed to be the filename of an
object to load and call the filter function on.

EXAMPLES

Using function pointers:

string s = "Hello, this is a string.";
s = filter(s, (: $1 != ' ' :));
// s == "Hello,thisisastring."

int *a = ({ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 });
a = filter(a, (: $1 % 2 == 0 :));
// a == ({ 2, 4, 6, 8, 10 })

mapping m = ([ "a": 1, "b": 2, "c": 3, "d": 4, "e": 5 ]);
m = filter(m, (: $1[1] % 2 == 0 :));
// m == ([ "b": 2, "d": 4 ])

not_me = filter(users(), (: $1 != $2 :), this_player());
// not_me == all users except this_player()

Using strings:

int filter_space(int elem) return (elem != ' ');
s = filter(s, "filter_space", this_object());
// s == "Hello,thisisastring."

int filter_even(int elem) return (elem % 2 == 0);
a = filter(a, "filter_even", this_object());
// a == ({ 2, 4, 6, 8, 10 })

int filter_even(string key, int value) return (value % 2 == 0);
m = filter(m, "filter_even", this_object());
// m == ([ "b": 2, "d": 4 ])

int filter_not_me(object elem, object tp) return (elem != tp);
not_me = filter(users(), "filter_not_me", this_object(), this_player());
// not_me == all users except this_player()

NOTE

The efuns filter_mapping() and filter_array() are aliases for filter().

SEE ALSO

filter_array(3), filter_mapping(3), map(3), unique_array(3)