Main Content

dictionary

Object that maps unique keys to values

Since R2022b. Recommended over containers.Map.

Description

Use a dictionary to efficiently lookup values associated with a key. A dictionary is a map that stores data as values, which can be accessed using corresponding unique keys. Each pair of keys and values is an entry.

Creation

Description

d = dictionary(keys,values) creates a dictionary with specified keys and values. The resulting dictionary d is a 1-by-1 scalar object. If multiple values are assigned to the same key, then only the last of those values is assigned. New assignments to an existing key overwrite the value for that entry.

keys and values can be of any type but must be the same size unless values is a scalar, where each element of keys becomes a key for values. When keys and values are arrays, the number of entries is equal to the number of key-value pairs.

Dictionary enforces that key and value types are uniform. 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 parts of a new entry do not share the configured data types then MATLAB® attempts a conversion. Keys and values do not need to be of the same data type. Character row vectors are converted to string scalars when assigned as keys or values.

To store a mixture of key or value types, use a cell array. When performing a lookup on a dictionary that uses cells as values, a cell array is returned. The contents of the cell array can be accessed directly by using curly braces ({}) instead of parentheses. (since R2023a)

example

d = dictionary(k1,v1,...,kN,vN) creates a dictionary with specified key-value pairs. If multiple instances of the same key are specified then only the last key-value pair is assigned.

d = dictionary creates an unconfigured dictionary with no keys or values.

When a dictionary is created without inputs, it is unconfigured and has no types. Adding entries to an unconfigured dictionary specifies a data type for the keys and a data type for the values.

example

Input Arguments

expand all

Keys, specified as a scalar or an array. Individual elements of keys must be scalars of the same data type or of compatible data types.

If keys is an array, each element creates a new key. If keys contains duplicate elements, the corresponding value of the last duplicate element is assigned.

Values, specified as a scalar, array, or cell array. Individual elements of values must be scalars of the same data type. If values need to be heterogeneous or nonscalar, use a cell array.

If values is an array, each element creates a new value. If keys is an array and values is a scalar, then that value is mapped to each key in keys.

Key-value pairs, specified as separate arguments of key and value scalars and arrays. All key arguments must have the same data type or have compatible data types. All value arguments must have the same data type or have compatible data types.

Output Arguments

expand all

Dictionary, returned as a dictionary object. Entries are stored in the order that they were added.

Usage

Description

Use dictionary to create the dictionary, d. Then you can evaluate or change d at specific query points using any of the following syntaxes:

valueOut = d(keys) looks up the value that corresponds to keys.

d(keys) = newValues assigns the elements of newValues to the entries specified by the corresponding values of keys. If a specified key does not exist in the dictionary, then a new entry is added. If multiple values are assigned to the same key, then only the last of those values is assigned. New assignments to an existing key overwrite the value for that entry.

d(keys) = [] removes the entry associated with keys from the dictionary.

valueOut = d{keys} looks up the value associated with keys and returns the contents of the cell. If keys is an array, a comma separated list of the corresponding values is returned. If the dictionary's values are configured to be a datatype other than cell, an error is thrown.

d{keys} = newValues assigns cells containing the elements of newValues to the entries specified by the corresponding values of keys. If the dictionary's values are configured to be a datatype other than cell an error is thrown.

Object Functions

configureDictionaryCreate dictionary with specified key and value types
insertAdd entries to a dictionary
lookupFind value in dictionary by key
removeRemove dictionary entries
entriesKey-value pairs of dictionary
keysKeys of dictionary
valuesValues of dictionary
typesTypes of dictionary keys and values
numEntriesNumber of key-value pairs in dictionary
isConfiguredDetermine if dictionary has types assigned to keys and values
isKeyDetermine if dictionary contains key

Examples

collapse all

Create a dictionary to store the number of wheels of different vehicles.

Create an array of names and an array of corresponding number of wheels.

wheels = [1 2 3];
names = ["Monocycle" "Bicycle" "Tricycle"];

Create a dictionary using the names as keys and the number of wheels as values.

d = dictionary(names,wheels)
d =

  dictionary (string ⟼ double) with 3 entries:

    "Monocycle" ⟼ 1
    "Bicycle"   ⟼ 2
    "Tricycle"  ⟼ 3

Access dictionary values by using the key as an index.

d("Tricycle")
ans = 
3

Entries can be modified by assigning a new value to an existing key.

d("Bicycle") = 2.5
d =

  dictionary (string ⟼ double) with 3 entries:

    "Monocycle" ⟼ 1
    "Bicycle"   ⟼ 2.5000
    "Tricycle"  ⟼ 3

