Update doc/efun/ aus Driversourcen.
Manpages der efuns aktualisiert, neue Manpages hinzugefuegt.
Change-Id: I7cc91684269ff56d1aef47d5c5e7c87f7fd531dc
diff --git a/doc/efun/map b/doc/efun/map
index 808f065..5c6c47d 100644
--- a/doc/efun/map
+++ b/doc/efun/map
@@ -7,87 +7,92 @@
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, 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])
-BESCHREIBUNG
- Ruft die Funktion <ob>-><func>() bzw. die Closure <cl> fuer jedes
- Element des Strings, Arrays, Mappings oder der Struktur <arg> auf
- und liefert ein Resultat, das aus den verschiedenen Rueckgabewerten
- erstellt wurde.
+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.
- Wurde <ob> nicht angegeben, oder ist es weder ein String noch ein
- Objekt, wird stattdessen this_object() verwendet.
+ If <ob> is omitted, or neither a string nor an object, it
+ defaults to this_object().
- Ist <arg> ein Array, ein String oder eine Struktur, 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:
+ 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...)
+ foreach(index) result[index] = ob->func(arg[index], extra...)
- Ist <arg> ein Array, ein String oder eine Struktur, 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 Originalwerten, wenn fuer sie kein Mappingeintrag
- existiert. Ist <idx> angegeben, so wird die entsprechende Spalte des
- Mappings verwendet. Mit anderen Worten:
+ 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] ist ein Key in <arg>)
- result[index] = map[arg[index]] oder map[arg[index]]
- else
- result[index] = arg[index]
+ 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]
- 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.
+ If <arg> is a string, the only allowed replacement values are
+ numbers, of which only the lower 8 bit will be considered.
- 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...)
+ 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.
- 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.
+ Depending on the width of the mapping <arg>, the operation can
+ be described as:
-BEISPIELE
+ 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) --> liefert ({ 1, 0, 1, 0 })
- map(arr, m) --> liefert ([ -1, 2, -3, 4 })
+ map(arr, #'%, 2) --> returns ({ 1, 0, 1, 0 })
+ map(arr, m) --> returns ({ -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.
- LDMud 3.3.439 fuehrt map() fuer Strings ein.
- LDMud 3.3.719 fuehrt den <idx>-Parameter fuer mappen mit Mappings ein.
+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.
-SIEHE AUCH
+SEE ALSO
filter(E), filter_indices(E), map_indices(E), map_objects(E)
+