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

1.2.13.2 How to declare and use Mappings

Mappings are lists of associated values. They are mixed by default, meaning that the index part of the associated values doesn't have to be of the same type all the time, even though this is encouraged for the same reason as before in regard to the mixed data type.

Mappings can use any kind of data type both as index and value. The index part of the mapping in a single mapping must consist of unique values. There can not be two indices of the same value.

This all sounds pretty complicated, but in reality it's pretty simple to use. However, it will be a lot easier to understand once we get down to actually seeing it used.

You declare a mapping just like any other variable, so let's just start up with a few declarations for later use:

 
mapping my_map;
int     value;

Allocating and initializing can be done in three different ways:

 
1:	<mapping_var> = ([ <index1>:<value1>, <index2>:<value2>, ... ]);

2:	<mapping_var>[<index>] = value;

3:	<mapping_var> = mkmapping(<list of indices>, <list of values>);

The first is straight-forward and easy.

 
1: my_map = ([ "adam":5, "bertil":8, "cecar":-4 ]);

The second works so that in case a given mapping pair doesn't exist, it is created when referenced. If it does exist the value part is replaced.

 
2: my_map["adam"] = 1;    // Creates the pair "adam":1
   my_map["bertil"] = 8;  // Creates the pair "bertil":8
   my_map["adam"] = 5;    // Replaces the old value in "adam" with 5.
	...

The third requires two arrays, one containing the indices and one containing the values. How to create arrays was described in the previous chapter.

 
3: my_map = mkmapping(({ "adam", "bertil", "cecar" }), ({ 5, 8, -4 }));

Unlike arrays there's no order in a mapping. The values are stashed in a way that makes finding the values as quick as possible. There are functions that will allow you to get the component lists (the indices or values) from a mapping but keep in mind that they can be in any order and are not guaranteed to remain the same from call to call. In practice though, they only change order when you add or remove an element.

Merging mappings can be done with the +/+= operator just as with mappings.

 
my_map += ([ "david":5, "erik":33 ]);

Removing items in a mapping, however, is a bit trickier. That has to be done by using the special efun m_delete() (also described later).

 
my_map = m_delete(my_map, "bertil");
my_map = m_delete(my_map, "david");

As you see the mapping pairs has to be removed one by one using the index as an identifier of which pair you want to remove. Another thing you now realize quite clearly is that the indices in a mapping has to be unique, you can't have two identical 'handles' to different values. The values however can naturally be identical.

Individual values can be obtained through simple indexing.

 
value = my_map["cecar"]; // => -4

Indexing a value that doesn't exist will not generate an error, only the value 0. Be very careful of this since you might indeed have legal values of 0 in the mapping as well. i.e. a value of 0 might mean that the index has no value part but also that the value indeed is 0.

 
value = my_map["urk"]; // => 0


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

This document was generated by Hekay Permer on April, 20 2005 using texi2html