readstruct

从文件创建结构体数组

语法

S = readstruct(filename)

S = readstruct(filename,Name,Value)

说明

S = readstruct(filename) 通过从指定文件中读取数据来创建结构体数组。输入文件必须包含格式良好的 XML 或 JSON 文本。readstruct 自动检测输入文件内容的数据类型。

S = readstruct(filename,Name,Value) 使用一个或多个名称-值参量指定选项。例如，当 filename 中的文件扩展名不是 .xml 时，您可以通过调用 S = readstruct(filename,FileType="xml") 以 XML 形式读取输入文件的内容。

示例

全部折叠

从 XML 文件创建结构体

打开实时脚本

以结构体形式将 XML 文件的内容导入，从该结构体创建变量，并查询其内容。

显示 music.xml 文件内容。

type music.xml

<MusicalEnsemble>
    <Ensemble>
        <Music>Jazz</Music>
        <BandName>Kool Katz</BandName>
        <Instrumentation>
            <Instrument type="wind">Trumpet
            </Instrument>
            <Instrument type="percussion">Piano
                <pianotype>concert grand</pianotype>
            </Instrument>
            <Instrument type="percussion">Drums
                <drumkit>Bass drum</drumkit>
                <drumkit>Floor tom</drumkit>
                <drumkit>Snare drum</drumkit>
                <drumkit>Hi-hat</drumkit>
                <drumkit>Ride cymbal</drumkit>
            </Instrument>
            <Instrument type="string">Bass
                <basstype>upright</basstype>
            </Instrument>
        </Instrumentation>
    </Ensemble>
    <Musicians>
        <Name role="trumpeter">Miles</Name>
        <Name role="vocalist">Roger</Name>
        <Name role="pianist">Diana</Name>
        <Name role="drummer">George</Name>
        <Name role="bassist">John</Name>
    </Musicians>
</MusicalEnsemble>

将 music.xml 作为结构体导入 MATLAB® 中。此结构体包含一个名为 MusicalEnsemble 的父节点，该节点有两个同级节点 Ensemble 和 Musicians。

S = readstruct("music.xml")

S = struct with fields:
     Ensemble: [1×1 struct]
    Musicians: [1×1 struct]

从第一个同级节点创建变量 band。band 有三个字段，其中一个是名为 Instrumentation 的结构体。

band = S.Ensemble

band = struct with fields:
              Music: "Jazz"
           BandName: "Kool Katz"
    Instrumentation: [1×1 struct]

在 band 中查询 Instrumentation 以查看其内容。

ins = band.Instrumentation

ins = struct with fields:
    Instrument: [1×4 struct]

从第二个同级节点创建变量 musicians。musicians 有一个名为 Name 的字段，其中包含五个结构体。

musicians = S.Musicians

musicians = struct with fields:
    Name: [1×5 struct]

从文本文件创建结构体

打开实时脚本

将文本文件的内容作为结构体导入。

显示 music.info 文件内容。

type music.info

<MusicalEnsemble>
    <Ensemble>
        <Music>Jazz</Music>
        <BandName>Kool Katz</BandName>
        <Instrumentation>
            <Instrument type="wind">Trumpet
            </Instrument>
            <Instrument type="percussion">Piano
                <pianotype>concert grand</pianotype>
            </Instrument>
            <Instrument type="percussion">Drums
                <drumkit>Bass drum</drumkit>
                <drumkit>Floor tom</drumkit>
                <drumkit>Snare drum</drumkit>
                <drumkit>Hi-hat</drumkit>
                <drumkit>Ride cymbal</drumkit>
            </Instrument>
            <Instrument type="string">Bass
                <basstype>upright</basstype>
            </Instrument>
        </Instrumentation>
    </Ensemble>
    <Musicians>
        <Name role="trumpeter">Miles</Name>
        <Name role="vocalist">Roger</Name>
        <Name role="pianist">Diana</Name>
        <Name role="drummer">George</Name>
        <Name role="bassist">John</Name>
    </Musicians>
</MusicalEnsemble>

