コード生成におけるディクショナリの制限事項

R2024b 以降

コード生成用の MATLAB^® コードで dictionary を使用するときは、string、cell、または構造体を使用する場合などの特定の状況で、考慮事項と制限事項が適用されます。dictionary は、データを値として格納するデータ構造体で、この値には対応するキーを使用してアクセスできます。このタイプのデータ構造体は、"ハッシュマップ" とも呼ばれます。MATLAB のディクショナリの詳細については、ディクショナリを使用したデータマッピングを参照してください。ディクショナリのコード生成の詳細については、ディクショナリのコードの生成を参照してください。

ディクショナリでの string の使用

string の配列を dictionary 関数に渡してディクショナリを作成することはできません。たとえば、次の関数のコード生成は失敗します。入力引数 Products が string の配列であるためです。

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

キーまたは値が string のディクショナリを作成するには、dictionary 関数でキーと値のペアを指定します。以下に例を示します。

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

あるいは、既存のディクショナリに string のキーまたは値を個別に追加します。以下に例を示します。

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

ディクショナリでの cell の使用

MATLAB ディクショナリでは、すべてのキーと値をスカラーにする必要があります。また、すべてキーまたは値が同じデータ型でなければなりません。ただし、データを cell 配列に入れることで、複数のデータ型を 1 つのディクショナリに保存できます。cell 配列の各要素には任意の型とサイズのデータを含めることができ、ディクショナリの作成後に、さまざまな型とサイズのデータを含む cell 配列をディクショナリに追加できます。一方、コードジェネレーターでは cell 配列内のデータの型が固定され、ディクショナリの作成時に cell 配列内のデータのサイズが変化するかどうかが判別されます。

cell 配列には同じパターンのデータ型が必要

cell 配列をキーまたは値として使用する場合、cell 配列内のデータは、すべてのエントリで同じパターンのデータ型に従う必要があります。たとえば、次の関数のコード生成は失敗します。キー "MyAlphaNum1" に対応する cell 配列の値では文字ベクトルの後に数値配列が続いていますが、キー "MyAlphaNum2" に対応する cell 配列では数値配列の後に文字ベクトルが続いているためです。

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

cell 配列をキーまたは値として使用するディクショナリのコードを生成するには、すべての cell 配列のキーまたは値に同じパターンのデータ型が含まれていることを確認します。たとえば、次の関数のコード生成は成功します。すべての cell 配列の値で文字ベクトルの後に数値配列が続いているためです。

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

cell 配列は固定サイズまたは可変サイズのいずれか

コードジェネレーターは、ディクショナリの作成時に cell 配列の内容が固定サイズか可変サイズかを判別する必要があります。cell 配列をキーまたは値として使用する単一のエントリを含むディクショナリを作成する場合、cell 配列内の要素のサイズは固定であり、サイズの異なる要素をもつ cell 配列を後で追加することはできません。cell 配列のキーまたは値内のデータのサイズを変更するには、ディクショナリの作成時にこれらのデータのサイズが可変になるように指定する必要があります。たとえば、次の関数のコード生成は失敗します。コードジェネレーターでは、追加された各ディクショナリ値が 1 行 3 列の数値ベクトルを含む cell 配列であると想定されているためです。

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

同様に、同じサイズのデータを含む cell 配列を使用してディクショナリを作成する場合、cell 配列内の要素のサイズは固定であり、サイズの異なる要素を後で追加することはできません。たとえば、次の関数のコード生成は失敗します。コードジェネレーターでは、追加された各ディクショナリ値が 1 行 3 列の数値ベクトルを含む cell 配列であると想定されているためです。

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

cell 配列内のデータのサイズ変更を許可するようにコードジェネレーターに指示するには、ディクショナリの作成に使用する cell 配列にサイズの異なるデータを含めます。以下に例を示します。

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

あるいは、coder.varsize を使用すると、cell 配列内のデータのサイズ変更を許可するようにコードジェネレーターに明示的に指示できます。

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

中かっこ `{}` を使用してディクショナリにインデックスを付けない

