readstruct

Create structure from file

Since R2020b

Syntax

S = readstruct(filename)

S = readstruct(filename,Name,Value)

Description

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.

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

Create Structure from XML File

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]

Get Information on Elements in Non-Uniform Structure

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

Create Structure from Text File

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]

Specify Element Node to Read

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]

Select Structure Path

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

filename — Name of file to read

character vector | string scalar

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

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

FileType — Type of file

'auto' (default) | 'xml'

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'

DateLocale — Locale for reading dates

character vector | string scalar

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	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 — Starting XML element

character vector | string scalar

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'

StructSelector — Starting XML Path

character vector | string scalar

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.

ImportAttributes — Import attributes

logical 1 or true (default) | logical 0 or false

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

AttributeSuffix — Attribute suffix

'Attribute' (default) | character vector | string scalar

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'

RegisteredNamespaces — Set of registered XML namespace prefixes

string array

Set of registered XML namespace prefixes, specified as 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.

S = readstruct("example.xml",StructSelector="/myprefix:Data",...
RegisteredNamespaces=["myprefix", "https://www.mathworks.com"])

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

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

Output Arguments

S — Output structure

structure

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. This table provides the XPath syntaxes that are supported by the XPath selector name-value argument StructSelector.

  Selection Operation	Syntax	Example	Result
  Select the 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 = readstruct("music.xml",StructSelector="//Ensemble")	data = struct with fields: Music: "Jazz" BandName: "Kool Katz" Instrumentation: [1×1 struct]
  Select a specific node in a set of nodes.	Provide the index of the node you want to select in square brackets ([]).	data = readstruct("music.xml",... StructSelector=... "//Ensemble/Instrumentation/Instrument[3]")	data = struct with fields: typeAttribute: "percussion" Text: "Drums" drumkit: ["Bass drum" "Floor tom" "Snare drum"... "Hi-hat" "Ride cymbal"]
  Specify precedence of operations.	Add parentheses around the expression you want to evaluate first.	data = readstruct("students.xml",... StructSelector="//Student/Name[4]")	Error using readstruct No node with the selector '//Student/Name[4]' could be... found in the file 'students.xml'. 'StructSelector' must... refer to a valid node.
  		data = readstruct("students.xml",... StructSelector="(//Student/Name)[4]")	data = struct with fields: FirstNameAttribute: "Salim" LastNameAttribute: "Copeland"

Version History

Introduced in R2020b