Learn more about MATLAB

containers.Map - Construct containers.Map object

Syntax

M = containers.Map
M = containers.Map(keys, values)
M = containers.Map(keys, values, 'uniformvalues', tf)

Description

The Map object is a data structure that is a container for other data. A Map container is similar to an array except for the means by which you index into the data stored inside the map. Instead of being restricted to the use of integer array indices 1 through N, you select elements of a Map container using indices of various data types, (strings, for example). A map consists of keys (the indices) and data values and is a handle object.

M = containers.Map constructs a Map container object M to hold data values that you can easily reference using keys that you establish. M is a handle object with properties Count, KeyType, and ValueType. These properties represent the number of keys in the map, the type of these keys, and the type of the values assigned to those keys respectively.

When you call the containers.Map constructor with no input arguments, MATLAB constructs an empty Map object, setting the Count , KeyType, and 'ValueType' properties to 0, char, and 'any', respectively.

M = containers.Map(keys, values) constructs a Map object M that contains one or more keys and a value for each of these keys, as specified in the keys and values arguments. A value is some unit of data that you want stored in the Map object, and a key is a unique reference to that data. Valid data types for the keys argument are any real-valued scalars or character arrays. This includes char, double, int32, uint32, int64, or uint64. Valid values are the same, plus the string 'any'.

To specify multiple keys, make the keys argument a 1-by-n cell array, where n is the number of keys to be stored in the map. Elements of this cell array should belong to the same type. You can specify values of mixed numeric, or numeric and logical, types, without generating an error. If you do this, the Map constructor converts all elements to the type of the leftmost element in the keys cell array. To specify multiple values, use a 1-by-n cell array, where n is equal to numel (keys). There must be exactly one value for each key argument.

Object M has properties Count, KeyType, and ValueType. Count is a string that contains the number of key-value pairs in the Map object once the map has been constructed. KeyType is a character array containing the data type of the keys in the map. All keys belong to the same data type. ValueType is a character array containing the data type of the values in the map. If these values are of different data types, ValueType is set to the string 'any'.

M = containers.Map(keys, values, 'uniformvalues', tf) constructs Map M in which all values are required to be of the same type when uniformvalues is set to logical 1 (true). If they are not, MATLAB throws an error. If you want to be able to store values of mixed types, set uniformvalues to logical 0 (false). This flag is only needed if you want to override the default.

Read more about Map Containers in the MATLAB Programming Fundamentals documentation.

Properties

Property	Description
Count	Unsigned 64-bit integer that represents the total number of key-value pairs contained in the Map object when the initial object is constructed.
KeyType	Character array that indicates the data type of all keys contained in the Map object.
ValueType	Character array that indicates the data type of all values contained in the Map object. If not all values have the same data type, then ValueType is 'any'.

Methods

Method	Description
isKey	Check if containers.Map object contains key.
keys	Return all keys of containers.Map object.
size	Return size of containers.Map object.
length	Return length of containers.Map object.
values	Return all values of containers.Map object in cell array.
remove	Remove key-value pairs from containers.Map.

Examples

Example 1 — Constructing a New Map Object

Construct a one-member Map object, US_Capitals:

US_Capitals = containers.Map('Arizona', 'Phoenix');

To call methods of the class, just use the method name followed by the name of the Map object in parentheses. Call the keys and values methods of the US_Capitals object you just constructed:

keys(US_Capitals), values(US_Capitals)
ans = 
    'Arizona'
ans = 
    'Phoenix'

Example 2 — Finding Map Properties

List the properties of the US_Capitals object:

properties(US_Capitals)

Properties for class containers.Map:
    Count
    KeyType
    ValueType

Examine each property:

US_Capitals.Count,
ans =
    1

US_Capitals.KeyType
ans =
    char

US_Capitals.ValueType
ans =
    char

Example 3 — Storing Multiple Keys and Values

Construct a new Map object and store 6 key and value parameters in it. Specify multiple keys and values by listing them in a cell array as shown here:

