|
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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)
e.g.
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)
e.g.
mapping mp, mdel;
mp["fatty"] = "blimp";
mp["mrpr"] = "unique";
mp["olorin"] = "bloodshot";
mdel = m_delete(mp, "olorin");
dump_array(mdel);
/* 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);
e.g.
// This function displays a mapping and its contents
void
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] | [ ? ] |