Table of Contents

Maps

What is a map?

A map is a collection that stores key-value pairs. Think of it like a dictionary: you look up a word (the key) and find its definition (the value).

Arrays use numbers (indices) to find values. Maps use any value — usually strings — as keys. This makes them perfect for situations where you want to associate one thing with another.

Key        →  Value
"name"     →  "Alice"
"age"      →  "25"
"city"     →  "Berlin"

Creating a map

In Nyx, you create a map with Map.new():

fn main() {
    var m: Map = Map.new()
    print(m)
}

Maps start empty. You fill them by inserting key-value pairs.

Inserting values

Use .insert(key, value) to add entries:

fn main() {
    var m: Map = Map.new()

    m.insert("name", "Alice")
    m.insert("language", "Nyx")
    m.insert("version", "0.12.0")

    print(m)
}

If you insert a key that already exists, the old value is replaced:

fn main() {
    var m: Map = Map.new()

    m.insert("color", "red")
    print(m.get("color"))    // red

    m.insert("color", "blue")
    print(m.get("color"))    // blue
}

Getting values

Use .get(key) to retrieve a value:

fn main() {
    var m: Map = Map.new()
    m.insert("capital", "Paris")
    m.insert("population", "67 million")

    print(m.get("capital"))       // Paris
    print(m.get("population"))    // 67 million
}

Checking if a key exists

Use .contains(key) to check whether a key is in the map:

fn main() {
    var m: Map = Map.new()
    m.insert("name", "Nyx")

    print(m.contains("name"))      // true
    print(m.contains("version"))   // false
}

This is useful to avoid errors when a key might not exist.

Removing entries

Use .remove(key) to delete a key-value pair:

fn main() {
    var m: Map = Map.new()
    m.insert("x", "10")
    m.insert("y", "20")

    print(m.size())    // 2

    m.remove("x")
    print(m.size())    // 1
    print(m.contains("x"))    // false
}

Map size

Use .size() to know how many entries a map has:

fn main() {
    var m: Map = Map.new()
    print(m.size())    // 0

    m.insert("a", "1")
    m.insert("b", "2")
    m.insert("c", "3")
    print(m.size())    // 3
}

When to use maps vs arrays

Use an array when:

Use a map when:

For example, a list of scores by player name is a perfect use case for a map:

fn main() {
    var scores: Map = Map.new()
    scores.insert("Alice", "95")
    scores.insert("Bob", "87")
    scores.insert("Charlie", "92")

    print(scores.get("Bob"))    // 87
}

Practical example: word counter

Count how many times each word appears in a list:

fn main() {
    let words: Array = ["hello", "world", "hello", "nyx", "hello", "world"]

    var counts: Map = Map.new()
    var i: int = 0
    while i < words.length() {
        let word: String = words[i]
        if counts.contains(word) {
            let current: int = string_to_int(counts.get(word))
            counts.insert(word, int_to_string(current + 1))
        } else {
            counts.insert(word, "1")
        }
        i += 1
    }

    print("hello: " + counts.get("hello"))    // hello: 3
    print("world: " + counts.get("world"))    // world: 2
    print("nyx: " + counts.get("nyx"))        // nyx: 1
}

Note: map values are stored as strings in Nyx, so we convert between int and String with string_to_int() and int_to_string().

Practical example: simple config

fn load_defaults() -> Map {
    var config: Map = Map.new()
    config.insert("port", "8080")
    config.insert("host", "localhost")
    config.insert("debug", "false")
    return config
}

fn main() {
    let cfg: Map = load_defaults()

    print("Server: " + cfg.get("host") + ":" + cfg.get("port"))
    // Server: localhost:8080
}

Exercises

  1. Create a map that stores the capitals of 5 countries. Then print the capital of each country.
  1. Write a function map_has_value(m: Map, value: String) -> bool that returns true if any key in the map has the given value. Hint: you will need to check each key you know about.
  1. Write a program that counts how many times each character appears in a string. Hint: loop through the string with .charAt(), convert each character to a string with char_to_string(), and use a map to count.
  1. Create a "phone book" map with 5 names and phone numbers. Write a function that takes a name and the map, and prints the phone number or "Not found".
  1. Write a function that takes two maps and returns a new map with all entries from both. If both maps have the same key, use the value from the second map.

Summary

Next chapter: Structs →

← Previous: Strings Next: Structs →