.. efun:: 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])

  Call the function ``<ob>-><func>()`` resp. the closure :arg:`cl` for every element of the string, array, struct or mapping :arg:`arg`, and return a result made up from the returned values.

  If :arg:`ob` is omitted, or neither a string nor an object, it defaults to ``this_object()``.

  If :arg:`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 :arg:`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:`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 :arg:`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:`arg` is a string, the only allowed replacement values are numbers, of which only the lower 8 bit will be considered.

  If :arg:`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 :arg:`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:`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.

  .. caution:: the resulting mapping _always_ has one value per key.

  .. note:: This efun behaves like ``map_array()``, but used with mappings generalises :efun:`map_indices`!

  .. todo:: should map_array above just be a literal, or a link to an obsolete doc? I could make an obsolete *domain* which would enable holding old copies? Also posed in this doc, multiple pseudocode examples that might need explicit code blocks with a specific highlight type?

  .. usage::

    ::

      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 3.2.6 introduced: obsoletes ``map_array()``.
  :history 3.2.8 changed: added the feature of mapping an array through a mapping.
  :history 3.3.439 changed: added mapping of strings.
  :history 3.3.719 changed: added the :arg:`idx` parameter for mapping through mappings.

  .. seealso:: :efun:`filter`, :efun:`filter_indices`, :efun:`map_indices`, :efun:`map_objects`