Add new entries to a dictionary by assigning values to keys.

d("Car") = 4
d =

  dictionary (string ⟼ double) with 4 entries:

    "Monocycle" ⟼ 1
    "Bicycle"   ⟼ 2.5000
    "Tricycle"  ⟼ 3
    "Car"       ⟼ 4

Add multiple entries using arrays of keys and values.

names2 = ["Truck" "Motorcycle" "Sixteen-Wheeler"];
wheels2 = [4 2 16];
d(names2) = wheels2
d =

  dictionary (string ⟼ double) with 7 entries:

    "Monocycle"       ⟼ 1
    "Bicycle"         ⟼ 2.5000
    "Tricycle"        ⟼ 3
    "Car"             ⟼ 4
    "Truck"           ⟼ 4
    "Motorcycle"      ⟼ 2
    "Sixteen-Wheeler" ⟼ 16

Remove entries by assigning an empty array to an existing key.

d("Truck") = []
d =

  dictionary (string ⟼ double) with 6 entries:

    "Monocycle"       ⟼ 1
    "Bicycle"         ⟼ 2.5000
    "Tricycle"        ⟼ 3
    "Car"             ⟼ 4
    "Motorcycle"      ⟼ 2
    "Sixteen-Wheeler" ⟼ 16

New entries are automatically converted to match the configured data types of the dictionary. If a conversion is not possible, MATLAB throws an error.

d('Spider-Car') = "8"
d =

  dictionary (string ⟼ double) with 7 entries:

    "Monocycle"       ⟼ 1
    "Bicycle"         ⟼ 2.5000
    "Tricycle"        ⟼ 3
    "Car"             ⟼ 4
    "Motorcycle"      ⟼ 2
    "Sixteen-Wheeler" ⟼ 16
    "Spider-Car"      ⟼ 8

Dictionary values must have the same type. However, data of different types can be stored in a dictionary as a cell.

Create a cell array containing various data types and a string array of keys.

myValues = {datetime,@myfun,struct,[1 2 3 4]}
myValues=1×4 cell array
    {[01-Feb-2025 08:19:32]}    {@myfun}    {1×1 struct}    {[1 2 3 4]}

myKeys = ["my birthday" "my favorite function" "a structure" "numeric array"]
myKeys = 1×4 string
    "my birthday"    "my favorite function"    "a structure"    "numeric array"

Create a dictionary using the specified keys and values.

d = dictionary(myKeys,myValues)
d =

  dictionary (string ⟼ cell) with 4 entries:

    "my birthday"          ⟼ {[01-Feb-2025 08:19:32]}
    "my favorite function" ⟼ {@myfun}
    "a structure"          ⟼ {1×1 struct}
    "numeric array"        ⟼ {[1 2 3 4]}

Extract values as a cell array using the values function.

values(d)
ans=4×1 cell array
    {[01-Feb-2025 08:19:32]}
    {                @myfun}
    {1×1 struct            }
    {[             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"          ⟼ {[01-Feb-2025 08:19:32]}
    "my favorite function" ⟼ {@myfun}
    "a structure"          ⟼ {1×1 struct}
    "numeric array"        ⟼ {[1 2 3 4]}
    "a new entry"          ⟼ {0×0 table}

Calling dictionary without any inputs creates an unconfigured dictionary.

Create an empty configured dictionary using configureDictionary.

Before R2023b: Assign empty inputs of the desired types. For example, d = dictionary(string([]),[]).

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

  dictionary (string ⟼ double) with no entries.

This dictionary is configured and new entries can be added as long as the data types match or can be converted to the data types of the configured dictionary.

d("Unicycle") = 1;
d("Bicycle") = 2;
d("Tricycle") = 3
d =

  dictionary (string ⟼ double) with 3 entries:

    "Unicycle" ⟼ 1
    "Bicycle"  ⟼ 2
    "Tricycle" ⟼ 3

Create an unconfigured dictionary by calling dictionary without inputs.

d = dictionary
d =

  dictionary with unset key and value types.

When you add entries to an unconfigured dictionary, MATLAB changes it to be configured.

names = ["Unicycle" "Bicycle" "Tricycle"];
wheels = [1 2 3];
d(wheels) = names
d =

  dictionary (double ⟼ string) with 3 entries:

    1 ⟼ "Unicycle"
    2 ⟼ "Bicycle"
    3 ⟼ "Tricycle"

Tips

  • Custom classes can be used as both keys and values. Classes with overloaded indexing and size queries and those that differ from standard array behavior may not behave as expected. For additional information, see Dictionaries and Custom Classes.

Extended Capabilities

expand all

Version History

Introduced in R2022b

expand all