US_Capitals = containers.Map( ...
{'Arizona', 'Nebraska', 'Nevada', ...       % 6 States
 'New York', 'Georgia', 'Alaska'}, ...
{'Phoenix', 'Lincoln', 'Carson City', ...   % 6 Capitals
 'Albany', 'Atlanta', 'Juneau'})

US_Capitals = 
  containers.Map handle
  Package: containers

  Properties:
        Count: 6
      KeyType: 'char'
    ValueType: 'char'
  Methods, Events, Superclasses

Example 4 — Displaying the Map Contents

Use the keys and values methods to see the mapping order defined within the map. The keys method lists all keys of the character array type in alphabetical order. The values method lists the value associated with each of these keys. These are listed in an order determined by their associated keys:

keys(US_Capitals),  values(US_Capitals)
ans = 
    'Alaska'  'Arizona'  'Georgia'  'Nebraska'  'Nevada'
 
  'New York'
ans = 
   'Juneau'  'Phoenix'  'Atlanta'  'Lincoln'  'Carson City'
   'Albany'

When using the values method, you can either list all values in the map, as shown above, or list only those values that belong to those keys you specify in the command:

values(US_Capitals, {'Arizona', 'New York', 'Nebraska'})
ans = 
    'Phoenix'    'Albany'    'Lincoln'

Example 5— Adding More Keys and Values Later

Once the object has been created, store two additional keys (Vermont and Oregon), and their related values (Montpelier and Salem) in it. You do not need to call the constructor this time as you are adding to an existing Map object:

US_Capitals('Vermont') = 'Montpelier';
US_Capitals('Oregon') = 'Salem';
keys(US_Capitals)
ans = 
    'Alaska'    'Arizona'    'Georgia'    'Nebraska'
    'Nevada'    'New York'    'Oregon'    'Vermont'

Note that the Count property has gone from 6 to 8:

US_Capitals.Count
ans =
    8

If you want to add more than one key-value pair at a time, you can concatenate your existing map with a new map that contains the new keys and values that you want to add. Only vertical concatenation is allowed. This example adds four more state/capital pairs to the US_Capitals map in just one concatenation operation. The US_Capitals map now contains twelve key-value pairs:

newSta = {'New Jersey', 'Ohio', 'Delaware', 'Montana'};
newCap = {'Trenton', 'Columbus', 'Dover', 'Helena'};
newMap = containers.Map(newSta, newCap);

% Construct a new map. Concatenate it to the existing one.
	US_Capitals = [US_Capitals; newMap]
US_Capitals = 
  containers.Map handle
  Package: containers

  Properties:
        Count: 12
      KeyType: 'char'
    ValueType: 'char'
  Methods, Events, Superclasses

Example 6— Looking Up Values with the Map

Use the map to find the capital cities of two states in the US:

S1 = 'Alaska';   S2 = 'Arizona'
sprintf('\nThe capitals of %s and %s are %s and %s.', ...
        S1, S2, US_Capitals(S1), US_Capitals(S2))

ans =
The capitals of Alaska and Arizona are Juneau and Phoenix.

Example 7— Removing Keys and Values

To remove a key-value pair, use the remove method of the Map class, as shown here:

keys(US_Capitals)
ans = 
  Columns 1 through 6
    'Alaska'    'Arizona'    'Delaware'    'Georgia'    'Montana'    'Nebraska'
  Columns 7 through 12
    'Nevada'    'New Jersey'    'New York'    'Ohio'    'Oregon'    'Vermont'

remove(US_Capitals, {'Nebraska', 'Nevada', 'New York'});

keys(US_Capitals)
ans = 
  Columns 1 through 6
    'Alaska'    'Arizona'    'Delaware'    'Georgia'    'Montana'    'New Jersey'
  Columns 7 through 9
    'Ohio'    'Oregon'    'Vermont'

Removing keys and their values from the Map object also decrements the setting of the Count property.

See Also

keys(Map), values(Map), size(Map), length(Map), isKey(Map), remove(Map), handle

makehgtform

mat2cell

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS