The Map class stores key-value pairs and provides methods for reading, updating, removing, and iterating over entries. Maps can also be combined with the supported map operators.

Map.count

attribute map

Signature

Map.count

Description

The count attribute returns the number of key-value pairs stored in the map.

Example

var inventory = {
    ["sword"] = 1,
    ["shield"] = 1,
    ["potion"] = 5,
    ["gold"] = 250
}

print(inventory.count)  // 4

var empty = {}
print(empty.count)  // 0

Map.keys

attribute map

Signature

Map.keys

Description

The keys attribute returns a list containing all the keys present in the map.

Example

var player = {
    ["name"] = "Aria",
    ["class"] = "Ranger",
    ["level"] = 17,
    ["guild"] = "Silverwood"
}

var k = player.keys
print(k)  // ["name", "class", "level", "guild"]

// Iterate over a map's keys
for const key in player.keys
{
    print("Field: " + key)
}

Map.values

attribute map

Signature

Map.values

Description

The values attribute returns a list containing all the values present in the map.

Example

var high_scores = {
    ["Aria"] = 9820,
    ["Bram"] = 7415,
    ["Cyrus"] = 10230
}

var v = high_scores.values
print(v)  // [9820, 7415, 10230]

// Sum all values
var total = 0
for const score in high_scores.values
{
    total += score
}
print(total)  // 27465

Map.new

method map

Signature

function Map:new()

Description

The new method creates a new empty map.

Example

var party = Map.new()
party.set("tank", "Bram")
party.set("healer", "Lyra")
party.set("dps", "Cyrus")

print(party.count)  // 3

Map.get

method map

Signature

function Map:get(key)

Description

The get method retrieves the value associated with the specified key in the map. If the key does not exist, nil is returned.

Parameters

key
The key to look up in the map.

Returns

The method returns the value associated with key, or nil if the key is not present.

Example

var config = {
    ["volume"] = 0.8,
    ["difficulty"] = "hard",
    ["subtitles"] = true
}

print(config.get("volume"))       // 0.8
print(config.get("difficulty"))   // "hard"
print(config.get("mouse_speed"))  // nil

Map.set

method map

Signature

function Map:set(key, value)

Description

The set method inserts or updates a key-value pair in the map. If the key already exists, its value is updated; otherwise, a new entry is created. If no value is provided, the key is set to nil.

Parameters

key
The key to insert or update in the map.
value
The value to associate with key. Optional, defaults to nil.

Example

var stats = {}

stats.set("strength", 12)
stats.set("dexterity", 18)
stats.set("intelligence", 9)

print(stats.get("dexterity"))  // 18

// Update an existing key
stats.set("strength", 15)
print(stats.get("strength"))   // 15

// Add a key with no value
stats.set("luck")
print(stats.get("luck"))       // nil

Map.update

method map

Signature

function Map:update(other)

Description

The update method merges all key-value pairs from another map into the original map, overwriting any existing keys that collide.

Parameters

other
The map whose entries will be merged into the original map.

Example

var defaults = {
    ["theme"] = "dark",
    ["font_size"] = 14,
    ["auto_save"] = true
}

var user_prefs = {
    ["theme"] = "light",
    ["font_size"] = 18
}

defaults.update(user_prefs)
print(defaults)
// { "theme": "light", "font_size": 18, "auto_save": true }

Map.clear()

method map

Signature

function Map:clear()

Description

The clear method removes all key-value pairs from the map, leaving it empty.

Example

var cart = {
    ["apples"] = 3,
    ["bread"] = 1,
    ["milk"] = 2
}

print(cart.count)  // 3
cart.clear()
print(cart.count)  // 0
print(cart)        // {}

Map.contains

method map

Signature

function Map:contains(key)

Description

The contains method checks whether a given key exists in the map.

Parameters

key
The key to search for within the map.

Returns

The method returns true if the key is found in the map, or false otherwise.

Example

var spellbook = {
    ["fireball"] = 12,
    ["ice_shard"] = 8,
    ["lightning"] = 15
}

print(spellbook.contains("fireball"))   // true
print(spellbook.contains("meteor"))     // false

Map.delete

method map

Signature

function Map:delete(key)

Description

The delete method removes the key-value pair associated with the specified key from the map. If the key is not present, an error is raised.

Parameters

key
The key to remove from the map.

Example

var inventory = {
    ["sword"] = 1,
    ["shield"] = 1,
    ["potion"] = 5
}

inventory.delete("potion")
print(inventory.contains("potion"))  // false
print(inventory)
// { "sword": 1, "shield": 1 }

// Deleting a missing key raises an error
inventory.delete("bow")  // error: map key not found

Map.copy

method map

Signature

function Map:copy()

Description

The copy method produces a shallow copy of the map. The new map contains the same key-value pairs, but is a separate object.

Example

var original = {
    ["hp"] = 100,
    ["mp"] = 50
}

var clone = original.copy()
clone.set("hp", 1)

print(original.get("hp"))  // 100
print(clone.get("hp"))     // 1

Map.foreach

method map

Signature

function Map:foreach(callback)

Description

The foreach method iterates over every key-value pair in the map, invoking the given callback function with the key and value as arguments. The callback should accept two parameters: key and value.

Parameters

callback
A function called once per entry, receiving the entry’s key and value.

Example

var roster = {
    ["Aria"] = "Ranger",
    ["Bram"] = "Warrior",
    ["Lyra"] = "Cleric"
}

roster.foreach(function(key, value) {
    print(key + " plays a " + value)
})
// Aria plays a Ranger
// Bram plays a Warrior
// Lyra plays a Cleric

// A callback that ignores the key can still use the value
var total = 0
var prices = {["apple"] = 2, ["banana"] = 3, ["cherry"] = 5}
prices.foreach(function(_, value) {
    total = total + value
})
print(total)  // 10

Map.iter

method map

Signature

function Map:iter()

Description

The iter method returns an iterator over the map’s key-value pairs. Each step yields a two-element list [key, value], which can be conveniently unpacked in a for loop.

Example

var scores = {
    ["Aria"] = 9820,
    ["Bram"] = 7415,
    ["Cyrus"] = 10230
}

for const entry in scores.iter() {
    print(tostring(entry[0]) + " scored " + tostring(entry[1]))
}
// Aria scored 9820
// Bram scored 7415
// Cyrus scored 10230

Map.+

operator map

Signature

operator Map:+(other)

Description

The + operator creates a new map containing all key-value pairs from both the original map and other. When the same key appears in both maps, the value from the right-hand map (other) wins.

Parameters

other
The map to combine with the original map.