Dictionary Limitations for Code Generation

Since R2024b

When you use a dictionary in MATLAB® code for code generation, considerations and limitations apply in certain situations, such as when you use strings, cells, or structures. A dictionary is a data structure that stores data as values that you can access using the corresponding keys. This type of data structure is also known as a hash map. For more information about dictionaries in MATLAB, see Map Data with Dictionaries. To learn about code generation for dictionaries, see Generate Code for Dictionaries.

Using Strings in Dictionaries

You cannot create a dictionary by passing arrays of strings to the dictionary function. For example, code generation fails for this function because the input argument Products is an array of strings.

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

To create a dictionary with keys or values that are strings, specify the key-value pairs in the dictionary function. For example:

function out = stringDictExample1
out = dictionary("Tomato",1,"Carrot",.5,"Mango",2.5,"Mushroom",1.99);
end

Alternatively, individually add string keys or values to an existing dictionary. For example:

function out = stringDictExample2
d = configureDictionary("string","double");
d("Tomato") = 1;
d("Carrot") = .5;
d("Mango") = 2.5;
d("Mushroom") = 1.99;
out = d;
end

Using Cells in Dictionaries

MATLAB dictionaries require that all keys and values are scalar. In addition, all keys or values must have the same data type. 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, and you can add cell arrays containing data of different types and sizes to the dictionary after dictionary creation. In contrast, the code generator fixes the types of the data in the cell array and determines whether the data in the cell array varies in size at the time of dictionary creation.

Cell Arrays Must Contain the Same Pattern of Data Types

If you use a cell array as a key or value, the data in the cell array must follow the same patten of data types across all entries. For example, code generation fails for this function because the cell array value corresponding to the key "MyAlphaNum1" contains a character vector followed by a numeric array, but the cell array corresponding to key "MyAlphaNum2" contains numeric array followed by a character vector.

function out = cellDictError
d = dictionary("MyAlphaNum1",{{'abcd',[1 2 3 4]}});
d("MyAlphaNum2") = {{[5 6 7 8],'efgh'}};
out = d;
end
To generate code for dictionaries that use cell arrays as keys or values, ensure that all cell array keys or values contain the same pattern of data types. For example, code generation succeeds for this function because all cell array values contain a character vector followed by a numeric array.
function out = cellDictExample
d = dictionary("MyAlphaNum1",{{'abcd',[1 2 3 4]}});
d("MyAlphaNum2") = {{'efgh', [5 6 7 8]}};
out = d;
end

Cell Arrays are Either Fixed-Size or Variable-Size

The code generator must determine whether the contents of a cell array are fixed-size or variable-size when the dictionary is created. If you create a dictionary with a single entry using a cell array as a key or value, the sizes of the elements in the cell array are fixed and you cannot later add a cell array with an element of a different size. To change the sizes of data inside a cell array key or value, you must specify that these data can vary in size when you create the dictionary. For example, code generation fails for this function because the code generator expects each added dictionary value to be a cell array containing a 1-by-3 numeric vector.

function out = cellDictVarSizeError1
d = dictionary(1,{[1 2 3]});
d(2) = {[2]};
d(3) = {[5 6 7 8 9]};
out = d;
end

Similarly, if you create a dictionary using cell arrays that contain data of the same size, the sizes of the elements in the cell array are fixed and you cannot later add elements of a different size. For example, code generation fails for this function because the code generator expects each added dictionary value to be a cell array containing a 1-by-3 numeric vector.

function out = cellDictVarSizeError2
d = dictionary(1,{[1 2 3]},4,{[10 11 12]});
d(2) = {[2]};
d(3) = {[5 6 7 8 9]};
out = d;
end

To instruct the code generator to allow the size of the data in the cell array to vary, include data of different sizes in the cell arrays you use to create the dictionary. For example:

function out = cellDictVarSizeExample1
d = dictionary(1,{[1 2 3]},2,{[4]});
d(3) = {[5 6 7 8 9]};
out = d;
end

Alternatively, you can use coder.varsize to explicitly instruct the code generator to allow the data in the cell array to vary in size.

