SYNOPSIS
        mixed * filter (mixed *arg, string fun, string|object ob
                                              , mixed extra...)
        mixed * filter (mixed *arg, closure cl, mixed extra...)
        mixed * filter (mixed *arg, mapping map, mixed extra...)

        mapping filter (mapping arg, string func, string|object ob
                                                , mixed extra...)
        mapping filter (mapping arg, closure cl, mixed extra...)

DESCRIPTION
        Call the function <ob>-><func>() resp. the closure <cl> for
        every element of the array or mapping <arg>, and return
        a result made from those elements for which the function
        call returns TRUE. The <extra> arguments are passed as additional
        parameters to the function calls and must not be references of array
        of mapping elements (like &(i[1]) ).

        If <ob> is omitted, or neither a string nor an object, it
        defaults to this_object().


        If <arg> is an array, the function will be called with
        each of the array values as first parameter, followed by the <extra>
        arguments. If the result from the function call is true, the array
        element in question is included into the efun result.

        If the efun is used with a mapping <map> instead of a function,
        every array element which is key in <map> is included into the result.


        If <arg> is a mapping, the function will be called with
        each of the mapping keys as first, and (if existing) the
        associated values as second parameter, followed by the <extra>
        arguments. If the result is true, the mapping element in question
        is included into the result.

        Depending on the width of the mapping <arg>, the function
        call takes one of three forms:

            widthof(arg) == 0: ob->func(key, 0, extra...)
                         == 1: ob->func(key, arg[key], extra...)
                          > 1: ob->func( key
                                       , ({ arg[key,0] ...arg[key,width-1] })
                                       , extra...)

        The advantage of this approach is that the two types of
        multi-dimensional mappings (mappings with multiple values
        per key, and mappings of arrays) can be treated in the same way.


        Note that filter() used with arrays behaves like filter_array(),
        but used with mappings is a generalisation of filter_indices().


HISTORY
        Introduced in LDMud 3.2.6, obsoletes filter_array().

SEE ALSO
        filter(E), filter_indices(E), map(E), walk_mapping(E), member(E),
        m_contains(E)