dictionary

将唯一键映射到值的字典

建议替换

全页展开

说明

字典是将数据存储为值的映射，这些值可以使用对应的唯一键来访问。每对键和值构成一个条目。使用字典高效查找与键关联的值。

创建对象

语法

d = dictionary(keys,values)

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

d = dictionary

描述

d = dictionary(keys,values) 使用指定的键和值创建一个字典。生成的字典 d 是一个 1×1 标量对象。如果您将多个值赋给同一个键，则只赋这些值中的最后一个值。对现有键的新赋值会覆盖该条目的值。

keys 和 values 的大小必须相同，除非 values 是标量，其中 keys 的每个元素成为 values 的一个键。当键和值是数组时，条目的数量等于键-值对组的数量。

keys 和 values 可以是任何类型，但键类型和值类型必须一致。字典中的所有键和所有值必须分别具有相同的数据类型，或可转换为配置的数据类型。如果新条目的某些部分的数据类型不同于已配置的数据类型，则 MATLAB^® 会尝试转换条目类型。键和值不需要具有相同的数据类型。dictionary 将指定为字符行向量的键和值转换为字符串标量。

要存储混合使用的键或值类型，请使用元胞数组。当您对使用元胞作为值的字典执行查找时，字典返回元胞数组。您可以使用花括号 {}（而不是括号）直接访问元胞数组的内容。 (自 R2023a 起)

示例

d = dictionary(k1,v1,...,kN,vN) 使用指定的键-值对组创建一个字典。如果指定了同一个键的多个实例，则只对最后一个键-值对组赋值。

d = dictionary 创建一个没有键或值的未配置字典。

在创建没有输入的字典时，该字典是未配置的字典，并且没有类型。向未配置的字典中添加条目会为键和值分别指定数据类型。

示例

输入参量

全部展开

`keys` — 键
标量 | 数组 | 元胞数组

键，指定为标量、数组或元胞数组。keys 的各个元素必须为具有相同数据类型或兼容数据类型的标量。

如果 keys 为数组，则每个元素会创建一个新键。如果 keys 包含重复元素，则会赋最后一个重复元素的对应值。

`values` — 值
标量 | 数组 | 元胞数组

值，指定为标量、数组或元胞数组。values 的各个元素必须为具有相同数据类型的标量。如果值需要是异构或非标量类型，请使用元胞数组。

如果 values 为数组，则每个元素会创建一个新键。如果 keys 为数组，values 为标量，则该值映射到 keys 中的每个键。

`k1,v1,...,kN,vN` — 键-值对组（作为单独参量）
标量 | 数组

键-值对组，键和值参量分别指定，可以为标量和数组。所有键参量必须具有相同的数据类型或兼容的数据类型。所有值参量必须具有相同的数据类型或兼容的数据类型。

输出参量

全部展开

`d` — 字典
`dictionary` 对象

字典，以 dictionary 对象形式返回。条目按其添加到字典的顺序存储。

用途

使用 dictionary 创建字典 d。然后，您可以使用以下任何语法访问或更改 d。

语法

valueOut = d(keys)

d(keys) = newValues

d(keys) = []

valueOut = d{keys}

d{keys} = newValues

描述

valueOut = d(keys) 查找与 keys 关联的值。

d(keys) = newValues 将 newValues 的元素赋给由 keys 的对应值指定的条目。如果字典中不存在指定的键，则会添加一个新条目。如果您将多个值赋给同一个键，则只赋这些值中的最后一个值。对现有键的新赋值会覆盖该条目的值。

d(keys) = [] 从字典中删除与 keys 关联的条目。

valueOut = d{keys} 查找与 keys 关联的值并返回元胞的内容。如果 keys 是数组，则返回对应值的以逗号分隔的列表。如果字典值配置为元胞以外的数据类型，此语法会抛出错误。

d{keys} = newValues 将包含 newValues 的元素的元胞赋给由对应键值指定的条目。如果字典值配置为元胞以外的数据类型，此语法会抛出错误。

对象函数

