Geas MUD, enter the Aventure!
Geas Home | Play the Game

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.11 Mapping functions

Mappings, as stated earlier, are lists of associated indices and values. A value is associated with another, so that by indexing with the first value you retrieve the second. Internally they are set up as hashed lists, which makes for very quick lookups. However, they are memory hogs, using up lots of memory as compared with arrays.

How to allocate mappings then? Well, that's very easy. Just declare it and assign a value to an index value. If it exists, the old value is removed and the new put in its place. If it doesn't exist it is allocated and stored in the mapping automatically. You can also use two arrays, one with the indices and one with the values and combine those into a mapping with the efun mkmapping(). Just remember that the two arrays must be of the same size.

mapping mkmapping(mixed indarr, mixed valarr)
    string *ind_arr, *val_arr;
    mapping mp;

    mp["fatty"] = "blimp";
    mp["mrpr"] = "unique";
    mp["olorin"] = "bloodshot";

    // Is the same as...

    ind_arr = ({ "fatty", "mrpr", "olorin" });
    val_arr = ({ "blimp", "unique", "bloodshot" });
    mp = mkmapping(ind_arr, val_arr);

    // You can give the arrays directly, instead of through
    // variables, of course.

As with arrays, there's a function available to determine if a given variable contains a mapping or not, mappingp(), that works in the exact same way. Use it in the same circumstances, i.e. typically when a function might or might not return a mapping and you need to know for certain that it contains a valid value before you try to index it.

To find the size of mapping you have to use the special efun m_sizeof(). However, it works exactly like the corresponding array function, returning the amount of elements in the mapping.

Removing elements from a mapping is slightly more complicated than with arrays however, you have to use the special function m_delete() to do that. m_delete() doesn't exactly remove an element, what it does is that it creates a new mapping that is a copy of the indicated mapping, apart from a particular value pair. As you can see, it takes the mapping to delete from and the index to the value pair you want removed as arguments:

mapping m_delete(mapping delmap, mixed elem)
    mapping mp, mdel;

    mp["fatty"] = "blimp";
    mp["mrpr"] = "unique";
    mp["olorin"] = "bloodshot";

    mdel = m_delete(mp, "olorin");

    /* Output:
     *  (Mapping) ([
     *    "mrpr":"unique"
     *    "fatty":"blimp"
     *  ])

Well... how to access all elements of a mapping then? Particularly one would want some kind of reverse function to mkmapping() earlier. Actually, there's two: m_indices() and m_values() which returns an array containing the index and value part of the given mapping respectively. Due to a linguistic confusion, the efun m_indices() has a double called m_indexes(). They both do the same thing however (actually just two names for the same function) so you can use either, as your linguistic preferences dictate. :)

However, now we come to a sensitive subject - order in mappings. As explained earlier a mapping has no defined internal order. Well... it has, but no order that you need or should worry about. This order also changes when you remove or add value pairs to a mapping. All in all this means that if you extract the indices and the values from a mapping, those two arrays will correspond to each other, the first index value corresponding to the first array value, only as long as the mapping hasn't been changed in between those two operations.

mixed m_indices(mapping mapp);
mixed m_values(mapping mapp);
    // This function displays a mapping and its contents
    dump_mapping(mapping mp)
        int i, sz;
        mixed ind, val;

        ind = m_indices(mp);
        val = m_values(mp);

        for (i = 0, sz = sizeof(ind); i < sz; i++)
            write(sprintf("%O", ind[i]) + " corresponds to " + 
                  sprintf("%O", val[i]) + "\n");

    /* Example run: dump_mapping(([ "fatty" : "blimp", 
     *                              "mrpr" : "unique",
     *                              "olorin" : "bloodshot" ]));
     * "olorin" corresponds to "bloodshot"
     * "fatty" corresponds to "blimp"
     * "mrpr" corresponds to "unique"

There are two functions that facilitates the saving and restoration of object data, m_save_object() will create a mapping that contains all global non-static variables, with the variable names as string indices corresponding to the actual values. You can then either save this mapping to file directly, or pass it to another function as you please. The converse of this efun; m_restore_object() takes a mapping as argument and reads the contents into the corresponding non-static global variables.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Ronny Wikh on July, 8 2003 using texi2html