Main Content

readstruct

Create structure array from file

Since R2020b

    Description

    example

    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.

    example

    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

    collapse all

    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]
    
    

    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]
    
    

    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
    
    

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

    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

    collapse all

    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 Locationscheme_name
    Amazon S3™s3
    Windows Azure® Blob Storagewasb, 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

    collapse all

    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"

    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 LanguageCountry
    "de_DE"GermanGermany
    "en_GB"EnglishUnited Kingdom
    "en_US"EnglishUnited States
    "es_ES"SpanishSpain
    "fr_FR"FrenchFrance
    "it_IT"ItalianItaly
    "ja_JP"JapaneseJapan
    "ko_KR"KoreanKorea
    "nl_NL"DutchNetherlands
    "zh_CN"Chinese (simplified)China

    Example: DateLocale="ja_JP"

    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"

    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 OperationSyntaxExample
    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 OperationSyntaxExample
    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")

    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

    collapse all

    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

    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"

    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

    collapse all

    Since R2023b

    How strictly to follow JSON standards while parsing, specified as one of these values:

    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.

    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.

    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

    collapse all

    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

    Version History

    Introduced in R2020b

    expand all

    See Also