Update doc/efun/ aus Driversourcen.
Manpages der efuns aktualisiert, neue Manpages hinzugefuegt.
Change-Id: I7cc91684269ff56d1aef47d5c5e7c87f7fd531dc
diff --git a/doc/efun/m_allocate b/doc/efun/m_allocate
index 255f3b9..7c75530 100644
--- a/doc/efun/m_allocate
+++ b/doc/efun/m_allocate
@@ -2,45 +2,45 @@
mapping m_allocate(int size)
mapping m_allocate(int size, int width)
-BESCHREIBUNG
- Die Funktion reserviert Speicher fuer ein Mapping. <size> ist die
- Anzahl Eintraege (d.h. die Anzahl Keys), <width> ist die Anzahl
- Dateneintraege pro Key. Wird <width> nicht angegeben, werden Keys
- mit einem Datenelement erzeugt.
+DESCRIPTION
+ Reserve memory for a mapping.
- Die Funktion ist nur sinnvoll, wenn man ein Mapping erzeugt, dessen
- ungefaehre Groesse von vornherein bekannt ist, um so den Overhead
- von wiederholten Speicherallokation zu minimieren. Wenn nicht alle
- allozierten Datenelemente mit Daten bestueckt werden, werden die
- Ueberbleibsel einige Zeit spaeter bei Gelegenheit wieder freigegeben
- (s. Bemerkungen).
- m_allocate() ist auch nuetzlich, wenn ein Mapping bestimmter Breite
- erzeugt werden soll, ohne bereits die Daten zu den Keys bereit zu
- stellen.
+ <size> is the number of entries (i.e. keys) to reserve, <width> is
+ the number of data items per entry. If the optional width is
+ omitted, 1 is used as default.
- Wenn bloss ein leeres Mapping bestimmter Breite erzeugt werden soll,
- so kann folgende Notation verwendet werden:
+ This is useful only when you are going to construct a mapping
+ whose approximate size you know beforehand, to save overhead on
+ repeated memory allocations. If you don't fill in data for all the
+ allocated elements, any leftovers will be eventually freed some time
+ later (see remark below).
+ It is also useful if you want the mapping to have a certain width
+ even if you don't provide all the data items for the keys yet.
- ([ ]) : erzeugt ein leeres Mapping mit Breite 1.
- ([:<width>]) : erzeugt ein leeres Mapping der Breite <width>,
- wobei <width> eine beliebige Anweisung sein kann, die eine
- Integerzahl zurueck liefert. Tatsaechlich wird diese Notation
- als 'm_allocate(0, <width>)' kompiliert.
+ If the goal is just to create an empty mapping with a certain
+ width, the following notations can be used:
-BEISPIELE
- m_allocate(3,7) -> erzeugt ein Mapping mit 7 Werten pro Key und Platz
- fuer 3 Eintraege.
- ([:2*3]) -> entspricht m_allocate(0,6).
+ ([ ]) : creates an empty mapping of width 1.
-BEMERKUNGEN
- Ungenutzer Speicher des allozierten Mappins wird waehrend des sog.
- Kompaktierens des Mappings freigegeben. Dies passiert waehrend eines
- "data cleanups" oder einer "garbage collection". Die Zeit zwischen
- "data cleanups" ist mit configure_driver() konfigurierbar.
+ ([:width ]) : creates an empty mapping the given <width>, where
+ <width> can be any expression yielding an integer result. In
+ fact this notation is compiled as 'm_allocate(0, width)' .
-GESCHICHTE
- Umbenannt von allocate_mapping() in LDMud 3.2.6.
- Die ([:<width>]) Notation wurde in 3.2.9 eingefuehrt.
+EXAMPLES
+ m_allocate(3, 7) -> mapping with 7 values per key, and with space
+ for 3 entries.
-SIEHE AUCH
+ ([:2*3 ]) -> same as m_allocate(0, 6)
+
+REMARKS
+ Unused memory in the allocated mapping will be freed during the
+ so-called compacting of the mapping. This is done during the
+ data-cleanup or the garbage collection. The time between
+ data-cleanups is configurable by configure_driver().
+
+HISTORY
+ Renamed from 'allocate_mapping' in LDMud 3.2.6.
+ The ([:width ]) notation was introduced in LDMud 3.2.9 / 3.3.208.
+
+SEE ALSO
mappings(LPC), walk_mapping(E), get_type_info(E), m_reallocate(E)