`configureDictionary`	使用指定的键和值类型创建字典
`insert`	向字典中添加条目
`lookup`	按键在字典中查找值
`remove`	删除字典条目
`entries`	Key-value pairs of dictionary
`keys`	字典的键
`values`	字典的值
`types`	字典键和值的类型
`numEntries`	字典中键-值对组的数量
`isConfigured`	Determine if dictionary has types assigned to keys and values
`isKey`	确定字典是否包含键

示例

全部折叠

创建和管理字典

打开实时脚本

创建一个将不同车辆名称映射到轮数的字典。

创建一个名称数组和一个对应轮数的数组。

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

创建一个字典，使用名称作为键，使用轮数作为值。

d = dictionary(names,wheels)

d =

  dictionary (string ⟼ double) with 3 entries:

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

通过使用键作为索引来访问字典值。

d("Tricycle")

ans = 
3

通过将新值赋给现有键来修改一个字典条目。

d("Bicycle") = 2.5

d =

  dictionary (string ⟼ double) with 3 entries:

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

通过为新键赋值来向字典添加一个新条目。

d("Car") = 4

d =

  dictionary (string ⟼ double) with 4 entries:

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

使用由键和值组成的数组添加多个条目。

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

通过将空数组赋给现有键来删除一个条目。

d("Truck") = []

d =

  dictionary (string ⟼ double) with 6 entries:

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

字典会自动转换新条目以匹配配置的数据类型。如果无法进行转换，MATLAB 会抛出错误。

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

在字典中存储多种数据类型

打开实时脚本

字典值必须具有相同的类型。但不同类型的数据可以作为一个元胞存储在字典中。

创建一个包含各种数据类型值的元胞数组和一个由键组成的字符串数组。

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"

使用指定的键和值创建一个字典。

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]}

使用 values 函数将值提取为一个元胞数组。

values(d)

ans=4×1 cell array
    {[24-Jan-2026 19:18:05]}
    {                @myfun}
    {1×1 struct            }
    {[             1 2 3 4]}

使用花括号 {} 直接查找作为值存储的元胞的内容。（自 R2023a 开始提供）

d{"numeric array"}

ans = 1×4

     1     2     3     4

同样，您可以使用花括号 {} 将任何数据类型的新条目添加到具有元胞值的现有字典中。

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}

创建空的已配置字典

打开实时脚本

使用 configureDictionary 创建一个空的已配置字典。

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

d =

  dictionary (string ⟼ double) with no entries.

在 R2023b 之前：指定所需类型的空输入。例如，d = dictionary(string([]),[]).

只要数据类型匹配或可以转换为已配置字典的数据类型，您就可以添加新字典条目。

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

d =

  dictionary (string ⟼ double) with 3 entries:

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

向未配置的字典中添加条目

打开实时脚本

通过在不使用输入的情况下调用 dictionary 来创建一个未配置的字典。

d = dictionary

d =

  dictionary with unset key and value types.

当您向未配置的字典添加条目时，MATLAB 使用条目的数据类型配置字典。

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

d =

  dictionary (string ⟼ double) with 3 entries:

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

提示

您可以对键和值都使用自定义类。但是，如果您使用的类具有重载的索引或大小查询，或其行为与标准数组行为不同，则字典可能不会按预期工作。有关其他信息，请参阅Dictionaries and Custom Classes。

条目按其添加顺序存储，并以相同的顺序返回。例如，创建一个包含三个条目的字典：

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

d =

  dictionary (string ⟼ double) with 3 entries:

    "first"  ⟼ 1
    "second" ⟼ 2
    "third"  ⟼ 3

此字典的键或值以其添加顺序返回。

k = keys(d)

k = 

  3×1 string array

    "first"
    "second"
    "third"

如果添加其他条目，它们将添加到先前条目的末尾。

d("fourth") = 4

d =

  dictionary (string ⟼ double) with 4 entries:

    "first"  ⟼ 1
    "second" ⟼ 2
    "third"  ⟼ 3
    "fourth" ⟼ 4

更新一个条目的值不会更改其在条目顺序中的位置。