MATLAB では、中かっこ {} を使用して、ディクショナリの値として保存された cell の内容をルックアップしたり、cell 値をもつディクショナリに新しいエントリを挿入したりできます。コード生成では、中かっこを使用したディクショナリの値へのアクセスまたはその挿入はサポートされていません。たとえば、次の関数のコード生成は失敗します。

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

cell 配列の値にアクセスしたりその値を挿入したりするには、小かっこ () を使用します。以下に例を示します。

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

ディクショナリでの構造体の使用

キーまたは値として使用される構造体には同じフィールドが必要

コード生成では、キーと値として構造体がサポートされます。ただし、キーまたは値の構造体には、すべてのディクショナリエントリで同じデータ型の同じフィールドが含まれている必要があります。たとえば、次の関数 structDictError のコード生成は 2 つの理由で失敗します。1 つ目は、キー "Lakeside" の構造体の値に Location フィールドがないことです。2 つ目は、フィールド "Phone" のデータ型が最初のエントリでは uint32、2 番目のエントリでは double であることです。

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

キーまたは値として使用する構造体のコードを生成するには、すべての構造体のキーまたは値に、すべてのエントリで同じデータ型の同じフィールドが含まれていることを確認します。たとえば、次の関数 structDictExample のコード生成は成功します。すべての構造体の値に、同じデータ型の同じフィールドが含まれているためです。

function out = structDictExample
d = dictionary("Apple Hill",struct("City","Natick","Phone",uint32(6477000)));
d("Lakeside") = struct("City","Natick","Phone",uint32(0));
out = d;
end

構造体フィールドは固定サイズまたは可変サイズのいずれか

コードジェネレーターは、ディクショナリの作成時に構造体フィールドの内容が固定サイズか可変サイズかを判別する必要があります。構造体をキーまたは値として使用する単一のエントリを含むディクショナリを作成する場合、構造体のフィールドのサイズは固定であり、サイズの異なるフィールドをもつ構造体を後で追加することはできません。ディクショナリで可変サイズのフィールドをもつ構造体を使用するには、ディクショナリの作成時にフィールドのサイズが可変になるように指定する必要があります。たとえば、次の関数のコード生成は失敗します。コードジェネレーターでは、追加された各値が 1 行 18 列の string であるフィールド Address をもつ構造体であると想定されているためです。

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

構造体フィールドのサイズ変更を許可するようにコードジェネレーターに指示するには、ディクショナリ作成コマンドにサイズの異なるフィールドを含めます。以下に例を示します。

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

その他の制約と制限

コード生成のために MATLAB コード内でディクショナリを使用するときは、次の追加の制限に従います。

ユーザー作成クラスや fi (Fixed-Point Designer) オブジェクトなどのオブジェクトをキーとして使用しないでください。
キーまたは値として関数ハンドルや categorical データを使用しないでください。
動的メモリ割り当てを無効にしないでください。
configureDictionary を使用してディクショナリを作成する場合、ディクショナリにはキーや値として複素数を含めることはできません。複素数を含めることができるディクショナリを構成するには、dictionary 関数を使用します。
実数のキーと値を dictionary 関数で使用するか、configureDictionary 関数を使用して実数の数値型のディクショナリを構成する場合、ディクショナリには実数の数値型のみを含めることができます。コード生成では、このようなディクショナリに対する複素数のキーや値の追加はサポートされていません。
コードジェネレーターは、コード生成時にディクショナリが定数であっても、ディクショナリを定数として扱いません。ディクショナリを coder.Constant または coder.const に渡すことはできません。また、lookup、entries、keys、および values を含むすべてのディクショナリアクセス関数は非定数値を返します。これは、定数入力を必要とする関数にディクショナリ、ディクショナリのキー、またはディクショナリの値を渡すことができないことを意味します。ディクショナリ、ディクショナリのキー、またはディクショナリの値は、異種混合 cell 配列へのインデックス付けなど、定数を必要とする操作には使用できません。また、コードジェネレーターは、定数畳み込みなど、定数値に依存する最適化をディクショナリに対して実行することもできません。
未構成のディクショナリをエントリポイント関数の入力として使用しないでください。
未構成のディクショナリを coder.typeof 関数に渡さないでください。
configureDictionary を使用して、キーまたは値が cell、構造体、またはユーザー定義クラスであるディクショナリを作成しないでください。

参考

codegen