Read and Write Using Key Index

When reading from the Map, use the same keys that you have defined and associated with particular values. Writing new entries to the Map requires that you supply the values to store with a key for each one.

Note

For a large Map, the keys and value methods use a lot of memory as their outputs are cell arrays.

Read From Map

After you have constructed and populated your Map, you can begin to use it to store and retrieve data. You use a Map in the same manner that you would an array, except that you are not restricted to using integer indices. The general syntax for looking up a value (valueN) for a given key (keyN) is shown here. If the key is a character vector, enclose it in single quotation marks:

valueN = mapObj(keyN);

Start with the Map ticketMap :

ticketMap = containers.Map(...
    {'2R175', 'B7398', 'A479GY', 'NZ1452'}, ...
    {'James Enright', 'Carl Haynes', 'Sarah Latham', ...
     'Bradley Reid'});

You can find any single value by indexing into the Map with the appropriate key:

passenger = ticketMap('2R175')

passenger =

James Enright

Find the person who holds ticket A479GY:

sprintf('   Would passenger %s please come to the desk?\n', ...
    ticketMap('A479GY'))

ans =

   Would passenger Sarah Latham please come to the desk?

To access the values of multiple keys, use the values method, specifying the keys in a cell array:

values(ticketMap, {'2R175', 'B7398'})

ans = 

    'James Enright'    'Carl Haynes'

Map containers support scalar indexing only. You cannot use the colon operator to access a range of keys as you can with other MATLAB^® classes. For example, the following statements throw an error:

ticketMap('2R175':'B7398')
ticketMap(:)

Add Key/Value Pairs

Unlike other array types, each entry in a Map consists of two items: the value and its key. When you write a new value to a Map, you must supply its key as well. This key must be consistent in type with any other keys in the Map.

Use the following syntax to insert additional elements into a Map:

existingMapObj(newKeyName) = newValue;

Start with the Map ticketMap :

ticketMap = containers.Map(...
    {'2R175', 'B7398', 'A479GY', 'NZ1452'}, ...
    {'James Enright', 'Carl Haynes', 'Sarah Latham', ...
     'Bradley Reid'});

Add two more entries to the ticketMap Map. Verify that ticketMap now has six key/value pairs:

ticketMap('947F4') = 'Susan Spera';
ticketMap('417R93') = 'Patricia Hughes';

ticketMap.Count

ans =

                    6

List all of the keys and values in ticketMap:

keys(ticketMap),  values(ticketMap)

ans = 

    '2R175'    '417R93'    '947F4'    'A479GY'    'B7398'    'NZ1452'


ans = 

    'James Enright'    'Patricia Hughes'    'Susan Spera'    'Sarah Latham'    'Carl Haynes'    'Bradley Reid'

Build Map with Concatenation

You can add key/value pairs to a Map in groups using concatenation. The concatenation of Map objects is different from other classes. Instead of building a vector of Map objects, MATLAB returns a single Map containing the key/value pairs from each of the contributing Map objects.

Rules for the concatenation of Map objects are:

Only vertical vectors of Map objects are allowed. You cannot create an m-by-n array or a horizontal vector of Map objects. For this reason, vertcat is supported for Map objects, but not horzcat.
All keys in each Map being concatenated must be of the same class.

You can combine Maps with different numbers of key/value pairs. The result is a single Map object containing key/value pairs from each of the contributing Map objects:

tMap1 = containers.Map({'2R175', 'B7398', 'A479GY'}, ...
    {'James Enright', 'Carl Haynes', 'Sarah Latham'});

tMap2 = containers.Map({'417R93', 'NZ1452', '947F4'}, ...
    {'Patricia Hughes', 'Bradley Reid', 'Susan Spera'});

% Concatenate the two maps:
ticketMap = [tMap1; tMap2];

The result of this concatenation is the same 6-element Map that was constructed in the previous section:

ticketMap.Count

ans =

                    6

keys(ticketMap),  values(ticketMap)

ans = 

    '2R175'    '417R93'    '947F4'    'A479GY'    'B7398'    'NZ1452'


ans = 

    'James Enright'    'Patricia Hughes'    'Susan Spera'    'Sarah Latham'    'Carl Haynes'    'Bradley Reid'

Concatenation does not include duplicate keys or their values in the resulting Map object.
In the following example, both objects m1 and m2 use a key of 8. In Map m1, 8 is a key to value C; in m2, it is a key to value X:
```
m1 = containers.Map({1, 5, 8}, {'A', 'B', 'C'});
m2 = containers.Map({8, 9, 6}, {'X', 'Y', 'Z'});
```
Combine m1 and m2 to form a new Map object, m:
```
m = [m1; m2];
```
The resulting Map object m has only five key/value pairs. The value C was dropped from the concatenation because its key was not unique:
```
keys(m), values(m)

ans = 

    [1]    [5]    [6]    [8]    [9]


ans = 

    'A'    'B'    'Z'    'X'    'Y'
```

Documentation