Mappen (Maps)

In heel wat situaties moet je paren opslaan die uit een sleutel en een waarde bestaan. Bijvoorbeeld, een karakter kan een aantal verschillende voorwerpen hebben en voor elk voorwerp heeft het er een bepaald aantal van. In dit geval is het voorwerp de sleutel en het aantal is de waarde. De mappen handhaven dergelijke paren, die door sleutel worden gesorteerd. Je kunt paren aan de map toevoegen en zoeken naar de waarde die aan een bepaalde sleutels is gekoppeld. Omdat de sleutels worden gesorteerd kun je de vorige en volgende sleutels ook vinden. Soms is het ook nuttig om een map te gebruiken om sleutels zonder een overeenkomstige waarde enkel op te slaan. In dat geval kun je een waarde van 0 eenvoudig gebruiken. De volgende functies bestaan:

ds_map_create() Creëert een nieuwe kaart. De functie geeft een geheel terug als een id die in alle andere functies moet worden gebruikt om tot deze map toegang te verkrijgen.
ds_map_destroy(id) Vernietigt de kaart met bepaalde id, waardoor het gebruikte geheugen vrij komt. Vergeet niet om deze functie te gebruiken wanneer je met de structuur klaar bent.
ds_map_clear(id) Ontruimt de kaart met bepaalde id, die alle gegevens verwijdert uit de map maar het niet vernietigt.
ds_map_size(id) Geeft het aantal sleutel-waarde paren die in de kaart zijn opgeslagen terug.
ds_map_empty(id) Geeft terug of de kaart leeg is. Dit is hetzelfde als het testen of de grootte van de map 0 is.
ds_map_add(id, key, val) Voegt een sleutel-waarde paar aan de map toe.
ds_map_replace(id, key, val) Vervangt de waarde van de sleutel met een nieuwe waarde.
ds_map_delete(id, key) Verwijdert de sleutel en de overeenkomstige waarde van de kaart. (Als er veelvoudige ingangen met dezelfde sleutel zijn, wordt er slechts een verwijderd.)
ds_map_exists(id, key) Geeft terug of de sleutel in de kaart bestaat.
ds_map_find_value(id, key) Geeft de waarde terug die aan de sleutel is gekoppeld.
ds_map_find_previous(id, key) Geeft de grootste sleutel in de kaart terug die kleiner dan de vermelde sleutel is. (Merk op dat de sleutel wordt teruggegeven, niet de waarde. Je kunt de vorige routine gebruiken om de waarde te vinden.)
ds_map_find_next(id, key) Geeft de kleinste sleutel in de kaart terug die groter is dan de vermelde sleutel.
ds_map_find_first(id) Geeft de kleinste sleutel in de kaart terug.
ds_map_find_last(id) Geeft de grootste sleutel in de kaart terug.