dictionary

Dictionary that maps unique keys to values

Since R2022b. Recommended over containers.Map.

Description

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. Use a dictionary to efficiently look up values associated with a key.

Creation

Syntax

d = dictionary(keys,values)

d = dictionary(k1,v1,...,kN,vN)

d = dictionary

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 you assign multiple values 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 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.

keys and values can be of any type, but key types and value types must be uniform. All keys and all values in a dictionary must share respective data types or be convertible to the configured data type. If parts of a new entry do not share the configured data types, then MATLAB^® attempts to convert the entry types. Keys and values do not need to be of the same data type. dictionary converts keys and values specified as character row vectors to string scalars.

To store a mix of key or value types, use a cell array. When you perform a lookup on a dictionary that uses cells as values, the dictionary returns a cell array. You can access the contents of the cell array directly by using curly braces {} instead of parentheses. (since R2023a)

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

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

When you create a dictionary 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.

Input Arguments

keys — Keys

scalar | array | cell array

Keys, specified as a scalar, an array, or a cell 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 — Values

scalar | array | cell array

Values, specified as a scalar, an array, or a 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.

k1,v1,...,kN,vN — Key-value pairs (as separate arguments)

scalar | array

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

d — dictionary

dictionary object

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

Usage

Use dictionary to create the dictionary d. Then you can access or change d using any of the following syntaxes.

Syntax

valueOut = d(keys)

d(keys) = newValues

d(keys) = []

valueOut = d{keys}

d{keys} = newValues

Description

valueOut = d(keys) looks up the value associated with 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 you assign multiple values 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 values are configured to be a data type other than cell, this syntax throws an error.

d{keys} = newValues assigns cells containing the elements of newValues to the entries specified by the corresponding values of keys. If the dictionary values are configured to be a data type other than cell, this syntax throws an error.

Object Functions

configureDictionary	Create dictionary with specified key and value types
insert	Add entries to a dictionary
lookup	Find value in dictionary by key
remove	Remove dictionary entries
entries	Key-value pairs of dictionary
keys	Keys of dictionary
values	Values of dictionary
types	Types of dictionary keys and values
numEntries	Number of key-value pairs in dictionary
isConfigured	Determine if dictionary has types assigned to keys and values
isKey	Determine if dictionary contains key

Examples

Create and Manage Dictionary

Create a dictionary that maps different vehicle names to the number of wheels.

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

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

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:

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

Access dictionary values by using the key as an index.

d("Tricycle")

ans = 
3

Modify a dictionary entry by assigning a new value to an existing key.

d("Bicycle") = 2.5

d =

  dictionary (string ⟼ double) with 3 entries:

    "Unicycle" ⟼ 1
    "Bicycle"  ⟼ 2.5000
    "Tricycle" ⟼ 3

Add a new entry to the dictionary by assigning a value to a new key.

d("Car") = 4

d =

  dictionary (string ⟼ double) with 4 entries:

    "Unicycle" ⟼ 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:

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

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

d("Truck") = []

d =

  dictionary (string ⟼ double) with 6 entries:

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

The dictionary automatically converts new entries to match the configured data types. If a conversion is not possible, MATLAB throws an error.

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

d =

  dictionary (string ⟼ double) with 7 entries:

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

Store Multiple Data Types in Dictionary

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 that contains values of various data types and a string array of keys.

myValues = {datetime,@myfun,struct,[1 2 3 4]}

