Object that maps unique keys to values
expand all in page
Description
A Map object is a data structure that allows you to retrieve values using a corresponding key. Keys can be real numbers or character vectors. As a result, they provide more flexibility for data access than array indices, which must be positive integers. Values can be scalar or nonscalar arrays.
Creation
Syntax
M = containers.Map(keySet,valueSet)
M = containers.Map(keySet,valueSet,'UniformValues',isUniform)
M = containers.Map('KeyType',kType,'ValueType',vType)
M = containers.Map
Description
Note
dictionary is recommended over containers.Map because it accepts more data types as keys and values and provides better performance. (since R2022b)
example
M = containers.Map(keySet,valueSet) creates a Map object that contains keys from keySet, each mapped to a corresponding value from valueSet. The input arguments keySet and valueSet must have the same number of elements, with keySet having elements that are unique.
example
M = containers.Map(keySet,valueSet,'UniformValues',isUniform), where isUniform is false, specifies that the values in valueSet do not need to be uniform. The default value of isUniform is true. The values in valueSet are uniform when they are all scalars that have the same data type, or when they are all character vectors.
example
M = containers.Map('KeyType',kType,'ValueType',vType) creates an empty Map object and specifies the data types of the keys and values you can add to it later. You can switch the order of the 'KeyType' and 'ValueType' name-value pair arguments, but both name-value pairs are required.
M = containers.Map creates an empty Map object.
Input Arguments
expand all
keySet — Keys
numeric array | cell array of character vectors | string array
Keys, specified as a numeric array, cell array of character vectors, or string array.
If you specify keys using a string array, then the containers.Map function converts the keys and stores them as character vectors. Because of this conversion, the KeyType property of the output Map object is set to 'char'.
valueSet — Values
array
Values, specified as an array.
isUniform — Indicator of uniform values
true (default) | false
Indicator of uniform values in valueSet, specified as true (1) or false (0).
kType — Data type of keys
'char' (default) | 'double' | 'single' | 'int32' | 'uint32' | 'int64' | 'uint64'
Data type of the keys to be added to an empty Map object, specified as a character vector. You can specify kType as any of the data types in the table, so that keys are either character vectors or numeric scalars.
kType | Data Type and Size of Key |
|---|---|
| Character vector |
| Double scalar |
| Single scalar |
| 32-bit signed integer scalar |
| 32-bit unsigned integer scalar |
| 64-bit signed integer scalar |
| 64-bit unsigned integer scalar |
vType — Data type of values
'any' (default) | 'char' | 'logical' | 'double' | 'single' | 'int8' | 'uint8' | ...
Data type of the values to be added to an empty Map object, specified as a character vector. You can specify vType as any of the data types in the table.
vType | Data Type and Size of Value |
|---|---|
| Array that has any data type |
| Character vector |
| Logical scalar |
| Double scalar |
| Single scalar |
| 8-bit signed integer scalar |
| 8-bit unsigned integer scalar |
| 16-bit signed integer scalar |
| 16-bit unsigned integer scalar |
| 32-bit signed integer scalar |
| 32-bit unsigned integer scalar |
| 64-bit signed integer scalar |
| 64-bit unsigned integer scalar |
Properties
expand all
Count — Number of key-value pairs
numeric scalar
This property is read-only.
Number of key-value pairs in the Map object, specified as a numeric scalar.
KeyType — Data type of keys
'char' (default) | character vector
This property is read-only.
Data type of the keys, specified as a character vector.
ValueType — Data type of values
'any' (default) | character vector
This property is read-only.
Data type of the values, specified as a character vector.
Object Functions
| isKey | Determine if Map object contains key |
| keys | Return keys of Map object |
| length | Number of key-value pairs in Map object |
| remove | Delete key-value pairs from Map object |
| size | Size of Map object |
| values | Return values of Map object |
Examples
collapse all
Create Map
Open Live Script
Create a Map object that contains rainfall data for several months. The map contains the four values in valueSet, and the keys are the four month names in keySet.
keySet = {'Jan','Feb','Mar','Apr'};valueSet = [327.2 368.2 197.6 178.4];M = containers.Map(keySet,valueSet)M = Map with properties: Count: 4 KeyType: char ValueType: double
Display the rainfall for March. You can retrieve the value for March by using 'Mar' as the key.
M('Mar')ans = 197.6000
Display the number of values in the map. You can access the Count property using dot notation.
M.Count
ans = uint64 4Specify Numbers as Keys
Open Live Script
Create a Map object with identification numbers as keys and employee names as values.
ids = [437 1089 2362];names = {'Lee, N.','Jones, R.','Sanchez, C.'};M = containers.Map(ids,names)M = Map with properties: Count: 3 KeyType: double ValueType: char
Retrieve a name using an identification number as a key.
M(437)
ans = 'Lee, N.'
Store Values That Are Not Uniform
Open Live Script
Create a Map object that contains test results for patients. For any patient, the results might be in either a numeric array or in a file. You can store numeric arrays and file names as values in the same map. To store values that do not have the same data type in the same map, specify 'UniformValues',false.
keySet = {'Li','Jones','Sanchez'};testLi = [5.8 7.35];testJones = [27 3.92 6.4 8.21];testSanchez = 'C:\Tests\Sanchez.dat';valueSet = {testLi,testJones,testSanchez};M = containers.Map(keySet,valueSet,'UniformValues',false)M = Map with properties: Count: 3 KeyType: char ValueType: any
Display the numeric array associated with Li.
M('Li')ans = 1×2 5.8000 7.3500Display the file name associated with Sanchez. If the file contains numeric values, you could then call a function to read those values into an array.
M('Sanchez')ans = 'C:\Tests\Sanchez.dat'
Specify Types for Empty Map
Open Live Script
Create an empty Map object. Specify the data types for key-value pairs added later.
M = containers.Map('KeyType','char','ValueType','double')
M = Map with properties: Count: 0 KeyType: char ValueType: double
Add key-value pairs to the map.
M('Jan') = 327.2;M('Feb') = 368.2;M
M = Map with properties: Count: 2 KeyType: char ValueType: double
Display the keys and values that the map now contains.
keys(M)
ans = 1x2 cell {'Feb'} {'Jan'}values(M)
ans=1×2 cell array {[368.2000]} {[327.2000]}Extended Capabilities
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.
This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.
Version History
Introduced in R2008b
See Also
dictionary | keys | isKey | values | cell | struct | table
Topics
- Map Data with Dictionaries
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- Deutsch
- English
- Français
- United Kingdom (English)
Contact your local office
