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)

        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)

        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)


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. In other words:

          foreach(index)
             if (arg[index] exists as key in map)
                 result[index] = map[arg[index]]
             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.


        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.

SEE ALSO
        filter(E), filter_indices(E), map_indices(E), map_objects(E)

