MAPS

A list finds things by their position: item 1, item 2, item 3. Often you want to find something by a name instead: a phone number by a person’s name, a price by the name of the thing, a score by the player. A container that files each value under a key is called a map, or a dictionary.

In satellite it is satellite.container.map. It keeps its keys in the order you put them in, the way a Python dictionary does, so a map prints back in the order you filled it. The same container has a second word, satellite.container.index: either word declares it, and you will see index in some older examples.

Filing and finding

Declare a map with the type of its keys and the type of its values between < and >. Then age["zoe"] = 30 files 30 under the key "zoe", and age["zoe"] reads it back. Writing to a key that is already there changes its value and does not move it.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.map<satellite.variable.string, satellite.variable.number> age
    age["zoe"] = 30
    age["al"] = 4
    age["bo"] = 100
    age["zoe"] = 31
    satellite.console.display(age)
    satellite.console.display(age["al"])
    satellite.console.display(age.keys)
    satellite.console.display(age.values)
    satellite.console.display(age.contains("bo"))
    satellite.console.display(age.values.sum)
    satellite.console.display(age.keys.join(", "))

    age.remove("al")
    satellite.console.display(age.size)
    satellite.console.display(age.first)
    satellite.console.display(age.last)
    satellite.return(satellite)
}

{"zoe": 31, "al": 4, "bo": 100}
4
{"zoe", "al", "bo"}
{31, 4, 100}
true
135
zoe, al, bo
2
zoe
bo

What each of those does:

• age.keys and age.values answer two lists, in the same order, so the first key goes with the first value.
• .contains(key) answers true or false. Ask it before you read a key you are not sure of.
• .values.sum and .keys.join(", ") are list words used on those lists. On a map you say which half you mean.
• .remove(key) takes a key and its value out. .size, .empty and .clear() work as they do on a list.
• .first and .last are the oldest and the newest key. .remove_first() and .remove_last() take those out.

A map has keys, not positions, so the list words that need a position, such as .append, .insert and .index_of, are refused on one.

Writing a map whole

Braces make a map when each entry is a key, a : and a value: {"zoe": 30, "al": 4}. That is the same form satl prints a map in, so what you see is what you can write. A key written twice keeps its first place and its last value. An empty map is a declaration with nothing after it, or satellite.container.map(); {} on its own is an empty list.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.map<satellite.variable.string, satellite.variable.number> price = {"tea": 3, "cake": 5, "tea": 4}
    satellite.console.display(price)
    satellite.console.display(price["tea"])

    satellite.container.map<satellite.variable.number, satellite.variable.string> rooms = satellite.container.map()
    rooms[101] = "Ada"
    rooms[102] = "Grace"
    satellite.console.display(rooms)
    satellite.return(satellite)
}

{"tea": 4, "cake": 5}
4
{101: "Ada", 102: "Grace"}

What can be a key

A key must be something that cannot change once it is filed: a number, a string, a bool, a binary or a percentage. A list can never be a key. 1 and "1" are two different keys. A value can be anything at all, a list or another map included, and a map with no <> takes any key and any value.

A list filed under a key is reached the same way as any list, so teams["red"][2] is the second name on the red team. To go through every entry, take the keys as a list and walk it with a for loop:

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.map<satellite.variable.string, satellite.container.list> teams
    teams["red"] = {"ann", "bo"}
    teams["blue"] = {"cy"}
    teams["red"].append("dee")
    satellite.console.display(teams)
    satellite.console.display(teams["red"][2])

    satellite.container.list<satellite.variable.string> names = teams.keys
    satellite.statement.for(satellite.variable.number i = 1; i <= names.size; i++)
    {
        satellite.variable.string team = names[i]
        satellite.console.display(team + ": " + teams[team].join(", "))
    }

    satellite.container.map anything
    anything[1] = "the number one"
    anything["1"] = "the text one"
    satellite.console.display(anything.size)
    satellite.return(satellite)
}

{"red": {"ann", "bo", "dee"}, "blue": {"cy"}}
bo
red: ann, bo, dee
blue: cy
2

Two maps are equal, ==, when they hold the same keys with the same values, whatever order those went in. Like a list, a map is a value: b = a copies it.

Containers nest to any depth: a list of maps of lists, a map of maps. What you declare is checked all the way down, and satellite.access(name) shows you how to reach every level of one. ANY CONTAINER IN ANY CONTAINER walks through it.

A key that is not there

Reading a key the map does not hold is refused. satl does not quietly hand you nothing, because a made-up answer is worse than a clear stop.

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.container.map<satellite.variable.string, satellite.variable.number> age
    age["zoe"] = 30
    satellite.console.display(age["max"])
    satellite.return(satellite)
}

--------------------------------------------------------------------------------
SATELLITE CRITICAL ERROR REPORT
--------------------------------------------------------------------------------
S501: LINE_PAST_THE_END
satl(run): age[max]: there is no such key in it -- it holds 1 key

directory: missing_key.satl:7
syntax: satellite.console.display(age["max"])
                                     /\

a line was read by its number and the file has no line with that number. Lines
count from 1, and the last one is the file's size.
machine code 47 line_past_the_end -- satl exits with this.

--------------------------------------------------------------------------------

The second line is the one that matters here: there is no key max, and the map holds 1 key. The paragraph under the caret is the general text for this report, which was written for lines of a file.

Where next

Every map word is in the FULL REFERENCE. For the lists that a map hands back from .keys and .values, see LISTS, and for a name that may hold one of several types, see MULTIPLE: ONE NAME, SEVERAL TYPES.