Chapter 5. Mappings

Table of Contents
5.1. Initializing Mappings
5.2. Testing With Mappings
5.3. Adding and Removing key/value Pairs from a Mapping
5.4. Accessing Elements in Mappings
5.5. Keys and Values
5.6. Size of a Mapping
5.7. Complex Mappings
5.8. Iterating Over Sorted Mappings
5.9. Common Errors

You know what an array is. An array is a list of buckets where one thing is stored in each bucket. To find something specific in the array you start at the first bucket and for each bucket in the array of buckets you ask yourself, "Is this the bucket I'm looking for?"

Additionally, with arrays, there's an association of an index to a specific bucket. The first item in the array is index 0, the second item is index 1, the nth item is index n - 1.

For some things, this is a good way of doing it. However, for other things, this process is terribly inefficient. It'd be much more efficient if instead of looking in each bucket in order, we could know which bucket the thing we're looking for is probably in. Additionally, there are situations where you want to associate other kinds of keys with a specific value.

LPC provides a datatype called a "mapping" for this purpose. Other languages call it a "map", "hashmap" or a "dictionary". The goal of a mapping is to map a "key" to a corresponding "value". That's all it is.

For example, we use mappings to keep track of exits (the key) and the rooms they exit to (the value). For example, we might have a room which has an exit to the north and an exit to the south. This room would have an exits mapping with two keys in it:


  mapping exits;

  exits = ([
             "north": "/d/Science/cities/meridia/rooma.c",
             "south": "/d/Science/cities/meridia/roomc.c"
          ]);

This chapter will talk about mappings and how to manipulate them.

5.1. Initializing Mappings

You can call functions which return mappings. You can also create your own mappings. LPC uses ([ ]) to denote a mapping. Examples of mappings:

Example 5-1. Initializing mappings


  // creates an empty mapping
  mapping m = ([ ]);

  // creates a mapping with one key/value pair in it
  mapping m1 = ([ "north": "/d/Science/cities/meridia/rooma.c" ]);

  // creates a mapping with two key/value pairs in it
  mapping m2 = ([
                  "north": "/d/Science/cities/meridia/rooma.c",
                  "south": "/d/Science/cities/meridia/roomc.c"
               ]);

  // creates a mapping of roman numberals (strings) to integers (ints)
  mapping rntn ([
                  "i": 1,
                  "iv": 4,
                  "v": 5,
                  "ix": 9,
                  "x": 10
               ]);

Mapping values can be anything: integers, floats, strings, arrays, objects, other mappings...

Mapping keys can also be anything.

Mappings can contain keys and values of different data types--though this is probably a bad habit to get into.

Mappings are declared like this:

Example 5-2. Declaring mappings


  mapping m;

Mappings can be initialized in one of two ways. You can have an empty mapping like this:

Example 5-3. Initializing an empty mapping


  mapping m = ([ ]);

or they can be initialized with data like this:

Example 5-4. Initializing a non-empty mapping


  mapping m2 = ([
                  "north": "/d/Science/cities/meridia/rooma.c",
                  "south": "/d/Science/cities/meridia/roomc.c"
               ]);

A mapping must be initialized before you can use it. If you don't have an initialized mapping (i.e. you did mapping m; and haven't assigned a value to that mapping m), then your code will error out.