将 music.info 作为结构体导入 MATLAB 中。将 FileType 名称-值参量指定为 ''xml"，以将内容作为 XML 文件读取。

S = readstruct("music.info",FileType="xml")

S = struct with fields:
     Ensemble: [1×1 struct]
    Musicians: [1×1 struct]

从 JSON 文件创建结构体

自 R2023b 起

打开实时脚本

将 JSON 文件的内容作为结构体导入，从该结构体创建变量，并查询其内容。

显示 music.json 文件内容。

type music.json

{
    "Ensemble": {
        "Music": "jazz",
        "BandName": "Kool Katz",
        "Instrumentation": [
            {
                "Type": "wind",
                "Instrument": "trumpet",
            },
            {
                "Type": "percussion",
                "Instrument": "piano",
                "Pianotype": "concert grand",
            },
            {
                "Type": "percussion",
                "Instrument": "drums",
                "Drumkit": [
                    "bass drum",
                    "floor tom",
                    "snare drum",
                    "hi-hat",
                    "ride cymbal"
                ],
            },
            {
                "Type": "string",
                "Instrument": "bass",
                "Basstype": "upright"
            }
        ]
    },
    "Musicians": [
        {
            "Role": "trumpeter",
            "Name": "Miles"
        },
        {
            "Role": "vocalist",
            "Name": "Roger"
        },
        {
            "Role": "pianist",
            "Name": "Diana"
        },
        {
            "Role": "drummer",
            "Name": "George"
        },
        {
            "Role": "bassist",
            "Name": "John"
        }
    ]
}

将 music.json 作为结构体导入 MATLAB 中。此结构体包含两个名为 Ensemble 和 Musicians 的同级节点。

S = readstruct("music.json")

S = struct with fields:
     Ensemble: [1×1 struct]
    Musicians: [1×5 struct]

从第一个同级节点创建一个变量 band。band 有三个字段，其中一个是名为 Instrumentation 的结构体数组。

band = S.Ensemble

band = struct with fields:
              Music: "jazz"
           BandName: "Kool Katz"
    Instrumentation: [1×4 struct]

在 band 中查询 Instrumentation 以查看其内容。

ins = band.Instrumentation

ins=1×4 struct array with fields:
    Type
    Instrument
    Pianotype
    Drumkit
    Basstype

从第二个同级节点创建一个变量 musicians。

musicians = S.Musicians

musicians=1×5 struct array with fields:
    Role
    Name

获取非统一结构体中元素的信息

打开实时脚本

从不包含统一结构化数据的文件创建结构体，然后显示其内容。

如果一个同级节点包含其他同级节点没有的字段，则对于在其他节点中找不到的字段，readstruct 将返回 missing。例如，在文件 music.json 中，Instrumentation 的第二个节点包含名为 Pianotype 的非空字段。由于其他同级节点没有为 Pianotype 指定的值，因此对于在这些节点下的 Pianotype，readstruct 返回 missing。

type music.json

{
    "Ensemble": {
        "Music": "jazz",
        "BandName": "Kool Katz",
        "Instrumentation": [
            {
                "Type": "wind",
                "Instrument": "trumpet",
            },
            {
                "Type": "percussion",
                "Instrument": "piano",
                "Pianotype": "concert grand",
            },
            {
                "Type": "percussion",
                "Instrument": "drums",
                "Drumkit": [
                    "bass drum",
                    "floor tom",
                    "snare drum",
                    "hi-hat",
                    "ride cymbal"
                ],
            },
            {
                "Type": "string",
                "Instrument": "bass",
                "Basstype": "upright"
            }
        ]
    },
    "Musicians": [
        {
            "Role": "trumpeter",
            "Name": "Miles"
        },
        {
            "Role": "vocalist",
            "Name": "Roger"
        },
        {
            "Role": "pianist",
            "Name": "Diana"
        },
        {
            "Role": "drummer",
            "Name": "George"
        },
        {
            "Role": "bassist",
            "Name": "John"
        }
    ]
}

将 music.json 作为结构体导入。

S = readstruct("music.json")

S = struct with fields:
     Ensemble: [1×1 struct]
    Musicians: [1×5 struct]

