Main Content

readstruct

Create structure from file

    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

    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]
    
    

    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
    
    

    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]
    
    

    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]
    
    

    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"
    
    

    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 as a structure, specify the value of 'StructSelector' as '//Student[2]/Address/myPrefix:Street' and the value of 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"
    
    

    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'

    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'

    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'

    Name-Value 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'

    Locale for reading dates, specified as the comma-separated pair consisting of 'DateLocale' and a character vector or a string scalar of the form xx_YY, where:

    • YY is an uppercase ISO 3166-1 alpha-2 code indicating a country.

    • xx is a lowercase ISO 639-1 two-letter code indicating a language.

    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'

    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.

    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: 'AttributeSuffix','_att'

    Set of registered XML namespace prefixes, specified as the comma-separated pair consisting of RegisteredNamespaces and an array 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 Nx2 string array. 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 called 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.

    T = readtable("example.xml", "VariableSelector", "/myprefix:Data",...
     "RegisteredNamespaces", ["myprefix", "https://www.mathworks.com"])

    Example: 'RegisteredNamespaces',["myprefix", "https://www.mathworks.com"]

    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.

    Tips

    • Use XPath selectors to specify which elements of the XML input document to import. For example, suppose you want to import the XML file myFile.xml, which has the following structure:

      <data>
          <table category="ones">
              <var>1</var>
              <var>2</var>
          </table>
          <table category="tens">
              <var>10</var>
              <var>20</var>
          </table>
      </data>
      
      This table provides the XPath syntaxes that are supported for XPath selector name-value arguments, such as VariableSelectors or TableSelector.

      Selection OperationSyntaxExampleResult
      Select every node whose name matches the node you want to select, regardless of its location in the document.Prefix the name with two forward slashes (//).
      data = readtable('myFile.xml', 'VariableSelectors', '//var')
      data =
      
        4×1 table
      
          var
          ___
      
           1 
           2 
          10 
          20 
      Read the value of an attribute belonging to an element node.Prefix the attribute with an at sign (@).
      data = readtable('myFile.xml', 'VariableSelectors', '//table/@category')
      data =
      
        2×1 table
      
          categoryAttribute
          _________________
      
               "ones"      
               "tens"   
      Select a specific node in a set of nodes.Provide the index of the node you want to select in square brackets ([]).
      data = readtable('myFile.xml', 'TableSelector', '//table[1]')
      data =
      
        2×1 table
      
          var
          ___
      
           1 
           2 
      
      Specify precedence of operations.Add parentheses around the expression you want to evaluate first.
      data = readtable('myFile.xml', 'VariableSelectors', '//table/var[1]')
      data =
      
        2×1 table
      
          var
          ___
      
           1 
          10 
      data = readtable('myFile.xml', 'VariableSelectors', '(//table/var)[1]')
      data =
      
        table
      
          var
          ___
      
           1 

    See Also

    Introduced in R2020b