Manpages aus Driver aktualisiert.
Hierbei handelt es sich um Manpages, welche vom MG
modifiziert wurden.
Die Bemerkungen und Beispiele wurden ausgelagert in
separate Manpages, um zukuenftige Aktualisierungen
aus dem Driver zu erleichtern.
Change-Id: I5a6248cd65a8cd841831617a92aa1ee191dbf661
diff --git a/doc/efun/sort_array b/doc/efun/sort_array
index 80837b7..3316a0c 100644
--- a/doc/efun/sort_array
+++ b/doc/efun/sort_array
@@ -1,108 +1,74 @@
-sort_array(E)
-
-FUNKTION:
- mixed *sort_array(mixed *arr, mixed func [, mixed ob])
-
-PARAMETER:
- arr - zu sortierendes Array
- func - zu rufende Methode; kann als String (Funktionsname) oder
- Closure uebergeben werden
- ob - Objekt, an dem Methode gerufen werden soll; kann als String
- (Filename) oder Objektpointer uebergeben werden
+SYNOPSIS
+ mixed * sort_array(mixed *arr, string wrong_order)
+ mixed * sort_array(mixed *arr, string wrong_order, object|string ob)
+ mixed * sort_array(mixed *arr, string wrong_order, object|string ob,
+ mixed extra...)
+ mixed * sort_array(mixed *arr, closure cl)
+ mixed * sort_array(mixed *arr, closure cl, mixed extra...)
BESCHREIBUNG
- Erzeugt eine (flache) Kopie des Arrays 'arr' und sortiert diese mit der
- Sortierfunktion 'func'. Die sortierte Kopie wird dann zurueckgegeben.
+ Sortiert das Array <arr> entweder nach der Ordnungsfunktion
+ <ob->wrong_order(a, b)> oder nach der Closure cl.
- Die Elemente des zu sortierenden Arrays werden paarweise an die
- Sortierfunktion als Argumente uebergeben.
- Die Sortierfunktion sollte eine Zahl
- - >0 zurueckgeben, wenn die Elemente in der falschen
- Reihenfolge sind
- - <=0 zurueckgeben, wenn die Elemente in der richtigen
- Reihenfolge sind.
+ Normalerweise wird zuerst eine flache Kopie des Arrays <arr> erstellt
+ und die sortierte Kopie als Ergebnis zurueckgeliefert. Wird <arr>
+ jedoch als Referenz uebergeben, wird keine implizite Kopie erstellt
+ und das Originalarray sortiert.
- Verwendung von Methoden:
- Wenn bei der Angabe von 'func' kein Objekt 'ob' in Form eines Strings
- oder Objekts angegeben wird, wird this_object() angenommen.
+ Wenn das Argument <arr> 0 ist, ist das Resultat der Funktion auch 0.
- Verwendung von Closures:
- Es koennen Lfun-, Lambda- und Inline-Closures verwendet werden.
- Lfun-Closures koennen, wenn im selben Objekt vorhanden, auch
- 'private' oder/und 'static' deklariert sein, muessen aber zu dem
- Zeitpunkt der Verwendung bekannt sein (Funktionsprototypen benutzen).
- Von der Verwendung von Lambda-Closures wird ausdruecklich abgeraten.
+ <ob> ist das Objekt, in dem die Ordnungsfunktion <wrong_order()>
+ aufgerufen wird. <ob> kann das Objekt als solches enthalten, oder
+ einen String mit dem Objektnamen. Wird <ob> nicht angegeben, oder
+ enthaelt es weder einen String noch ein Objekt, wird stattdessen
+ this_object() verwendet.
-BEMERKUNGEN:
- (1) sort_array() unterstuetzt keinen extra-Parameter
+ Die Elemente von <arr> werden paarweise an die Ordnungsfunktion
+ <wrong_order()> als Argumente uebergeben, gefolgt von den <extra>
+ Argumenten, falls vorhanden. Die Ordnungsfunktion <wrong_order> sollte
+ eine positve Zahl liefern, wenn die paarweisen Elemente in der
+ falschen Reihenfolge waren, 0 oder eine negative Zahl sonst.
- (2) Achtung, die Elemente in 'arr' werden nicht tief kopiert, sind sie
- also selbst Arrays oder Mappings, so fuehrt eine Aenderung im Rueckgabe-
- Array zur Aenderung im Ursprungsarray:
+BEISPIELE
+ Um folgendes Array in aufsteigender Reihenfolge zu ordnen:
- int *i, *j;
- i=({({1}),({2,3}),({4,5,6})});
- j=sort_array(i, // sortiert der Groesse nach absteigend
- function int ( mixed x, mixed y ) {
- return sizeof(x) < sizeof(y); }
- );
-
- Zu diesem Zeitpunkt ist i == ({ ({1}),({2,3}),({4,5,6}) })
- j == ({ ({4,5,6}),({2,3}),({1}) })
-
- Fuehrt man jetzt die Zuweisung j[0][0]=8; aus
+ arr = ({ 3, 8, 1, 3 })
- resultieren folgende Arrays: i == ({ ({1}),({2,3}),({8,5,6}) })
- j == ({ ({8,5,6}),({2,3}),({1}) })
+ wird als Ordnungsfunktion ist_groesser() verwendet:
-BEISPIELE:
- ### Sortieren von Zahlen in aufsteigender Reihenfolge ###
-
- int *arr = ({ 3, 8, 1, 3 })
+ int ist_groesser(int a, int b) {
+ return a > b;
+ }
- // Folgend identische Resultate, aber andere Ansaetze:
+ Folgende Aufrufe von sort_array() sind alle aequivalent:
- #1: nutzt die 'Efun' > als Lfun-Closure (ideal hier):
- sort_array(arr, #'>);
+ arr = sort_array(arr, "ist_groesser", this_object())
+ arr = sort_array(arr, "ist_groesser")
+ arr = sort_array(arr, #'ist_groesser)
+ arr = sort_array(arr, #'>) //dies ist die bevorzugte Variante :-)
+ arr = sort_array(arr, lambda(({'a, 'b}), ({#'>, 'a, 'b})))
- #2: mit Sortierfunktion im selben Objekt:
- int is_greater (int a, int b) {
- return a > b;
- }
-
- #2a: sortiert mittels der Lfun im selben Objekt die Elemente in das
- Rueckgabearray
- sort_array(arr, "is_greater", this_object())
- sort_array(arr, "is_greater")
+ Soll direkt das Original <arr> statt einer impliziten Kopie sortiert
+ werden:
- #2b: nutzt die Lfun is_greater() als Lfun-Closure (Funktionspointer)
- sort_array(arr, #'is_greater)
+ sort_array(&arr, #'>)
- #3: Nutzt eine Inline-Closure
- sort_array(arr, function int (int a, int b) {
- return a > b; } );
+ Etwas komplizierter ist es, folgendes Array aufsteigend nach dem
+ zweiten Argument jedes Teilarrays zu ordnen:
- Resultat in allen Faellen: ({1,3,3,8})
+ arr = ({ ({ "foo", 3 }), ({ "quux", 1 }), ... })
- ### Sortieren von geschachtelten Arrays ###
+ Dafuer muss die Ordnungsfunktion folgende Form annehmen:
- arr = ({ ({ "foo", 3 }), ({ "quux", 1 }), ... })
+ int ist_groesser(mixed *a, mixed *b) {
+ return a[1] > b[1];
+ }
- // Vorgehen identisch, allerdings muss die Sortierfunktion
- // angepasst werden (siehe auch das Beispiel unter Verwendung von
- // Inline-Closures oben unter "Bemerkungen"):
-
- int is_greater (mixed *a, mixed *b) {
- return a[1] > b[1];
- }
+GESCHICHTE
+ LDMud 3.2.8 fuehrte die Moeglichkeit ein, zusaetzliche Argumente
+ <extra> zu uebergeben.
+ LDMud 3.3.720 unterstuetzt die Uebergabe von <arr> als Referenz und
+ sortiert das Original statt einer impliziten flachen Kopie.
-SIEHE AUCH:
- Arrays: filter(E), map(E)
- Objektarrays: filter_objects(E), map_objects(E)
- Mappings: filter_indices(E), map_indices(E)
-
- Sonstiges: unique_array()
- alist, transpose_array(E)
-
-----------------------------------------------------------------------------
-Last modified: Mon Feb 18 23:09 2008 by Arathorn
+SIEHE AUCH
+ transpose_array(E), filter(E), map(E), alists(LPC)