myValues=1×4 cell array
    {[24-Jan-2026 19:18:05]}    {@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"          ⟼ {[24-Jan-2026 19:18:05]}
    "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
    {[24-Jan-2026 19:18:05]}
    {                @myfun}
    {1×1 struct            }
    {[             1 2 3 4]}

Look up the contents of cells stored as values directly using curly braces {}. (since R2023a)

d{"numeric array"}

ans = 1×4

     1     2     3     4

Similarly, you can add new entries of any data type into an existing dictionary with cell values using curly braces {}.

d{"a new entry"} = table

d =

  dictionary (string ⟼ cell) with 5 entries:

    "my birthday"          ⟼ {[24-Jan-2026 19:18:05]}
    "my favorite function" ⟼ {@myfun}
    "a structure"          ⟼ {1×1 struct}
    "numeric array"        ⟼ {[1 2 3 4]}
    "a new entry"          ⟼ {0×0 table}

Create Empty Configured Dictionary

Create an empty configured dictionary using configureDictionary.

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

d =

  dictionary (string ⟼ double) with no entries.

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

You can add new dictionary entries 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

Add Entries to Unconfigured Dictionary

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 configures the dictionary using the data types of the entries.

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

d =

  dictionary (string ⟼ double) with 3 entries:

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

Tips

• You can use custom classes for both keys and values. However, if you use classes with overloaded indexing or size queries or whose behavior differs from standard array behavior, the dictionary might not behave as expected. For additional information, see Dictionaries and Custom Classes.

• Entries are stored in the order that they are added and returned in the same order. For example, create a dictionary with three entries:

  d = dictionary("first",1,"second",2,"third",3)

  d =
  
    dictionary (string ⟼ double) with 3 entries:
  
      "first"  ⟼ 1
      "second" ⟼ 2
      "third"  ⟼ 3

  The keys or values from this dictionary are returned in the same order in which they were added.

  k = keys(d)

  k = 
  
    3×1 string array
  
      "first"
      "second"
      "third"

  If additional entries are added, they are added to the end of previous entries.

  d("fourth") = 4

  d =
  
    dictionary (string ⟼ double) with 4 entries:
  
      "first"  ⟼ 1
      "second" ⟼ 2
      "third"  ⟼ 3
      "fourth" ⟼ 4

  Updating the value of an entry does not change its place in the order of entries.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Do not use objects, such as user-written classes and fi (Fixed-Point Designer) objects, as keys.

• If you configure a dictionary of real numeric types by passing real keys and values to the dictionary function, the dictionary can only contain real numeric types. Code generation does not support adding complex keys or values to such a dictionary.

• You cannot define a dictionary as a constant.

• The code generator does not treat a dictionary as a constant, even if the dictionary is constant at code generation time. This means that you cannot pass a dictionary, a dictionary key, or a dictionary value to a function that requires constant inputs. You cannot use a dictionary, dictionary key, or dictionary value for operations that require constants, such as indexing into a heterogeneous cell array. The code generator also cannot perform optimizations that depend on constant values, such as constant folding, on dictionaries.

For additional considerations that apply when generating C/C++ code for MATLAB dictionaries, see Dictionary Limitations for Code Generation (MATLAB Coder).

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Refer to the usage notes and limitations in the C/C++ Code Generation section. The same usage notes and limitations apply to GPU code generation.

Version History

Introduced in R2022b

R2024b: Code generation support

You can generate C/C++ code for the dictionary function, with some limitations.

R2023b: configureDictionary Function: Create dictionaries with configured keys and values

Use configureDictionary to create an empty dictionary with specified types for keys and values.

For example, create a dictionary that is configured to accept strings as keys and doubles as values.

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

d =

  dictionary (string ⟼ double) with no entries.

R2023b: lookup, insert, and remove Functions: Manage dictionary entries

Use lookup, insert, and remove to perform basic dictionary operations.

R2023a: Look up and assign values in cells using curly braces {}

Data in cells can be looked up and assigned directly using curly braces, {}. When a dictionary's values are cells, a lookup using parentheses, (), will return a cell. Accessing the contents of that cell would require indexing into that cell. Introducing curly brace access allows contents of cell values to be accessed directly. For example, the dictionary, d, has three cell values

d = 

  dictionary (double ⟼ cell) with 3 entries:

    1 ⟼ {["Hello"]}
    2 ⟼ {[4 5 6]}
    3 ⟼ {@sin}

Perform a lookup using smooth parentheses, (). The value is returned as a cell containing an array.

d(1)

ans = 

    {[4 5 6]}

Perform a lookup using curly braces, {}. The value is returned as an array.

d{1}

ans = 

    [4 5 6]

R2023a: Use Python objects as keys in dictionary

You can use Python objects as keys in dictionaries.

R2022b: Recommended over containers.Map

dictionary is recommended over containers.Map because it supports more data types as keys and values and provides better performance.