Hash Maps

Map Literals
Indexing
Iterating
Containment
Key Types
Value Types
Methods

A hash map, map, is a collection of key-value pairs.

$map() -> map: Creates a new map.

Pyro's map type preserves insertion order so when you iterate over a map you get its entries back in the same order you inserted them.

Map Literals

You can create a map using literal syntax, e.g.

var map = {"foo" = 123, "bar" = 456};

Trailing commas are allowed, e.g.

var map = {
    "foo" = 123,
    "bar" = 456,
};

The empty literal {} will create an empty map.

Indexing

You can index into a map to get or set entries, e.g.

var map = {"foo" = 123, "bar" = 456};
assert map["foo"] == 123;
assert map["bar"] == 456;

map["bar"] = 789;
assert map["bar"] == 789;

Indexing is equivalent to using the map's :get() and :set() methods, e.g.

var map = {"foo" = 123, "bar" = 456};
assert map:get("foo") == 123;
assert map:get("bar") == 456;

map:set("bar", 789);
assert map:get("bar") = 789;

If the map doesn't contain an entry corresponding to key, the expression map[key] will return an err, e.g.

var map = {"foo" = 123, "bar" = 456};
assert $is_err(map["baz"]);
assert $is_err(map:get("baz"));

Iterating

You can iterate over a map in four different ways.

Iterating over a map directly returns the map's entries as (key, value) tuples which you can unpack in a for-loop, e.g.
```
for (key, value) in map {
    echo key;
    echo value;
}
```
The :keys() method returns an iterator over the map's keys, e.g.
```
for key in map:keys() {
    echo key;
}
```
The :values() method returns an iterator over the map's values, e.g.
```
for value in map:values() {
    echo value;
}
```
The :entries() method returns an iterator over the map's entries as (key, value) tuples, e.g.
```
for (key, value) in map:entries() {
    echo key;
    echo value;
}
```
This is equivalent to iterating over the map directly.

Containment

You can check if a map contains a key using the in operator:

var map = {
    "foo" = 123,
    "bar" = 456,
};

if "foo" in map {
    echo "found";
}

This is equivalent to calling the map's :contains() method.

Key Types

You can use any Pyro value as a key in a map. The only requirement is that key values which compare as equal using the == operator should also have the same hash value. This is true for all builtin types.

Pyro checks for key equality using the == operator. Note that i64, f64, and rune values which are numerically equal compare as equal using the == operator. This means that these values work interchangeably as map keys, e.g.

var map = {
    65 = "foo",
    66 = "bar",
};

assert map['A'] == "foo";
assert map[66.0] == "bar";

Value Types

You can use any Pyro value as a value in a map.

Methods

:clear(): Removes all entries from the map.
:contains(key: any) -> bool: Returns true if the map contains key, otherwise false.
:copy() -> map: Returns a copy of the map.
:count() -> i64: Returns the number of entries in the map.
:entries() -> iter[tup]: Returns an iterator over the map's entries as (key, value) tuples.
:get(key: any) -> any: Returns the value associated with key or an err if key was not found.
:is_empty() -> bool: Returns true if the map is empty.
:keys() -> iter: Returns an iterator over the map's keys.
:remove(key: any): Deletes the entry for key, if it exists. Does nothing if the map has no entry for key.
:set(key: any, value: any): Adds a new entry to the map or updates an existing entry.
:values() -> iter: Returns an iterator over the map's values.