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)

        mapping map(mapping arg, string func, string|object ob, mixed extra...)
        mapping map(mapping arg, closure cl, mixed extra...)

BESCHREIBUNG
        Ruft die Funktion <ob>-><func>() bzw. die Closure <cl> fuer jedes
        Element des Arrays oder Mappings <arg> auf und liefert ein Resultat,
        das aus den verschiedenen Rueckgabewerten erstellt wurde.

        Wurde <ob> nicht angegeben, oder ist es weder ein String noch ein
        Objekt, wird stattdessen this_object() verwendet.

        Ist <arg> ein Array, wird die Funktion mit jedem Element des Arrays
        als erstem Parameter aufgerufen, gefolgt von den <extra> Argumenten.
        Das Resultat der Efun ist ein Array, das die Rueckgabewerte der
        Funktionsaufrufe enthaelt. Man koennte die Operation map() deshalb
        umschreiben als:

            foreach(index) result[index] = ob->func(arg[index], extra...)

        Ist <arg> ein Array, und wurde statt einer Funktion ein Mapping
        angegeben, so liefert map() ein Array mit den Werten, die im
        Mapping an Stelle der urspruenglichen Werte stehen, bzw. mit den
        Werten, fuer die kein Mappingeintrag existiert. Mit anderen Worten:

            foreach(index)
                if (arg[index] ist ein Key in <arg>)
                    result[index] = map[arg[index]]
                else
                    result[index] = arg[index]

        Ist <arg> ein Mapping, wird die Funktion fuer jeden Key des Mappings
        als erstem Parameter und den Datenwerten (sofern vorhanden) als
        zusaetzliche Argumente aufgerufen, gefolgt von den <extra> Argumenten.
        Die <extra> Argumente duerfen keine geschuetzten Referenzen enthalten
        (wie z.B. &(i[0])). Das Ergebnis der Efun ist ein Mapping, das die
        Resultate der Funktionsaufrufe als Zuordnung zum jeweiligen Key
        enthaelt.

        Abhaengig von der Breite des Mappings <arg>, kann die Operation
        umschrieben werden als:

            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...)

        Der Vorteil dieses Ansatzes ist, dass beide Arten von mehrdimensionalen
        Mappings (Mappings mit mehreren Werten pro Key und Mappings von Arrays)
        gleich behandelt werden koennen.

BEISPIELE
        arr = ({ 1, 2, 3, 4 });
        m = ([ 1:-1, 3:-3 ]);

        map(arr, #'%, 2)  --> liefert ({ 1, 0, 1, 0 })
        map(arr, m)       --> liefert ([ -1, 2, -3, 4 })

ANMERKUNGEN
        map() auf Arrays angewandt verhaelt sich wie map_array(), auf Mappings
        angewandt hingegen verhaelt es sich wie eine Verallgemeinerung von
        map_indices().

GESCHICHTE
        Eingefuehrt in LDMud 3.2.6, loest map_array() ab.
        LDMud 3.2.8 fuehrt neu die Moeglichkeit ein, ein Array durch ein
        Mapping zu mappen.

SIEHE AUCH
        filter(E), filter_indices(E), map_indices(E), map_objects(E)
