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)