| SYNOPSIS |
| mixed * map(mixed *arg, string func, string|object ob, mixed extra...) |
| mixed * map(mixed *arg, closure cl, mixed extra...) |
| mixed * map(mixed *arg, mapping m [, int idx]) |
| |
| mixed * map(struct arg, string func, string|object ob, mixed extra...) |
| mixed * map(struct arg, closure cl, mixed extra...) |
| mixed * map(struct arg, mapping m [, int idx]) |
| |
| mapping map(mapping arg, string func, string|object ob |
| , mixed extra...) |
| mapping map(mapping arg, closure cl, mixed extra...) |
| |
| string map(string arg, string func, string|object ob, mixed extra...) |
| string map(string arg, closure cl, mixed extra...) |
| string map(string arg, mapping m [, int idx]) |
| |
| DESCRIPTION |
| Call the function <ob>-><func>() resp. the closure <cl> for every |
| element of the string, array, struct or mapping <arg>, and return a |
| result made up from the returned values. |
| |
| If <ob> is omitted, or neither a string nor an object, it |
| defaults to this_object(). |
| |
| If <arg> is an string, array or struct, the function will be called |
| with each of the array/struct elements as first parameter, followed |
| by the <extra> arguments. The result of the efun is an array/struct |
| with all the results returned from the function calls. Thus the |
| operation could be described as: |
| |
| foreach(index) result[index] = ob->func(arg[index], extra...) |
| |
| If <arg> is an string/array/struct, and a mapping is specified |
| instead of a function, the result is an array/struct with the |
| values found in the mapping for the original values, resp. with the |
| original values for which no mapping entry exists. If a column index |
| <idx> is given, that column of the mapping is used. In other words: |
| |
| foreach(index) |
| if (arg[index] exists as key in map) |
| result[index] = map[arg[index]] or map[arg[index], idx] |
| else |
| result[index] = arg[index] |
| |
| If <arg> is a string, the only allowed replacement values are |
| numbers, of which only the lower 8 bit will be considered. |
| |
| |
| 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 (these must not be protected references like &(i[0]). The |
| result of the efun is a mapping of all results of the function calls, |
| stored under their corresponding key. |
| |
| Depending on the width of the mapping <arg>, the operation can |
| be described as: |
| |
| foreach (key in arg) |
| switch (widthof(arg)) |
| case 0: |
| result[key] = ob->func(key, 0, extra...) |
| case 1: |
| result[key] = ob->func(key, arg[key], extra...) |
| else : |
| result[key] = 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 however that the resulting mapping always has one value |
| per key. |
| |
| Historical Note: map() used with arrays behaves like map_array(), |
| but used with mappings generalises map_indices()! |
| |
| |
| EXAMPLES |
| arr = ({ 1, 2, 3, 4 }); |
| m = ([ 1:-1, 3:-3 ]); |
| |
| map(arr, #'%, 2) --> returns ({ 1, 0, 1, 0 }) |
| map(arr, m) --> returns ({ -1, 2, -3, 4 }) |
| |
| |
| HISTORY |
| Introduced in LDMud 3.2.6, obsoletes map_array(). |
| LDMud 3.2.8 added the feature of mapping an array through a mapping. |
| LDMud 3.3.439 added mapping of strings. |
| LDMud 3.3.719 added the <idx> parameter for mapping through mappings. |
| |
| SEE ALSO |
| filter(E), filter_indices(E), map_indices(E), map_objects(E) |
| |