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

        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.

        Wenn bloss ein leeres Mapping bestimmter Breite erzeugt werden soll,
        so kann folgende Notation verwendet werden:

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

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

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.

GESCHICHTE
        Umbenannt von allocate_mapping() in LDMud 3.2.6.
        Die ([:<width>]) Notation wurde in 3.2.9 eingefuehrt.

SIEHE AUCH
        mappings(LPC), walk_mapping(E), get_type_info(E), m_reallocate(E)