查询 S 中的 Pianotype 结构体，并将其内容赋给变量。

[ins1,ins2,ins3,ins4] = S.Ensemble.Instrumentation.Pianotype

ins1 = missing
    <missing>

ins2 = 
"concert grand"

ins3 = missing
    <missing>

ins4 = missing
    <missing>

注册自定义 XML 命名空间前缀

打开实时脚本

使用 RegisteredNamespaces 名称-值参量将自定义 XML 命名空间前缀注册到输入文件中的现有命名空间 URL。

要将 students.xml 文件的第二个 Street 元素节点作为结构体读取，请将 StructSelector 名称-值参量指定为 //Student[2]/Address/myPrefix:Street"。将 RegisteredNamespaces 指定为 ["myPrefix","https://www.mathworks.com"]。

S = readstruct("students.xml",RegisteredNamespaces=["myPrefix","https://www.mathworks.com"], ...
    StructSelector="//Student[2]/Address/myPrefix:Street")

S = struct with fields:
    xmlnsAttribute: "https://www.mathworks.com"
              Text: "4641 Pearl Street"

按照所选 JSON 标准解析数据

自 R2023b 起

打开实时脚本

通过严格遵守 JSON 标准，但在解析时允许尾部逗号，从 JSON 文件创建一个结构体。

S = readstruct("music.json",ParsingMode="strict",AllowTrailingCommas=true)

S = struct with fields:
     Ensemble: [1×1 struct]
    Musicians: [1×5 struct]

输入参数

全部折叠

`filename` — 要读取的文件的名称
字符串标量 | 字符向量

要读取的文件的名称，指定为字符串标量或字符向量。文件类型由文件扩展名或 FileType 名称-值参量确定。扩展名为 .xml 或 .json 的文件分别解释为 XML 或 JSON (自 R2023b 起) 文件，而其他文件扩展名需要 FileType 名称-值参量。扩展名为 .zip、.gz 或 .tar 的文件解释为压缩或存档文件。

压缩文件格式作为文件读取。存档文件格式被视为文件夹。例如，函数将 mydatafiles.zip 解释为文件夹，因此必须在其中指定一个文件，如 mydatafiles.zip/file1.xlsx。对于以 .gz 扩展名结尾的文件，函数通过使用 .gz 之前的扩展名来确定文件格式。例如，mydata.csv.gz 作为 CSV 文件读取。 (自 R2025a 起)

根据文件的位置，filename 可以采用下列形式之一。

位置

形式

当前文件夹或 MATLAB^® 路径上的文件夹

指定 filename 中文件的名称。

例如："myFile.xml"

例如："myFile.json"

文件夹中的文件

如果该文件不在当前文件夹或 MATLAB 路径下的文件夹中，则在 filename 中指定完整或相对路径名称。

例如："C:\myFolder\myFile.xml"

例如："C:\myFolder\myFile.json"

例如："dataDir\myFile.xml"

例如："dataDir\myFile.json"

Internet URL

如果文件指定为 Internet 统一资源定位器 (URL)，则 filename 必须包含协议类型 "http://" 或 "https://"。

例如："http://hostname/path_to_file/my_data.xml"

例如："http://hostname/path_to_file/my_data.json"

远程位置

如果文件存储在远程位置，则 filename 必须包含用以下格式指定的文件的完整路径：

scheme_name://path_to_file/my_file.ext

根据远程位置，scheme_name 可以是下表中的值之一。

远程位置	`scheme_name`
Amazon S3™	`s3`
Windows Azure^® Blob 存储	`wasb`, `wasbs`
HDFS™	`hdfs`

有关详细信息，请参阅处理远程数据。

例如："s3://bucketname/path_to_file/my_setup.xml"

例如："s3://bucketname/path_to_file/my_setup.json"

名称-值参数

全部展开

以 Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组，其中 Name 是参量名称，Value 是对应的值。名称-值参量必须出现在其他参量之后，但参量对组的顺序无关紧要。

