SYNOPSIS
	mixed * filter (mixed *arg, string fun, 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, 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.

	If <ob> is omitted, it defaults to this_object().


	If <arg> is an array, 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 array element in question
	is included into the result. Analog, if a mapping <map> is given
	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)

