MATLAB 2022b added the dictionary object. A complete usage guide can be found under Language Fundamentals > Data Types > Dictionaries in the MATLAB documentation.
dictionary is now recommended over the old containers.Map. Quoting the documentation for containers.Map:
dictionary is recommended over containers.Map because it accepts more data types as keys and values and provides better performance. (since R2022b)
From the R2022b Release Notes:
In almost all use cases, dictionary performs faster than containers.Map.
For containers.Map usage, see Amro's answer.
Construction
Dictionaries can be constructed from a set of initial entries by passing key and value arrays with an equal number of entries:
% From key and value arrays
>> d = dictionary(["a", "b", "c"], [1, 2, 3])
d =
dictionary (string ⟼ double) with 3 entries:
"a" ⟼ 1
"b" ⟼ 2
"c" ⟼ 3
Alternatively, initial entries can be provided as key-value pairs:
% Using Name=Value syntax (string keys only)
>> d = dictionary(a=1, b=2, c=3)
d =
dictionary (string ⟼ double) with 3 entries:
"a" ⟼ 1
"b" ⟼ 2
"c" ⟼ 3
>> squares = dictionary(2, 4, 3, 9, 4, 16)
squares =
dictionary (double ⟼ double) with 3 entries:
2 ⟼ 4
3 ⟼ 9
4 ⟼ 16
To create an unconfigured dictionary, you can use dictionary without any inputs:
>> d_unconfigured = dictionary
d_unconfigured =
dictionary with unset key and value types.
The dictionary will become configured once you assign an entry.
To construct an empty dictionary with pre-configured key and value types, you can use configureDictionary (R2023b or later):
>> d_empty = configureDictionary("string", "double")
d_empty =
dictionary (string ⟼ double) with no entries.
Lookup
Single key:
>> d("a")
ans =
1
Simultaneously look-up an array of keys:
>> k = [ "a" "b"
"b" "c" ];
>> d(k)
ans =
1 2
2 3
Error on invalid key lookup:
>> d("bad key")
Error using ()
Key not found.
>> d(123)
Error using ()
Key not found.
MATLAB R2023b introduced the lookup function, which allows you to specify a fallback value:
>> d.lookup("a", FallbackValue=nan)
ans =
1
>> d.lookup("missing", FallbackValue=nan)
ans =
NaN
Assignment
>> d("new") = 10
d =
dictionary (string ⟼ double) with 4 entries:
"a" ⟼ 1
"b" ⟼ 2
"c" ⟼ 3
"new" ⟼ 10
Values are automatically marshaled into the value type if a conversion is possible. If no conversion is possible, and error is emitted:
d("new") = "123" % Note: string instead of double
d =
dictionary (string ⟼ double) with 4 entries:
"a" ⟼ 1
"b" ⟼ 2
"c" ⟼ 3
"new" ⟼ 123
>> d("new") = @sum
Error using ()
Unable to use 'function_handle' as value for dictionary with 'double' value type.
Caused by:
Conversion to double from function_handle is not possible
Deletion
Keys can be deleted by assigning an empty array []:
>> d("a") = []
d =
dictionary (string ⟼ double) with 2 entries:
"b" ⟼ 2
"c" ⟼ 3
Arrays of keys can also be used on the left-hand side, just as seen under Assignment above.
MATLAB 2023b introduced the remove function, which behaves identically to assigning []:
>> d.remove("a")
ans =
dictionary (string ⟼ double) with 2 entries:
"b" ⟼ 2
"c" ⟼ 3
Size
Number of entries:
>> d.numEntries
ans =
3
Extracting key/value collections
Key and value arrays:
>> d.keys
ans =
3×1 string array
"a"
"b"
"c"
>> d.values
ans =
1
2
3
Entries table:
>> d.entries
ans =
3×2 table
Key Value
___ _____
"a" 1
"b" 2
"c" 3
Querying types configuration
Query the key and value types:
>> [kt, vt] = d.types
kt =
"string"
vt =
"double"
Checking whether the dictionary has configured key and value types:
>> d.isConfigured
ans =
logical
1
Dictionaries constructed without any initial entries start unconfigured:
>> d2 = dictionary
d2 =
dictionary with unset key and value types.
>> d2.isConfigured
ans =
logical
0
>> [kt, vt] = d2.types
kt =
<missing>
vt =
<missing>
Unconfigured dictionaries become configured as soon as an entry is assigned:
>> d2("key") = "value"
d2 =
dictionary (string ⟼ string) with 1 entry:
"key" ⟼ "value"
>> d2.isConfigured
ans =
logical
1
