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...)
string filter( string arg, string fun, string|object ob, mixed extra...)
string filter( string arg, closure cl, mixed extra...)
string filter( string 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 or struct, the function will be called with each of the array/struct 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.

HISTORY

  • introduced (3.2.6) – obsoletes filter_array() for arrays and filter_indices() with mappings.
  • changed (3.3.439) – adds filtering of strings.