1SYNOPSIS
2        mixed * filter(mixed *arg, string fun, string|object ob
3                                             , mixed extra...)
4        mixed * filter(mixed *arg, closure cl, mixed extra...)
5        mixed * filter(mixed *arg, mapping map, mixed extra...)
6
7        string  filter(string arg, string fun, string|object ob
8                                          , mixed extra...)
9        string  filter(string arg, closure cl, mixed extra...)
10        string  filter(string arg, mapping map, mixed extra...)
11
12        mapping filter(mapping arg, string func, string|object ob
13                                               , mixed extra...)
14        mapping filter(mapping arg, closure cl, mixed extra...)
15
16DESCRIPTION
17        Call the function <ob>-><func>() resp. the closure <cl> for
18        every element of the array, or mapping <arg>, and return a
19        result made from those elements for which the function call
20        returns TRUE.  The <extra> arguments are passed as additional
21        parameters to the function calls and must not be references of
22        array of mapping elements (like &(i[1]) ).
23
24        If <ob> is omitted, or neither a string nor an object, it
25        defaults to this_object().
26
27
28        If <arg> is an array or struct, the function will be called with
29        each of the array/struct values as first parameter, followed by the
30        <extra> arguments. If the result from the function call is true,
31        the array element in question is included into the efun result.
32
33        If the efun is used with a mapping <map> instead of a function,
34        every array element which is key in <map> is included into the
35        result.
36
37
38        If <arg> is a mapping, the function will be called with
39        each of the mapping keys as first, and (if existing) the
40        associated values as second parameter, followed by the <extra>
41        arguments. If the result is true, the mapping element in question
42        is included into the result.
43
44        Depending on the width of the mapping <arg>, the function
45        call takes one of three forms:
46
47            widthof(arg) == 0: ob->func(key, 0, extra...)
48                         == 1: ob->func(key, arg[key], extra...)
49                          > 1: ob->func( key
50                                       , ({ arg[key,0] ...arg[key,width-1] })
51                                       , extra...)
52
53        The advantage of this approach is that the two types of
54        multi-dimensional mappings (mappings with multiple values
55        per key, and mappings of arrays) can be treated in the same way.
56
57
58        Historical Note: filter() used with arrays behaves like
59        filter_array(), but used with mappings is a generalisation of
60        filter_indices().
61
62
63HISTORY
64        Introduced in LDMud 3.2.6, obsoletes filter_array().
65        LDMud 3.3.439 added filtering of strings.
66
67SEE ALSO
68        filter(E), filter_indices(E), map(E), walk_mapping(E), member(E),
69        m_contains(E)
70
71