readstruct
Description
specifies options using one or more name-value arguments. For example, you can read the
contents of the input file as XML when the file extension in S
= readstruct(filename
,Name,Value
)filename
is
not .xml
by calling S =
readstruct(filename,FileType="xml")
.
Examples
Create Structure from XML File
Import the contents of an XML file as a structure, create variables from the structure, and query its contents.
Display the contents of the music.xml
file.
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>
Import music.xml
into MATLAB® as a structure. This structure contains one parent node named MusicalEnsemble
that has two sibling nodes, Ensemble
and Musicians
.
S = readstruct("music.xml")
S = struct with fields:
Ensemble: [1x1 struct]
Musicians: [1x1 struct]
Create the variable band
from the first sibling node. band
has three fields, one of which is a structure named Instrumentation
.
band = S.Ensemble
band = struct with fields:
Music: "Jazz"
BandName: "Kool Katz"
Instrumentation: [1x1 struct]
Query Instrumentation
in band
to view its contents.
ins = band.Instrumentation
ins = struct with fields:
Instrument: [1x4 struct]
Create the variable musicians
from the second sibling node. musicians
has one field called Name
, which contains five structures.
musicians = S.Musicians
musicians = struct with fields:
Name: [1x5 struct]
Create Structure from Text File
Import the contents of a text file as a structure.
Display the contents of the music.info
file.
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>
Import music.info
into MATLAB as a structure. Specify the FileType
name-value argument as "xml"
to read the contents as an XML file.
S = readstruct("music.info",FileType="xml")
S = struct with fields:
Ensemble: [1x1 struct]
Musicians: [1x1 struct]
Create Structure from JSON File
Since R2023b
Import the contents of a JSON file as a structure, create variables from the structure, and query its contents.
Display the contents of the music.json
file.
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" } ] }
Import music.json
into MATLAB as a structure. This structure contains two sibling nodes named Ensemble
and Musicians
.
S = readstruct("music.json")
S = struct with fields:
Ensemble: [1x1 struct]
Musicians: [1x5 struct]
Create the variable band
from the first sibling node. band
has three fields, one of which is a structure array named Instrumentation
.
band = S.Ensemble
band = struct with fields:
Music: "jazz"
BandName: "Kool Katz"
Instrumentation: [1x4 struct]
Query Instrumentation
in band
to view its contents.
ins = band.Instrumentation
ins=1×4 struct array with fields:
Type
Instrument
Pianotype
Drumkit
Basstype
Create a variable musicians
from the second sibling node.
musicians = S.Musicians
musicians=1×5 struct array with fields:
Role
Name
Get Information on Elements in Nonuniform Structure
Create a structure from a file that does not contain uniformly structured data, then show its contents.
If a sibling node contains fields that other sibling nodes do not have, readstruct
returns missing
for the fields that are not found in other nodes. For example, in the file music.json
, the second node of Instrumentation
contains a nonempty field named Pianotype
. Because the sibling nodes do not have a value specified for Pianotype
, readstruct
returns missing
for Pianotype
under those nodes.
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" } ] }
Import music.json
as a structure.
S = readstruct("music.json")
S = struct with fields:
Ensemble: [1x1 struct]
Musicians: [1x5 struct]
Query the Pianotype
structure in S
, and assign its contents to variables.
[ins1,ins2,ins3,ins4] = S.Ensemble.Instrumentation.Pianotype
ins1 = missing
<missing>
ins2 = "concert grand"
ins3 = missing
<missing>
ins4 = missing
<missing>
Register Custom XML Namespace Prefix
Register a custom XML namespace prefix to the existing namespace URL in the input file using the RegisteredNamespaces
name-value argument.
To read the second Street
element node of the students.xml
file as a structure, specify the StructSelector
name-value argument as "//Student[2]/Address/myPrefix:Street"
. Specify RegisteredNamespaces
as ["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"
Parse Data by Selected JSON Standards
Since R2023b
Create a structure from a JSON file by strictly adhering to JSON standards but allowing trailing commas while parsing.
S = readstruct("music.json",ParsingMode="strict",AllowTrailingCommas=true)
S = struct with fields:
Ensemble: [1x1 struct]
Musicians: [1x5 struct]
Input Arguments
filename
— Name of file to read
string scalar | character vector
Name of the file to read, specified as a string scalar or character vector. The file
type is determined by either the file extension or the FileType
name-value argument. Files with the .xml
or .json
extension are interpreted as XML or JSON (since R2023b) files,
respectively, while other file extensions require the FileType
name-value argument.
Depending on the location of your file, filename
can take one of
these forms.
Location | Form | ||||||||
---|---|---|---|---|---|---|---|---|---|
Current folder or folder on the MATLAB® path | Specify the name of the file in
Example:
Example:
| ||||||||
File in a folder | If the file is not in the current folder or in a folder on the
MATLAB path, then specify the full or relative pathname in
Example:
Example:
Example:
Example:
| ||||||||
Internet URL | If the file is specified as an internet uniform resource locator
(URL), then Example:
Example:
| ||||||||
Remote location | If the file is stored at a remote location, then
Based on the remote location,
For more information, see Work with Remote Data. Example:
Example:
|
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: readstruct("myfile.xml",DateLocale="en_US")
imports data from
myfile.xml
using the en-US locale for dates.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: readstruct("myfile.xml","DateLocale","en_US")
imports data
from myfile.xml
using the en-US locale for dates.
FileType
— Type of file
"xml"
| "json"
Type of file, specified as one of these values:
"xml"
— Read the contents of the input file as XML, regardless of the file extension specified infilename
."json"
— Read the contents of the input file as JSON, regardless of the file extension specified infilename
. (since R2023b)
If you specify a file extension in filename
that is not
.xml
or .json
, you can specify
FileType
as "xml"
or "json"
to read the contents of the input file as XML or JSON, respectively.
Example: FileType="xml"
DateLocale
— Locale for reading dates
string scalar | character vector
Locale for reading dates, specified as a string scalar or character vector of the
form
, where:xx
_YY
xx
is a lowercase ISO 639-1 two-letter code indicating a language.YY
is an uppercase ISO 3166-1 alpha-2 code indicating a country.
This table lists some common values for the locale.
Locale | Language | Country |
---|---|---|
"de_DE" | German | Germany |
"en_GB" | English | United Kingdom |
"en_US" | English | United States |
"es_ES" | Spanish | Spain |
"fr_FR" | French | France |
"it_IT" | Italian | Italy |
"ja_JP" | Japanese | Japan |
"ko_KR" | Korean | Korea |
"nl_NL" | Dutch | Netherlands |
"zh_CN" | Chinese (simplified) | China |
Example: DateLocale="ja_JP"
StructNodeName
— Name of starting element
string scalar | character vector
Name of the starting element, specified as a string scalar or character vector. To
determine where to start reading, readstruct
finds the first node
in the file whose name matches the value specified in
StructNodeName
. readstruct
reads the contents
of the input file starting with that node. If you do not specify
StructNodeName
, then readstruct
reads the
contents starting at the root of the file.
Example: StructNodeName="RootName"
Example: StructNodeName="Instrumentation"
StructSelector
— Starting XML Path or JSON Pointer
string scalar | character vector
Starting XML Path or JSON Pointer, specified as a string scalar or character
vector. readstruct
reads the contents of the input file starting
with the element at the specified XML Path or JSON Pointer.
For XML files, the value of StructSelector
must be a valid
XPath version 1.0 expression. An XML Path can be specified using these
syntaxes:
XML Selection Operation | Syntax | Example |
---|---|---|
Select the node by name, regardless of its location in the document. | Prefix the name with two forward slashes (// ). |
S = readstruct("music.xml",StructSelector="//Ensemble") |
Select a specific node in a set of nodes by index. | Provide the index of the node in square brackets
([] ). |
S = readstruct("music.xml", ... StructSelector= ... "//Ensemble/Instrumentation/Instrument[3]") |
Specify precedence of operations. | Add parentheses around the expression you want to evaluate first. |
S = readstruct("students.xml", ... StructSelector="//Student/Name[4]") |
S = readstruct("students.xml", ... StructSelector="(//Student/Name)[4]") |
A JSON Pointer can be specified using these syntaxes:
JSON Selection Operation | Syntax | Example |
---|---|---|
Select a JSON object key by name. | Prefix the name with one forward slash (/ ). |
S = readstruct("music.json",StructSelector="/Musicians") |
Select a JSON array element by index. | Provide the index of the node after one forward slash
(/ ). This index is zero-based. |
S = readstruct("music.json", ... StructSelector="/Musicians/4") |
WebOptions
— HTTP
or HTTPS
request options
weboptions
object
HTTP
or HTTPS
request options, specified as
a weboptions
object. The
weboptions
object determines how to import data when the
specified filename
is an internet URL containing the protocol type
"http://"
or "https://"
.
ImportAttributes
— Import attributes
true
or 1
(default) |
false
or 0
Import attributes, specified as a numeric or logical 1
(true
) or 0
(false
). If you
specify the value as false
, then readstruct
does
not import the XML attributes in the input file as fields in the output
structure.
Example: ImportAttributes=false
AttributeSuffix
— Attribute suffix
"Attribute"
(default) | string scalar | character vector
Attribute suffix, specified as a string scalar or character vector.
readstruct
appends this suffix to all field names of the output
structure that correspond to attributes in the input XML file. If you do not specify
AttributeSuffix
, then readstruct
defaults to
appending the suffix "Attribute"
to all field names corresponding
to attributes in the input XML file.
Example: AttributeSuffix="_att"
RegisteredNamespaces
— Set of registered XML namespace prefixes
string matrix
Set of registered XML namespace prefixes, specified as a string matrix of
prefixes. The reading function uses these prefixes when evaluating XPath expressions
on an XML file. Specify the namespace prefixes and their associated URLs as an
N
-by-2 string matrix, where N
is the number of
pairs of namespace prefix and URLs. RegisteredNamespaces
can be
used when you also evaluate an XPath expression specified by a selector name-value
argument, such as StructSelector
for readstruct
,
or VariableSelectors
for readtable
and
readtimetable
.
By default, the reading function automatically detects namespace prefixes to
register for use in XPath evaluation, but you can also register new namespace prefixes
using the RegisteredNamespaces
name-value argument. You might
register a new namespace prefix when an XML node has a namespace URL, but no declared
namespace prefix in the XML file.
For example, evaluate an XPath expression on an XML file named
example.xml
that does not contain a namespace prefix. Specify
RegisteredNamespaces
as
["myprefix","https://www.mathworks.com"]
to assign the prefix
"myprefix"
to the URL
https://www.mathworks.com
.
S = readstruct("example.xml",StructSelector="/myprefix:Data", ... RegisteredNamespaces=["myprefix","https://www.mathworks.com"])
Example: RegisteredNamespaces=["myprefix","https://www.mathworks.com"]
ParsingMode
— How strictly to follow JSON standards while parsing
"lenient"
(default) | "strict"
Since R2023b
How strictly to follow JSON standards while parsing, specified as one of these values:
"lenient"
(default) – The values ofAllowComments
,AllowInfAndNaN
, andAllowTrailingCommas
are set totrue
."strict"
– The values ofAllowComments
,AllowInfAndNaN
, andAllowTrailingCommas
are set tofalse
.
AllowComments
— Allow comments
true
or 1
(default) | false
or 0
Since R2023b
Allow comments in the input file, specified as one of these values:
Numeric or logical
1
(true
) (default) – Comments do not cause an error during import. Comments in the file are not considered data and are not read into MATLAB. Comments can start with "//" for single-line comments or start with "/*" and end with "*/" for multi-line comments.Numeric or logical
0
(false
) – Comments cause an error during import.
AllowInfAndNaN
— Read Inf
and NaN
literals
true
or 1
(default) | false
or 0
Since R2023b
Read Inf
and NaN
literals in the input file,
specified as one of these values:
Numeric or logical
1
(true
) (default) –Inf
andNaN
literals (includingInfinity
,-Inf
, and-Infinity
) are read into MATLAB.Numeric or logical
0
(false
) –Inf
andNaN
literals cause an error during import.
AllowTrailingCommas
— Read trailing commas
true
or 1
(default) | false
or 0
Since R2023b
Read trailing commas in the input file, specified as one of these values:
Numeric or logical
1
(true
) (default) – Trailing commas after a JSON array or JSON object do not cause an error during import.Numeric or logical
0
(false
) – Trailing commas cause an error during import.
Output Arguments
S
— Output structure
MATLAB structure
Output structure, returned as a MATLAB structure. A structure is a data type that groups related data using data
containers called fields. Each field can contain any type of data. Access data in a
structure using dot notation of the form structName.fieldName
. For
more information on structures, see struct
.
Extended Capabilities
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
Usage notes and limitations:
readstruct
supports only thread-based workflows with XML files.
Version History
Introduced in R2020bR2023b: Read data from JSON files
You can import the contents of JSON files into MATLAB as structures.
See Also
MATLAB 명령
다음 MATLAB 명령에 해당하는 링크를 클릭했습니다.
명령을 실행하려면 MATLAB 명령 창에 입력하십시오. 웹 브라우저는 MATLAB 명령을 지원하지 않습니다.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)