readstruct

Create structure array from file

Since R2020b

Syntax

S = readstruct(filename)

S = readstruct(filename,Name,Value)

Description

S = readstruct(filename) creates a structure array by reading data from the specified file. The input file must contain well-formed XML or JSON text. readstruct automatically detects the data types of the contents in the input file.

S = readstruct(filename,Name,Value) 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 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 filename. Example: "myFile.xml" Example: "myFile.json"
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 filename. Example: "C:\myFolder\myFile.xml" Example: "C:\myFolder\myFile.json" Example: "dataDir\myFile.xml" Example: "dataDir\myFile.json"
Internet URL	If the file is specified as an internet uniform resource locator (URL), then filename must contain the protocol type "http://" or "https://". Example: "http://hostname/path_to_file/my_data.xml" Example: "http://hostname/path_to_file/my_data.json"
Remote location	If the file is stored at a remote location, then filename must contain the full path of the file specified with the form: scheme_name://path_to_file/my_file.ext Based on the remote location, scheme_name can be one of the values in this table. Remote Location scheme_name Amazon S3™ s3 Windows Azure® Blob Storage wasb, wasbs HDFS™ hdfs For more information, see Work with Remote Data. Example: "s3://bucketname/path_to_file/my_setup.xml" Example: "s3://bucketname/path_to_file/my_setup.json"

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.

File Information

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 in filename.

• "json" — Read the contents of the input file as JSON, regardless of the file extension specified in filename. (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 xx_YY, where:

• 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://".

XML Attributes

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

JSON Standards

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 of AllowComments, AllowInfAndNaN, and AllowTrailingCommas are set to true.

• "strict" – The values of AllowComments, AllowInfAndNaN, and AllowTrailingCommas are set to false.

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 and NaN literals (including Infinity, -Inf, and -Infinity) are read into MATLAB.

• Numeric or logical 0 (false) – Inf and NaN 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 R2020b

R2023b: Read data from JSON files

You can import the contents of JSON files into MATLAB as structures.