writestruct

Write structure to file

Since R2020b

Syntax

writestruct(S,filename)

writestruct(S,filename,Name,Value)

Description

writestruct(S,filename) writes a structure to a file with the name and extension specified by filename. The writestruct function automatically writes the input structure to an XML file when .xml is specified as the file extension in filename.

writestruct(S,filename,Name,Value) writes a structure to a file with additional options specified by one or more name-value pair arguments. For example, you can export the contents of the input structure as an XML file regardless of the file extension specified in filename by calling writestruct(filename,"FileType","xml").

Examples

Write Structure to XML File

Create a structure from a text file that contains an XML structure, then write it to an XML file.

The file music.txt has the following structure.

Read the text file music.txt 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]

Write S to the XML file named band.xml. Display the contents of band.xml.

writestruct(S,"band.xml")
type band.xml

<?xml version="1.0" encoding="UTF-8"?>
<struct>
    <Ensemble>
        <Music>Jazz</Music>
        <BandName>Kool Katz</BandName>
        <Instrumentation>
            <Instrument type="wind">
                <Text>Trumpet</Text>
            </Instrument>
            <Instrument type="percussion">
                <Text>Piano</Text>
            </Instrument>
            <Instrument type="percussion">
                <Text>Drums</Text>
            </Instrument>
            <Instrument type="string">
                <Text>Bass</Text>
            </Instrument>
            <pianotype>concert grand</pianotype>
            <drumkit>Bass drum</drumkit>
            <drumkit>Floor tom</drumkit>
            <drumkit>Snare drum</drumkit>
            <drumkit>Hi-hat</drumkit>
            <drumkit>Ride cymbal</drumkit>
            <basstype>upright</basstype>
        </Instrumentation>
    </Ensemble>
    <Musicians>
        <Name role="trumpeter">
            <Text>Miles</Text>
        </Name>
        <Name role="vocalist">
            <Text>Roger</Text>
        </Name>
        <Name role="pianist">
            <Text>Diana</Text>
        </Name>
        <Name role="drummer">
            <Text>George</Text>
        </Name>
        <Name role="bassist">
            <Text>John</Text>
        </Name>
    </Musicians>
</struct>

Specify Root Node in Output File

Read the file music.xml as a structure S.

S = readstruct("music.xml")

S = struct with fields:
     Ensemble: [1x1 struct]
    Musicians: [1x1 struct]

Write S to the XML file named band.xml. Name the root node JazzBand. Display the contents of band.xml.

writestruct(S,"band.xml","StructNodeName","JazzBand")
type band.xml

<?xml version="1.0" encoding="UTF-8"?>
<JazzBand>
    <Ensemble>
        <Music>Jazz</Music>
        <BandName>Kool Katz</BandName>
        <Instrumentation>
            <Instrument type="wind">
                <Text>Trumpet</Text>
            </Instrument>
            <Instrument type="percussion">
                <Text>Piano</Text>
                <pianotype>concert grand</pianotype>
            </Instrument>
            <Instrument type="percussion">
                <Text>Drums</Text>
                <drumkit>Bass drum</drumkit>
                <drumkit>Floor tom</drumkit>
                <drumkit>Snare drum</drumkit>
                <drumkit>Hi-hat</drumkit>
                <drumkit>Ride cymbal</drumkit>
            </Instrument>
            <Instrument type="string">
                <Text>Bass</Text>
                <basstype>upright</basstype>
            </Instrument>
        </Instrumentation>
    </Ensemble>
    <Musicians>
        <Name role="trumpeter">
            <Text>Miles</Text>
        </Name>
        <Name role="vocalist">
            <Text>Roger</Text>
        </Name>
        <Name role="pianist">
            <Text>Diana</Text>
        </Name>
        <Name role="drummer">
            <Text>George</Text>
        </Name>
        <Name role="bassist">
            <Text>John</Text>
        </Name>
    </Musicians>
</JazzBand>

Specify Attribute Suffix

Specify the field names in the input structure to write as attributes in the output XML file.

Read the file music.xml as a structure S. Append the suffix "_att" to the field names of the output structure that correspond to attributes in the input XML file.

S = readstruct("music.xml", "AttributeSuffix", "_att")

S = struct with fields:
     Ensemble: [1x1 struct]
    Musicians: [1x1 struct]

All elements in S that have associated attributes will have the suffix "_att" appended to the attribute names.

Query the field Musicians to view its contents. Musicians is a structure that contains five structures, each of which contain a field called Name with an associated attribute called role.

S.Musicians.Name

ans=1×5 struct array with fields:
    role_att
    Text

Write S to the XML file named band.xml and display its contents. The suffix "_att" has been appended to the attribute names in the file.

writestruct(S,"band.xml")
type band.xml

