SYNOPSIS
        mapping m_allocate(int size)
        mapping m_allocate(int size, int width)

DESCRIPTION
        Reserve memory for a mapping.

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

        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.

        If the goal is just to create an empty mapping with a certain
        width, the following notations can be used:

        ([ ]) : creates an empty mapping of width 1.

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

EXAMPLES
        m_allocate(3, 7) -> mapping with 7 values per key, and with space
        for 3 entries.

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