示例: readstruct("myfile.xml",DateLocale="en_US") 使用 en-US 日期区域设置从 myfile.xml 导入数据。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例: readstruct("myfile.xml","DateLocale","en_US") 使用 en-US 日期区域设置从 myfile.xml 导入数据。

文件信息

全部展开

`FileType` — 文件类型
`"xml"` | `"json"`

文件类型，指定为以下值之一：

"xml" - 将输入文件的内容作为 XML 读取，而不考虑 filename 中指定的文件扩展名。
"json" - 将输入文件的内容作为 JSON 读取，而不考虑 filename 中指定的文件扩展名。 (自 R2023b 起)

如果您在 filename 中指定不是 .xml 或 .json 的文件扩展名，您可以将 FileType 指定为 "xml" 或 "json"，以分别以 XML 或 JSON 格式读取输入文件的内容。

示例: FileType="xml"

`DateLocale` — 用于读取日期的区域设置
字符串标量 | 字符向量

用于读取日期的区域设置，指定为字符串标量或 xx_YY 形式的字符向量，其中：

xx 是指示语言的小写 ISO 639-1 双字母代码。
YY 是指示国家/地区的大写 ISO 3166-1 alpha-2 代码。

下表列出了区域设置的某些常用值。

区域设置	语言	国家/地区
`"de_DE"`	德语	德国
`"en_GB"`	英语	英国
`"en_US"`	英语	美国
`"es_ES"`	西班牙语	西班牙
`"fr_FR"`	法语	法国
`"it_IT"`	意大利语	意大利
`"ja_JP"`	日语	日本
`"ko_KR"`	韩语	韩国
`"nl_NL"`	荷兰	荷兰
`"zh_CN"`	简体中文	中国

示例: DateLocale="ja_JP"

`StructNodeName` — 开始元素的名称
字符串标量 | 字符向量

开始元素的名称，指定为字符串标量或字符向量。为了确定从哪里开始读取，readstruct 在文件中查找其名称与 StructNodeName 中指定的值匹配的第一个节点。readstruct 从该节点开始读取输入文件的内容。如果不指定 StructNodeName，则 readstruct 会从文件的根开始读取内容。

示例: StructNodeName="RootName"

示例: StructNodeName="Instrumentation"

`StructSelector` — 开始 XML 路径或 JSON 指针
字符串标量 | 字符向量

开始 XML 路径或 JSON 指针，指定为字符串标量或字符向量。readstruct 从指定的 XML 路径或 JSON 指针处的元素开始读取输入文件的内容。

对于 XML 文件，StructSelector 的值必须为有效的 XPath 版本 1.0 表达式。可以使用以下语法指定 XML 路径：

XML 选取操作	语法	示例
按名称选择节点，而不考虑它在文档中的位置。	在名称前加两个正斜杠 (`//`) 前缀。	S = readstruct("music.xml",StructSelector="//Ensemble")
在一组节点中按索引选择一个特定节点。	在方括号 (`[]`) 中提供节点的索引。	S = readstruct("music.xml", ... StructSelector= ... "//Ensemble/Instrumentation/Instrument[3]")
指定运算的优先级。	在要首先计算的表达式前后添加圆括号。	S = readstruct("students.xml", ... StructSelector="//Student/Name[4]")
指定运算的优先级。	在要首先计算的表达式前后添加圆括号。	S = readstruct("students.xml", ... StructSelector="(//Student/Name)[4]")

可以使用以下语法指定 JSON 指针：

JSON 选取操作	语法	示例
通过名称选择 JSON 对象关键字。	在名称前加一个正斜杠 (`/`) 前缀。	S = readstruct("music.json",StructSelector="/Musicians")
通过索引选择 JSON 数组元素。	在正斜杠 (`/`) 后提供节点的索引。此索引是从 0 开始的。	S = readstruct("music.json", ... StructSelector="/Musicians/4")

`WebOptions` — `HTTP` 或 `HTTPS` 请求选项
`weboptions` 对象

HTTP 或 HTTPS 请求选项，指定为 weboptions 对象。当指定的 filename 是包含协议类型 "http://" 或 "https://" 的 Internet URL 时，由 weboptions 对象确定如何导入数据。

