Main Content

writestruct

Write structure to file

    Description

    example

    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.

    example

    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

    collapse all

    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>
    

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

    collapse all

    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.

    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 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/myFile.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: 'StructNodeName','RootName' specifies the name to use for the root node of the output XML file.

    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'

    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'

    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'

    See Also

    Introduced in R2020b