containers.Map class

Package: containers

Map values to unique keys

Description

A Map object is a data structure that allows you to retrieve values using a corresponding key. Keys can be real numbers or text strings and provide more flexibility for data access than array indices, which must be positive integers. Values can be scalar or nonscalar arrays.

Construction

mapObj = containers.Map constructs an empty Map container mapObj.

mapObj = containers.Map(keySet,valueSet) constructs a Map that contains one or more values and a unique key for each value.

mapObj = containers.Map(keySet,valueSet,'UniformValues',isUniform) specifies whether all values must be uniform (either all scalars of the same data type, or all strings). Possible values for isUniform are logical true (1) or false (0).

mapObj = containers.Map('KeyType',kType,'ValueType',vType) constructs an empty Map object and sets the KeyType and ValueType properties. The order of the key type and value type argument pairs is not important, but both pairs are required.

Input Arguments

keySet

1-by-n array that specifies n unique keys for the map.

All keys in a Map object are real numeric values or all keys are strings. If n > 1 and the keys are strings, keySet must be a cell array. The number of keys in keySet must equal the number of values in valueSet.

valueSet

1-by-n array of any class that specifies n values for the map. The number of values in valueSet must equal the number of keys in keySet.

'UniformValues'

Parameter string to use with the isUniform argument.

isUniform

Logical value that specifies whether all values are uniform. If isUniform is true (1), all values must be scalars of the same data type, or all values must be strings. If isUniform is false (0), then containers.Map sets the ValueType to 'any'.

Default: true for empty Map objects, otherwise determined by the data types of values in valueSet.

'KeyType'

Parameter string to use with the kType argument.

kType

String that specifies the data type for the keys. Possible values are 'char', 'double', 'single', 'int32', 'uint32', 'int64', or 'uint64'.

Default: 'char' for empty Map objects, otherwise determined by the data types of keys in keySet. If you specify keys of different numeric types, kType is 'double'.

'ValueType'

Literal string parameter to use with the vType argument.

vType

String that specifies the data type for the values. Possible values are 'any', 'char', 'logical', 'double', 'single', 'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'int64', or 'uint64'.

Default: 'any' when you create an empty Map object or when you specify values of different sizes or types, otherwise determined by the data type of valueSet.

Properties

Count

Unsigned 64-bit integer that represents the total number of key-value pairs contained in the Map object. Read only.

KeyType

Character array that indicates the data type of all keys in the Map object. The default KeyType for empty Map objects is 'char'. Otherwise, KeyType is determined from the data type of the keySet inputs. Read only.

ValueType

Character array that indicates the data type of all values in the Map object. If you construct an empty Map object or specify values with different data types, then the value of ValueType is 'any'. Otherwise, ValueType is determined from the data type of the valueSet inputs. Read only.

Methods

isKeyDetermine if containers.Map object contains key
keysIdentify keys of containers.Map object
lengthLength of containers.Map object
removeRemove key-value pairs from containers.Map object
sizeSize of containers.Map object
valuesIdentify values in containers.Map object

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB® documentation.

Examples

Construct a Map and View Properties

Construct a Map object that contains rainfall data for several months:

keySet =   {'Jan', 'Feb', 'Mar', 'Apr'};
valueSet = [327.2, 368.2, 197.6, 178.4];
mapObj = containers.Map(keySet,valueSet)

This code returns a description of the map, including the property values:

mapObj = 

  containers.Map handle
  Package: containers

  Properties:
        Count: 4
      KeyType: 'char'
    ValueType: 'double'

  Methods, Events, Superclasses

Get a specific property using dot notation, such as

mapObj.Count

which returns

ans =
                    4

Look Up Values in a Map

Use the map created in the previous example to find the rainfall data for February:

rainFeb = mapObj('Feb')

This code returns

rainFeb =
  368.2000

Add a Single Value and Key to a Map

Add data for the month of May to the map created in the first example:

mapObj('May') = 100.0;

Add Multiple Values and Keys by Concatenating Maps

Create a map that contains rainfall data for June, July, and August, and add the data to mapObj (from previous examples):

keySet   = {'Jun','Jul','Aug'};
valueSet = [ 69.9, 32.3, 37.3];
newMap = containers.Map(keySet,valueSet);

mapObj = [mapObj; newMap];

Map objects only support vertical concatenation (that is, adding columns with a semicolon, ;). When concatenating maps, the data type of all values must be consistent with the ValueType of the leftmost map. In this example, both maps have the a ValueType of double.

Get the Keys or Values in a Map

Determine all the keys of mapObj (from previous examples) by calling the keys method:

allKeys = keys(mapObj)

This method returns the keys in alphabetical order:

allKeys = 
    'Apr'    'Aug'    'Feb'    'Jan'    'Jul'    'Jun'    'Mar'    'May'

Get multiple values from the map by calling the values method. Like the keys method, you can request all values with the syntax values(mapObj). Alternatively, request values for specific keys. For example, view the values for March, April, and May in mapObj:

springValues = values(mapObj,{'Mar','Apr','May'})

This method returns the values in a cell array, in the order corresponding to the specified keys:

springValues = 
    [197.6000]    [178.4000]    [100]

Remove Keys and Values

Remove the data for March and April from mapObj (from previous examples) by calling the remove method, and view the remaining keys:

remove(mapObj,{'Mar','Apr'});
keys(mapObj)

This code returns

ans = 
    'Aug'    'Feb'    'Jan'    'Jul'    'Jun'    'May'

Create a Map with Nonscalar Values

Map integer keys to nonscalar arrays, and view the value for one of the keys:

keySet = [5,10,15];
valueSet = {magic(5),magic(10),magic(15)};
mapObj = containers.Map(keySet,valueSet);
mapObj(5)

This code returns

ans =
    17    24     1     8    15
    23     5     7    14    16
     4     6    13    20    22
    10    12    19    21     3
    11    18    25     2     9

Construct an Empty Map

Construct a map with no values, but set the KeyType and ValueType properties:

mapObj = containers.Map('KeyType','char','ValueType','int32')

This code returns

mapObj = 

  containers.Map handle
  Package: containers

  Properties:
        Count: 0
      KeyType: 'char'
    ValueType: 'int32'

  Methods, Events, Superclasses

Specify Whether Values Are Uniform

Construct a map with numeric values, and specify that the values do not have to be uniform:

keySet = {'a','b','c'};
valueSet = {1,2,3};
mapObj = containers.Map(keySet,valueSet,'UniformValues',false);

This map allows nonnumeric values, so

mapObj('d') = 'OK';
values(mapObj)

returns

ans = 
    [1]    [2]    [3]    'OK'

See Also

| |

Was this topic helpful?