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