readstruct

Create structure from file

collapse all in page

    Syntax

    S = readstruct(filename)
    S = readstruct(filename,Name,Value)

    Description

    example

    S = readstruct(filename) creates a structure by reading structured data from a file. The input file must contain a well-formed XML structure.

    readstruct automatically detects the datatypes of the contents in the input file.

    example

    S = readstruct(filename,Name,Value) creates a structure from a file with additional options specified by one or more name-value pair 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

    Open Live Script

    Read an XML file as a structure, create variables from the structure, and query its contents.

    The file music.xml has the following structure.

    Read music.xml into MATLAB as a structure S. This structure contains one parent node MusicalEnsemble that has two sibling nodes, Ensemble and Musicians. 

    S = readstruct("music.xml")
    S = struct with fields:
     Ensemble: [1x1 struct]
    Musicians: [1x1 struct]

    Create a 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. 

    band.Instrumentation
    ans = struct with fields:
    Instrument: [1x4 struct]

    Create a 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]
    Open Live Script

    Create a structure from an XML 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.xml, the second Instrument node contains a non-empty field pianotype. Since the other Instrument nodes do not have a value specified for pianotype, readstruct returns missing for pianotype under those Instrument nodes.

    Read the XML file music.xml to a structure S.

    S = readstruct("music.xml")
    S = struct with fields:
     Ensemble: [1x1 struct]
    Musicians: [1x1 struct]

    Query the Instrument structure in S to view its contents. 

    S.Ensemble.Instrumentation.Instrument
    ans=1×4 struct array with fields:
    typeAttribute
    Text
    pianotype
    drumkit
    basstype
    Open Live Script

    Read a text file as a structure.

    The file music.txt has the following structure.

    Read the text file music.txt into MATLAB as a structure S. Specify 'FileType' as 'xml' to read the contents of the input as an XML file.

    S = readstruct("music.txt","FileType","xml")
    S = struct with fields:
     Ensemble: [1x1 struct]
    Musicians: [1x1 struct]
    Open Live Script

    Create a structure from a specific element node in the input file by using the 'StructNodeName' name-value pair.

    Read the Instrumentation node from the XML file music.xml.

    S = readstruct("music.xml","StructNodeName","Instrumentation")
    S = struct with fields:
    Instrument: [1x4 struct]

    Open Live Script

    Specify the precise XML element node under which to start reading the structure in the input file.

    Read the fifth Name element in the XML file music.xml. Specify the full XPath expression of the element node as the value of 'StructSelector'.

    S = readstruct("music.xml","StructSelector","/MusicalEnsemble/Musicians/Name[5]")
    S = struct with fields:
    roleAttribute: "bassist"
             Text: "John"

    Input Arguments

    collapse all

    Name of the file to read, specified as a character vector or a string scalar.

    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'

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

    Example: 'C:\myFolder\myFile.xml'

    Example: 'dataDir\myFile.xml'

    Remote Location

    If the file is stored at a remote location, then specify a uniform resource locator (URL) of the form:

    scheme_name://path_to_file/my_file.ext

    Based on your 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'

    Name-Value Pair Arguments

    Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

    Example: 'ImportAttributes',true specifies to import the attributes associated with element nodes as fields of the output structure.

    Type of file, specified as the comma-separated pair consisting of 'FileType' and one of these values:

    • 'auto' — Automatically detect the file format of the input file from the extension specified in filename.

    • 'xml' — Read the contents of the input file as XML.

    If the file extension in filename is not .xml, you can specify the value of 'FileType' as 'xml' to read the contents of the input file as XML.

    Example: 'FileType','xml'

    Starting XML element, specified as the comma-separated pair consisting of 'StructNodeName' and either a character vector or string scalar readstruct reads the structure in the input file, starting with the specified XML element. If you do not specify StructNodeName, then readstruct reads the structure starting at the root of the XML file.

    readstruct matches the first node in the XML document whose name matches the value specified in StructNodeName.

    Example: 'StructNodeName','RootName'

    Starting XML Path, specified as the comma-separated pair consisting of 'StructSelector' and a character vector or string scalar readstruct reads the structure in the input file starting at the element at the specified path. The value of 'StructSelctor' must be a valid XPath version 1.0 expression.

    • To read one of several sibling nodes under one parent node in the structure, you can specify ChildNode[n], where n corresponds to the sibling node that you want to index. For example, the path RootNode/ChildNode[2] selects the second ChildNode element whose parent is RootNode.

    • To read the value of an attribute belonging to an element node in the input XML file, specify @ before the name of the attribute. For example, RootNode/ChildNode[2]/@AttributeName selects the attribute AttributeName belonging to the second ChildNode element whose parent is RootNode.

    Import attributes, specified as the comma-separated pair consisting of 'ImportAttributes' and either 1 (true) or 0 (false). If you specify the value as false, then readstruct will not import the XML attributes in the input file as fields in the output structure.

    Example: 'ImportAttributes',false

    Attribute suffix, specified as the comma-separated pair consisting of 'AttributeSuffix' and either a character vector or string scalar. 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: 'AtributeSuffix','_att'

    Output Arguments

    collapse all

    Output 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.

    See Also

    Introduced in R2020b

    MATLAB Documentation

    Support