XML 属性

全部展开

`ImportAttributes` — 导入属性
`true` 或 `1` (默认) | `false` 或 `0`

导入属性，指定为数值或逻辑值 1 (true) 或 0 (false)。如果将值指定为 false，则 readstruct 不会将输入文件中的 XML 属性作为输出结构体中的字段导入。

示例: ImportAttributes=false

`AttributeSuffix` — 属性后缀
`"Attribute"` (默认) | 字符串标量 | 字符向量

属性后缀，指定为字符串标量或字符向量。readstruct 将此后缀附加到输出结构体中所有与输入 XML 文件中的属性对应的字段名称。如果未指定 AttributeSuffix，则 readstruct 默认将后缀 "Attribute" 附加到与输入 XML 文件中的属性对应的所有字段名称。

示例: AttributeSuffix="_att"

`RegisteredNamespaces` — 注册的 XML 命名空间前缀集
字符串矩阵

注册的 XML 命名空间前缀集，指定为前缀的字符串矩阵。读取函数在计算 XML 文件的 XPath 表达式时使用这些前缀。将命名空间前缀及其关联的 URL 指定为 N×2 字符串矩阵，其中 N 是命名空间前缀和 URL 对的数量。RegisteredNamespaces 还可以用于计算由选择器名称-值参量（例如 readstruct 的 StructSelector 或 readtable 和 readtimetable 的 VariableSelectors）指定的 XPath 表达式。

默认情况下，读取函数会自动检测要注册以用于 XPath 计算的命名空间前缀，但您也可以使用 RegisteredNamespaces 名称-值参量注册新命名空间前缀。当 XML 节点有命名空间 URL 但在 XML 文件中没有声明的命名空间前缀时，您可以注册新命名空间前缀。

例如，对名为 example.xml 的不包含命名空间前缀的 XML 文件计算 XPath 表达式。将 RegisteredNamespaces 指定为 ["myprefix","https://www.mathworks.com"] 以将前缀 "myprefix" 赋给 URL https://www.mathworks.com。

S = readstruct("example.xml",StructSelector="/myprefix:Data", ...
RegisteredNamespaces=["myprefix","https://www.mathworks.com"])

示例: RegisteredNamespaces=["myprefix","https://www.mathworks.com"]

JSON 标准

全部展开

`ParsingMode` — 解析时如何严格遵循 JSON 标准
`"lenient"` (默认) | `"strict"`

自 R2023b 起

解析时如何遵守 JSON 标准的严格，指定为以下值之一：

"lenient"（默认值）- 将 AllowComments，AllowInfAndNaN 和 AllowTrailingCommas 的值设置为 true。
"strict" - 将 AllowComments，AllowInfAndNaN 和 AllowTrailingCommas 的值设置为 false。

`AllowComments` — 允许注释
`true` 或 `1`（默认值） | `false` 或 `0`

自 R2023b 起

允许输入文件中的注释，指定为以下值之一：

数值或逻辑值 1 (true)（默认值）- 注释在导入过程中不会导致错误。文件中的注释不被视为数据，不会读入 MATLAB。对于单行注释，注释可以“//”开头；对于多行注释，注释可以“/*”开头，以“*/”结尾。
数值或逻辑值 0 (false) - 注释会在导入过程中导致错误。

`AllowInfAndNaN` — 读取 `Inf` 和 `NaN` 字面值
`true` 或 `1`（默认值） | `false` 或 `0`

自 R2023b 起

读取输入文件中的 Inf 和 NaN 字面值，指定为以下值之一：

数值或逻辑值 1 (true)（默认值）- Inf 和 NaN 字面值（包括 Infinity、-Inf 和 -Infinity）读入 MATLAB。
数值或逻辑值 0 (false) - Inf 和 NaN 字面值会在导入过程中导致错误。

`AllowTrailingCommas` — 读取尾部逗号
`true` 或 `1`（默认值） | `false` 或 `0`

自 R2023b 起

读取输入文件中的尾部逗号，指定为以下值之一：