<?xml version="1.0" encoding="UTF-8"?>
<struct>
    <Ensemble>
        <Music>Jazz</Music>
        <BandName>Kool Katz</BandName>
        <Instrumentation>
            <Instrument>
                <type_att>wind</type_att>
                <Text>Trumpet</Text>
            </Instrument>
            <Instrument>
                <type_att>percussion</type_att>
                <Text>Piano</Text>
                <pianotype>concert grand</pianotype>
            </Instrument>
            <Instrument>
                <type_att>percussion</type_att>
                <Text>Drums</Text>
                <drumkit>Bass drum</drumkit>
                <drumkit>Floor tom</drumkit>
                <drumkit>Snare drum</drumkit>
                <drumkit>Hi-hat</drumkit>
                <drumkit>Ride cymbal</drumkit>
            </Instrument>
            <Instrument>
                <type_att>string</type_att>
                <Text>Bass</Text>
                <basstype>upright</basstype>
            </Instrument>
        </Instrumentation>
    </Ensemble>
    <Musicians>
        <Name>
            <role_att>trumpeter</role_att>
            <Text>Miles</Text>
        </Name>
        <Name>
            <role_att>vocalist</role_att>
            <Text>Roger</Text>
        </Name>
        <Name>
            <role_att>pianist</role_att>
            <Text>Diana</Text>
        </Name>
        <Name>
            <role_att>drummer</role_att>
            <Text>George</Text>
        </Name>
        <Name>
            <role_att>bassist</role_att>
            <Text>John</Text>
        </Name>
    </Musicians>
</struct>

writestruct(S,"band.xml","AttributeSuffix","_att")

Write the structure S to the XML file again, this time specifying the value of "AttributeSuffix" as "_att" to indicate which field names in the input structure to write as attributes. Display the contents of band.xml. The attributes in band.xml do not have the suffix "_att".

type band.xml

<?xml version="1.0" encoding="UTF-8"?>
<struct>
    <Ensemble>
        <Music>Jazz</Music>
        <BandName>Kool Katz</BandName>
        <Instrumentation>
            <Instrument type="wind">
                <Text>Trumpet</Text>
            </Instrument>
            <Instrument type="percussion">
                <Text>Piano</Text>
                <pianotype>concert grand</pianotype>
            </Instrument>
            <Instrument type="percussion">
                <Text>Drums</Text>
                <drumkit>Bass drum</drumkit>
                <drumkit>Floor tom</drumkit>
                <drumkit>Snare drum</drumkit>
                <drumkit>Hi-hat</drumkit>
                <drumkit>Ride cymbal</drumkit>
            </Instrument>
            <Instrument type="string">
                <Text>Bass</Text>
                <basstype>upright</basstype>
            </Instrument>
        </Instrumentation>
    </Ensemble>
    <Musicians>
        <Name role="trumpeter">
            <Text>Miles</Text>
        </Name>
        <Name role="vocalist">
            <Text>Roger</Text>
        </Name>
        <Name role="pianist">
            <Text>Diana</Text>
        </Name>
        <Name role="drummer">
            <Text>George</Text>
        </Name>
        <Name role="bassist">
            <Text>John</Text>
        </Name>
    </Musicians>
</struct>

Input Arguments

S — Input structure

MATLAB^® structure

Input structure, specified as a MATLAB structure. A structure is a data type that groups related data using data containers called fields.

If a field in the input structure contains a missing value or NaN, writestruct will write the contents of the field as an empty string.

For more information on structures, see struct.

filename — File name

character vector | string scalar

File name to write to, specified as a character vector or string scalar. If filename does not exist, then the writing function creates the file. If filename is the name of an existing file, then the writing function overwrites it.

Depending on the location you are writing to, filename can take on one of these forms.

Location	Form
Current folder	To write to the current folder, specify the name of the file in filename. Example: 'myFile.xml'
Other folders	To write to a folder different from the current folder, specify the full or relative path name in filename. Example: 'C:\myFolder\myFile.xml' Example: 'myFolder\myFile.xml'
Remote Location	To write to a remote location, 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 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/myFile.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: 'StructNodeName','RootName' specifies the name to use for the root node of the output XML file.

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 to write from the extension specified in filename.

• 'xml' — Export the contents of the structure as an XML file, regardless of the file extension specified in filename.

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

Example: 'FileType','xml'

StructNodeName — Root node name of output XML file

character vector | string scalar

Root node name of output XML file, specified as the comma-separated pair consisting of 'StructNodeName' and either a character vector or string scalar containing the name of the root node to be used in the output. If you do not specify StructNodeName, the default name of the root node is "struct".

Example: 'StructNodeName','RootName'

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 indicating which field names in the input structure to write as attributes in the output XML file.

For example, for a field name AttName_att in the input structure, you can specify 'AttributeSuffix','_att' to indicate that 'AttName' should be written out as an attribute in the output XML file.

• If you do not specify 'AttributeSuffix', writestruct defaults to writing fields with the suffix 'Attribute' as attributes in the output XML file.

• If the attribute specified as the value of 'AttributeSuffix' matches the suffix appended to the attribute name in the input structure, the suffix will be dropped from the attribute name in the output XML file. For example, if you specify 'AttributeSuffix','_att', a field in the input structure named MyField_att will correspond to the attribute named MyField in the XML file.

Example: 'AttributeSuffix','_att'

Version History

Introduced in R2020b