Main Content

writestruct

Write structure array to file

Since R2020b

collapse all in page

    Syntax

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

    Description

    example

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

    example

    writestruct(S,filename,Name=Value) specifies options using one or more name-value 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

    Open Live Script

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

    Display the contents of the music.txt file.

    type music.txt
    <MusicalEnsemble>
    <Ensemble>
        <Music>Jazz</Music>
        <BandName>Kool Katz</BandName>
        <Instrumentation>
            <Instrument type="wind">Trumpet
            </Instrument>
            <Instrument type="percussion">Piano
                <pianotype>concert grand</pianotype>
            </Instrument>
            <Instrument type="percussion">Drums
                <drumkit>Bass drum</drumkit>
                <drumkit>Floor tom</drumkit>
                <drumkit>Snare drum</drumkit>
                <drumkit>Hi-hat</drumkit>
                <drumkit>Ride cymbal</drumkit>
            </Instrument>
            <Instrument type="string">Bass
                <basstype>upright</basstype>
            </Instrument>
        </Instrumentation>
    </Ensemble>
    <Musicians>
        <Name role="trumpeter">Miles</Name>
        <Name role="vocalist">Roger</Name>
        <Name role="pianist">Diana</Name>
        <Name role="drummer">George</Name>
        <Name role="bassist">John</Name>
    </Musicians>
</MusicalEnsemble>

    Import music.txt as a structure. Specify the FileType name-value argument as "xml" to read the contents as an XML file.

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

    Write the structure to an XML file. Display the contents of the XML 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="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>
    Open Live Script

    Import the file music.xml as a structure.

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

    Write the structure to an XML file. Name the root node JazzBand. Display the contents of the XML file.

    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>
    Open Live Script

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

    Import the file music.xml as a structure. 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 the output structure that have associated attributes 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 contains a field called Name with an associated attribute called role.

    contents = S.Musicians
    contents = struct with fields:
    Name: [1x5 struct]


    RolesNames = S.Musicians.Name
    RolesNames=1×5 struct array with fields:
    role_att
    Text

    Write the structure S to an XML file named band.xml and display its contents. The suffix "_att" is 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>

    Write the structure S to the XML file again, this time specifying the AttributeSuffix name-value argument 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".

    writestruct(S,"band.xml","AttributeSuffix","_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>
    Open Live Script

    Display the contents of the musicians.txt file.

    type musicians.txt
    {
    "Orchestra": {
        "Music": "classical",
        "Instruments": [
            {
                "Section": "string",
                "Musicians": 5
            },
            {
                "Section": "brass",
                "Musicians": 5
            },
            {
                "Section": "woodwind",
                "Musicians": NaN
            }
        ]
    },
    "Band": [
        {
            "Section": "guitar",
            "Musicians": 2
        },
        {
            "Section": "bass",
            "Musicians": NaN
        },
        {
            "Section": "drums",
            "Musicians": 1
        },
    ]
}

    Create a structure from musicians.txt. Parse the file as a JSON file.

    S = readstruct("musicians.txt",FileType="json");

    Write the structure S to musicians.json. Replace all NaN values with null values. 

    writestruct(S,"musicians.json",PreserveInfAndNaN=false)
type musicians.json
    {
    "Orchestra": {
        "Music": "classical",
        "Instruments": [
            {
                "Section": "string",
                "Musicians": 5.0
            },
            {
                "Section": "brass",
                "Musicians": 5.0
            },
            {
                "Section": "woodwind",
                "Musicians": null
            }
        ]
    },
    "Band": [
        {
            "Section": "guitar",
            "Musicians": 2.0
        },
        {
            "Section": "bass",
            "Musicians": null
        },
        {
            "Section": "drums",
            "Musicians": 1.0
        }
    ]
}

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

    When creating XML files, if a field in the input structure contains a missing value or NaN, writestruct writes the contents of the field as an empty string. When creating JSON files, writestruct writes missing values as null values and NaN values as null or NaN values depending on the PreserveInfAndNan name-value argument.

    Name of file to write, specified as a string scalar or character vector. 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 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"

    Example: "myFile.json"

    Other folders

    To write to a folder that is not the current folder, specify the full or relative pathname in filename.

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

    Example: "myFolder\myFile.xml"

    Example: "C:\myFolder\myFile.json"

    Example: "myFolder\myFile.json"

    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 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/myFile.xml"

    Example: "s3://bucketname/path_to_file/myFile.json"

    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.

    Example: writestruct(S,"myfile.xml",StructNodeName="RootName") specifies the name to use for the root node of the output XML file.

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

    Example: writestruct(S,"myfile.xml","StructNodeName","RootName") specifies the name to use for the root node of the output XML file.

    Type of file, specified as one of these values:

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

    • "json" — Export the contents of the structure as a JSON file, regardless of the file extension specified in filename. (since R2023b)

    If you specify a file extension in filename that is not .xml or .json, you can specify FileType as "xml" or "json" to write the contents of the input structure as XML or JSON, respectively.

    Example: FileType="xml"

    Since R2023b

    Indent text in the output file, specified as a numeric or logical 1 (true) or 0 (false). If you specify the value as true, then writestruct writes the XML or JSON text with an indentation of four spaces.

    Root node name of the output XML file, specified as a string scalar or character vector. If you do not specify StructNodeName, the default name of the root node is "struct".

    Example: StructNodeName="RootName"

    XML attribute suffix, specified as a string scalar or character vector. This suffix indicates which field names in the input structure to write as attributes in the output XML file.

    If the value of AttributeSuffix matches the suffix of an attribute name in the input structure, the suffix is dropped from the attribute name in the output XML file. For example, if you specify AttributeSuffix as "_att", a field in the input structure named MyField_att is written as an attribute named MyField in the XML file.

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

    Example: AttributeSuffix="_att"

    Since R2023b

    Preserve Inf and NaN values in the output JSON file, specified as a numeric or logical 1 (true) or 0 (false). Specify this argument as false to write all Inf and NaN values as JSON null values.

    Example: PreserveInfAndNaN=false

    Version History

    Introduced in R2020b

    expand all

    See Also