扩展功能

全部展开

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

用法说明和限制：

不要使用对象（例如用户编写的类和 fi (Fixed-Point Designer) 对象）作为键。
如果通过向 dictionary 函数传递实数键和值来配置实数值类型的字典，则该字典只能包含实数值类型。代码生成不支持向这样的字典添加复数键或值。
不能将字典定义为常量。
即使字典在代码生成时为常量，代码生成器也不会将该字典视为常量。这意味着您不能将字典、字典键或字典值传递给需要常量输入的函数。您不能将字典、字典键或字典值用于需要常量的操作，如对异构元胞数组进行索引。代码生成器也无法对字典执行依赖常量值的优化，如常量折叠。

有关为 MATLAB 字典生成 C/C++ 代码时适用的其他注意事项，请参阅代码生成的字典限制 (MATLAB Coder)。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

请参阅“C/C++ 代码生成”部分中的用法说明和限制。同样的用法说明和限制也适用于 GPU 代码生成。

版本历史记录

在 R2022b 中推出

全部展开

R2024b: 代码生成支持

您可以为 dictionary 函数生成 C/C++ 代码，但存在一些限制。

R2023b: `configureDictionary` 函数：使用配置的键和值创建字典

使用 configureDictionary 为键和值创建指定类型的空字典。

例如，创建一个 dictionary，它配置为接受字符串作为键、接受双精度值作为值。

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

d =

  dictionary (string ⟼ double) with no entries.

R2023b: `lookup`、`insert` 和 `remove` 函数：管理字典条目

使用 lookup、insert 和 remove 来执行基本的 dictionary 操作。

R2023a: 使用花括号 `{}` 在元胞中查找值和赋值

可以使用花括号 {} 直接对元胞中的数据进行查找和赋值。当字典的值是元胞时，使用圆括号 () 的查找将返回一个元胞。访问该元胞的内容需要对该元胞进行索引。引入花括号访问允许直接访问元胞值的内容。例如，字典 d 有三个元胞值

d = 

  dictionary (double ⟼ cell) with 3 entries:

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

使用圆括号 () 执行查找。值以包含数组的元胞形式返回。

d(1)

ans = 

    {[4 5 6]}

使用花括号 {} 执行查找。值以数组形式返回。

d{1}

ans = 

    [4 5 6]

R2023a: 使用 Python 对象作为字典中的键

您可以使用 Python 对象作为字典中的键。

R2022b: 建议替换 `containers.Map`

推荐使用 dictionary 而不是 containers.Map，因为它支持更多数据类型作为键和值，并能提供更好的性能。

另请参阅

dictionary

说明

创建对象

语法

描述

输入参量

keys — 键 标量 | 数组 | 元胞数组

values — 值 标量 | 数组 | 元胞数组

k1,v1,...,kN,vN — 键-值对组（作为单独参量） 标量 | 数组

输出参量

d — 字典 dictionary 对象

用途

语法

描述

对象函数

示例

创建和管理字典

在字典中存储多种数据类型

创建空的已配置字典

向未配置的字典中添加条目

提示

扩展功能

C/C++ 代码生成 使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成 使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

版本历史记录

R2024b: 代码生成支持

R2023b: configureDictionary 函数：使用配置的键和值创建字典

R2023b: lookup、insert 和 remove 函数：管理字典条目

R2023a: 使用花括号 {} 在元胞中查找值和赋值

R2023a: 使用 Python 对象作为字典中的键

R2022b: 建议替换 containers.Map

另请参阅

主题

`keys` — 键
标量 | 数组 | 元胞数组

`values` — 值
标量 | 数组 | 元胞数组

`k1,v1,...,kN,vN` — 键-值对组（作为单独参量）
标量 | 数组

`d` — 字典
`dictionary` 对象

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

R2023b: `configureDictionary` 函数：使用配置的键和值创建字典

R2023b: `lookup`、`insert` 和 `remove` 函数：管理字典条目

R2023a: 使用花括号 `{}` 在元胞中查找值和赋值

R2022b: 建议替换 `containers.Map`