数值或逻辑值 1 (true)（默认值）-JSON 数组或 JSON 对象后的尾部逗号不会在导入过程中导致错误。
数值或逻辑值 0 (false) - 尾部逗号会在导入过程中导致错误。

输出参量

全部折叠

`S` — 输出结构体
MATLAB 结构体

输出结构体，以 MATLAB 结构体形式返回。结构体是使用被称为字段的数据容器将相关数据组合在一起的一种数据类型。每个字段都可以包含任意类型的数据。使用 structName.fieldName 格式的圆点表示法来访问结构体中的数据。有关结构体的详细信息，请参阅 struct。

扩展功能

全部展开

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

用法说明和限制：

readstruct 仅支持具有 XML 文件的基于线程的工作流。

版本历史记录

在 R2020b 中推出

全部展开

R2025a: 从压缩和存档文件中读取数据

您可以将压缩和存档文件中的数据作为结构体读取。

R2023b: 从 JSON 文件中读取数据

可以将 JSON 文件的内容作为结构体导入 MATLAB 中。

另请参阅

writestruct

readstruct

语法

说明

示例

从 XML 文件创建结构体

从文本文件创建结构体

从 JSON 文件创建结构体

获取非统一结构体中元素的信息

注册自定义 XML 命名空间前缀

按照所选 JSON 标准解析数据

输入参数

filename — 要读取的文件的名称 字符串标量 | 字符向量

名称-值参数

文件信息

FileType — 文件类型 "xml" | "json"

DateLocale — 用于读取日期的区域设置 字符串标量 | 字符向量

StructNodeName — 开始元素的名称 字符串标量 | 字符向量

StructSelector — 开始 XML 路径或 JSON 指针 字符串标量 | 字符向量

WebOptions — HTTP 或 HTTPS 请求选项 weboptions 对象

XML 属性

ImportAttributes — 导入属性 true 或 1 (默认) | false 或 0

AttributeSuffix — 属性后缀 "Attribute" (默认) | 字符串标量 | 字符向量

RegisteredNamespaces — 注册的 XML 命名空间前缀集 字符串矩阵

JSON 标准

ParsingMode — 解析时如何严格遵循 JSON 标准 "lenient" (默认) | "strict"

AllowComments — 允许注释 true 或 1（默认值） | false 或 0

AllowInfAndNaN — 读取 Inf 和 NaN 字面值 true 或 1（默认值） | false 或 0

AllowTrailingCommas — 读取尾部逗号 true 或 1（默认值） | false 或 0

输出参量

S — 输出结构体 MATLAB 结构体

扩展功能

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

版本历史记录

R2025a: 从压缩和存档文件中读取数据

R2023b: 从 JSON 文件中读取数据

另请参阅

`filename` — 要读取的文件的名称
字符串标量 | 字符向量

`FileType` — 文件类型
`"xml"` | `"json"`

`DateLocale` — 用于读取日期的区域设置
字符串标量 | 字符向量

`StructNodeName` — 开始元素的名称
字符串标量 | 字符向量

`StructSelector` — 开始 XML 路径或 JSON 指针
字符串标量 | 字符向量

`WebOptions` — `HTTP` 或 `HTTPS` 请求选项
`weboptions` 对象

`ImportAttributes` — 导入属性
`true` 或 `1` (默认) | `false` 或 `0`

`AttributeSuffix` — 属性后缀
`"Attribute"` (默认) | 字符串标量 | 字符向量

`RegisteredNamespaces` — 注册的 XML 命名空间前缀集
字符串矩阵

`ParsingMode` — 解析时如何严格遵循 JSON 标准
`"lenient"` (默认) | `"strict"`

`AllowComments` — 允许注释
`true` 或 `1`（默认值） | `false` 或 `0`

`AllowInfAndNaN` — 读取 `Inf` 和 `NaN` 字面值
`true` 或 `1`（默认值） | `false` 或 `0`

`AllowTrailingCommas` — 读取尾部逗号
`true` 或 `1`（默认值） | `false` 或 `0`

`S` — 输出结构体
MATLAB 结构体

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。