Main Content

Map Data with Dictionaries

Since R2022b. Recommended over containers.Map.
Open Live Script

A dictionary is a data structure that creates associations between data of different types. Dictionaries store data as values, that are accessed using corresponding unique keys. Keys and values can be different data types, and each key and value pair is an entry.

The basic function of a dictionary is to link two associated sets of data so that an element of one set can be used to find the corresponding element of the other. This action is called a lookup. Dictionaries offer consistent performance regardless of how many entries the dictionary has.

This example shows how to create a dictionary and modify its entries. It then shows how dictionaries handle data types and how to store different data types.

Create Dictionary

For example, create a dictionary using products as keys and prices as values. The dictionary output indicates the data type of the keys and values.

Products = ["Tomato" "Carrot" "Mango" "Mushroom"];
Prices = [1 .5 2.50 1.99];
d = dictionary(Products,Prices)
d =

  dictionary (string --> double) with 4 entries:

    "Tomato"   --> 1
    "Carrot"   --> 0.5000
    "Mango"    --> 2.5000
    "Mushroom" --> 1.9900

Now, perform a lookup to find the price of carrots. Any price in the dictionary can be found using the associated key.

d("Carrot")
ans = 
0.5000

Modify Dictionary

To insert new entries into a dictionary, you can map a value to a new key using an equal sign (=). This command adds the key "Potato" with a price of 0.75 as the value.

d("Potato") = 0.75
d =

  dictionary (string --> double) with 5 entries:

    "Tomato"   --> 1
    "Carrot"   --> 0.5000
    "Mango"    --> 2.5000
    "Mushroom" --> 1.9900
    "Potato"   --> 0.7500

You can change an entry by mapping a new value to an existing key. This command changes the price of "Tomato" to 1.25.

d("Tomato") = 1.25
d =

  dictionary (string --> double) with 5 entries:

    "Tomato"   --> 1.2500
    "Carrot"   --> 0.5000
    "Mango"    --> 2.5000
    "Mushroom" --> 1.9900
    "Potato"   --> 0.7500

Remove entries by mapping the key to an empty array ([]). This command removes the entry for "Mango".

d("Mango") = []
d =

  dictionary (string --> double) with 4 entries:

    "Tomato"   --> 1.2500
    "Carrot"   --> 0.5000
    "Mushroom" --> 1.9900
    "Potato"   --> 0.7500

Any of the prior actions can be vectorized, rather than operating on one entry at a time. For example, this command adds two new entries for "Celery" and "Grapes" with associated prices.

d(["Celery" "Grapes"]) = [0.50 1.95]
d =

  dictionary (string --> double) with 6 entries:

    "Tomato"   --> 1.2500
    "Carrot"   --> 0.5000
    "Mushroom" --> 1.9900
    "Potato"   --> 0.7500
    "Celery"   --> 0.5000
    "Grapes"   --> 1.9500

Dictionaries and Data Types

Dictionary keys and values can be of almost any data type and a dictionary is typed based on its entries. Once data types are assigned, the dictionary is configured.

Keys and values do not need to be of the same data type. However, all keys and all values in a dictionary must share respective data types or be able to be converted to the configured data type.

If a new entry is inserted that does not match the configured data types for the dictionary, then MATLAB® attempts to convert the data types to match the configuration.

For example, create a dictionary that accepts keys and values that are strings. Then add an entry that contains a numeric value. MATLAB converts the value to a string.

d = dictionary("hello","world")
d =

  dictionary (string --> string) with 1 entry:

    "hello" --> "world"

d("newKey") = 1
d =

  dictionary (string --> string) with 2 entries:

    "hello"  --> "world"
    "newKey" --> "1"

isstring(d("newKey"))
ans = logical
   1

Store Different Data Types in Dictionary

Dictionaries require that all entries share the same respective data types for keys and values. However, you can store multiple data types in a dictionary by putting the data in a cell array. Each element of a cell array can contain data of any type or size. This approach satisfies the dictionary type requirement because all of the values are cell arrays.

Create a cell array containing values of various data types, and then create a string array of keys.

myCell = {datetime,@myfun,struct,[1 2 3 4]}
myCell=1×4 cell array
    {[05-Sep-2024 15:48:13]}    {@myfun}    {1x1 struct}    {[1 2 3 4]}


names = ["my birthday" "my favorite function" "a structure" "numeric array"]
names = 1x4 string
    "my birthday"    "my favorite function"    "a structure"    "numeric array"

Create a dictionary using the specified keys and values.

d = dictionary(names,myCell)
d =

  dictionary (string --> cell) with 4 entries:

    "my birthday"          --> {[05-Sep-2024 15:48:13]}
    "my favorite function" --> {@myfun}
    "a structure"          --> {1x1 struct}
    "numeric array"        --> {[1 2 3 4]}

In R2023a, lookup the contents of cells stored as values directly using curly braces ({}).

d{"numeric array"}
ans = 1×4

     1     2     3     4

Similarly, new entries of any datatype can be inserted into an existing dictionary with cell values using curly braces ({}).

d{"a new entry"} = table
d =

  dictionary (string --> cell) with 5 entries:

    "my birthday"          --> {[05-Sep-2024 15:48:13]}
    "my favorite function" --> {@myfun}
    "a structure"          --> {1x1 struct}
    "numeric array"        --> {[1 2 3 4]}
    "a new entry"          --> {0x0 table}

Data Type Limitations

Dictionaries allow entries of almost any data type, but there are some limitations. Certain data types like struct are accepted as part of an entry, but vectorized operations are not supported for structures with different fields. Vectorized lookup is not supported for types that are not able to be concatenated.

Dictionaries do not accept these data types as keys or values:

  • Tables

  • Tall arrays

  • Distributed arrays

  • graph and digraph objects

Unconfigured Dictionaries

When you create a dictionary without any entries, it is an unconfigured dictionary, and it has no data type assigned to the keys and values. 

d = dictionary
d =

  dictionary with unset key and value types.

isConfigured(d)
ans = logical
   0

Use the configureDictionary to create a configured dictionary with no entries.

d = configureDictionary("string","double")
d =

  dictionary (string --> double) with no entries.

Before R2023b A dictionary can be configured without adding any entries by creating empty inputs of the intended data types. For example, dictionary(string.empty,struct.empty).

See Also

| |

Related Topics