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 object.

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 three different ways.

Iterating over a map directly returns key-value tuples which you can unpack in a for-loop as shown below:

for (key, value) in map {
    echo key;
    echo value;
}

The :keys() method returns an iterator over the map's keys:

for key in map:keys() {
    echo key;
}

The :values() method returns an iterator over the map's values:

for value in map:values() {
    echo value;
}

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 char 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.
: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.
:iter() -> iter[tup]: Returns an iterator over (key, value) tuples.
: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.