function out = cellDictVarSizeExample2
value = 1:3;
coder.varsize("value",[1 inf])
d = dictionary(1,{value});
d(2) = {[4]};
d(3) = {[5 6 7 8 9]};
out = d;
end

Do Not Index into a Dictionary Using Curly Braces {}

In MATLAB, you can use curly braces {} to look up the contents of cells stored as dictionary values and to insert new entries into a dictionary that has cell values. Code generation does not support using curly braces to access or insert dictionary values. For example, code generation fails for this function.

function out = dictBraceError
d = dictionary("MyAlphaNum1",{{'abcd',[1 2 3 4]}});
d{"MyAlphaNum2"} = {'efgh',[5 6 7 8]};
out = d{"MyAlphaNum2"};
end

To access or insert cell array values, use parentheses (). For example:

function out = dictBraceExample
d = dictionary("MyAlphaNum1",{{'abcd',[1 2 3 4]}});
d("MyAlphaNum2") = {{'efgh',[5 6 7 8]}};
val = d("MyAlphaNum2");
out = val{1};
end

Using Structures in Dictionaries

Structures Used as Keys or Values Must Have the Same Fields

Code generation supports structures as keys and values. However, key or value structures must contain the same fields with the same data types across all dictionary entries. For example, code generation fails for the function structDictError for two reasons: First, the structure value for key "Lakeside" lacks the Location field. Second, the data type of field "Phone" is uint32 in the first entry and double in the second.

function out = structDictError
d = dictionary("Apple Hill",struct("Location","Headquarters", ...
    "City","Natick","Phone",uint32(6477000)));
d("Lakeside") = struct("City","Natick","Phone",0);
out = d;
end
To generate code for structures as keys or values, make sure that all structure keys or values contain the same fields with the same data types across all entries. For example, code generation succeeds for the function structDictExample because all structure values contain the same fields with the same data types.
function out = structDictExample
d = dictionary("Apple Hill",struct("City","Natick","Phone",uint32(6477000)));
d("Lakeside") = struct("City","Natick","Phone",uint32(0));
out = d;
end

Structure Fields Are Either Fixed-Size or Variable-Size

The code generator must determine whether the contents of a structure field are fixed-size or variable-size when the dictionary is created. If you create a dictionary with a single entry using a structure as a key or value, the sizes of the fields of the structure are fixed and you cannot later add a structure with fields of different sizes. To use a structure with variable-size fields in a dictionary, you must specify that fields can vary in size when you create the dictionary. For example, code generation fails for this function because the code generator expects each added value to be a structure with a field Address that is a 1-by-18 string.

function out = structDictVarSizeError
d = dictionary("Apple Hill",struct("Address","1 Apple Hill Drive"));
d("Lakeside") = struct("Address","1 Lakeside Campus Drive");
d("Novi") = struct("Address","28125 Cabot Drive");
out = d;
end

To instruct the code generator to allow structure fields to vary in size, include fields of different sizes in the dictionary creation command. For example:

function out = structDictVarSizeExample
d = dictionary("Apple Hill",struct("Address","1 Apple Hill Drive"), ...
    "Lakeside",struct("Address","1 Lakeside Campus Drive"));
d("Novi") = struct("Address","28125 Cabot Drive");
out = d;
end

Other Restrictions and Limitations

When using dictionaries in MATLAB code for code generation, adhere to these additional restrictions:

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

  • Do not use function handles or categorical data as keys or values.

  • Do not disable dynamic memory allocation.

  • If you create a dictionary using configureDictionary, the dictionary cannot contain complex numbers as keys or values. To configure a dictionary that can contain complex numbers, use the dictionary function.

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

  • The code generator does not treat a dictionary as a constant, even if the dictionary is constant at code generation time. You cannot pass a dictionary to coder.Constant or coder.const. In addition, all dictionary access functions, including lookup, entries, keys, and values return non-constant values. 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.

  • Do not use unconfigured dictionaries as inputs to entry-point functions.

  • Do not pass unconfigured dictionaries to the coder.typeof function.

  • Do not use configureDictionary to create dictionaries with keys or values that are cells, structures, or user-defined classes.

See Also

Topics