Cartes (Maps)

Dans quelques situations, il vous sera nécessaire de mémoriser des couples de valeurs comprenant une clé et sa valeur associée. Par exemple, un personnage peut disposer de différents articles et pour chacun d'entre eux en avoir un certain nombre. Dans ce cas précis, l'article sera la clé et le nombre la valeur. Les cartes (maps) contiennent de telles paires de valeurs, triées par clé. Vous pouvez ajouter des paires de valeurs dans une carte puis y effectuer une recherche d'une valeur correspondant à des clés particulières. Dû au fait que les clés sont triées dans la carte, il est donc possible de faire une recherche des clés précédentes et suivantes par rapport à une clé donnée. Parfois, il peut être utile également d'utiliser une carte pour stocker uniquement des clés sans aucune valeur associée. Dans cette situation, vous utiliserez simplement une valeur initialisée à 0. Les fonctions suivantes existent :

ds_map_create() Crée une nouvelle carte. La fonction retourne l'id de la carte sous forme d'entier, id qui devra ensuite être utilisé par toutes les fonctions devant accéder à la carte créée.
ds_map_destroy(id) Détruit la carte d'ID id, libérant la mémoire utilisée par cette dernière. Ne pas oublier d'appeler cette fonction lorsque vous n'aurez plus besoin d'utiliser une carte particulière.
ds_map_clear(id) Efface la carte d'ID id, supprimant ainsi toutes les données qu'elle contient mais ne supprime pas la carte.
ds_map_size(id) Retourne le nombre de couples clé-valeur contenus dans la carte d'ID id.
ds_map_empty(id) Indique si la carte est vide. Cela revient à tester si sa taille est égale à 0.
ds_map_add(id, key, val) Ajoute le couple clé-valeur donné dans la carte d'ID id.
ds_map_replace(id, key, val) Remplace la valeur correspondant à la clé key par la nouvelle valeur val.
ds_map_delete(id, key) Supprime la clé key et sa valeur attachée de la carte d'ID id (en présence de plusieurs entrées avec la même clé, seule la première entrée sera supprimée).
ds_map_exists(id, key) Indique si la clé key existe dans la carte d'ID id.
ds_map_find_value(id, key) Retourne la valeur correspondant à la clé key.
ds_map_find_previous(id, key) Retourne la clé précédent la clé key indiquée (veuillez noter que seule la clé est retournée et non pas sa valeur. Vous pouvez utiliser la routine précédente pour obtenir la valeur correspondant à la clé).
ds_map_find_next(id, key) Retourne la clé suivant la clé key indiquée.
ds_map_find_first(id) Retourne la plus petite clé de la carte.
ds_map_find_last(id) Retourne la plus grande clé de la carte.

<< Traduction française par Philippe Ragni - (2005) >>