Main Content

readstruct

ファイルから構造体配列を作成する

R2020b 以降

    説明

    S = readstruct(filename) は指定したファイルからデータを読み取って構造体配列を作成します。入力ファイルには、適切にフォーマットされた XML または JSON テキストが含まれている必要があります。readstruct は入力ファイルの内容のデータ型を自動的に検出します。

    S = readstruct(filename,Name,Value) は、1 つ以上の名前と値の引数を使用してオプションを指定します。たとえば、filename のファイル拡張子が .xml でないときに、S = readstruct(filename,FileType="xml") を呼び出すことによって、入力ファイルの内容を XML として読み取ることができます。

    すべて折りたたむ

    XML ファイルの内容を構造体としてインポートし、構造体から変数を作成し、その内容をクエリします。

    ファイル music.xml の内容を表示します。

    type music.xml
    <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>
    

    music.xml を構造体として MATLAB® にインポートします。この構造体には、MusicalEnsemble という名前の 1 つの親ノードがあり、その親ノードは 2 つの兄弟ノード EnsembleMusicians をもちます。

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

    1 つ目の兄弟ノードから変数 band を作成します。band には 3 つのフィールドがあり、その 1 つは、Instrumentation という名前の構造体です。

    band = S.Ensemble
    band = struct with fields:
                  Music: "Jazz"
               BandName: "Kool Katz"
        Instrumentation: [1x1 struct]
    
    

    bandInstrumentation をクエリし、その内容を表示します。

    ins = band.Instrumentation
    ins = struct with fields:
        Instrument: [1x4 struct]
    
    

    2 つ目の兄弟ノードから変数 musicians を作成します。musicians は、Name という名前の 1 つのフィールドをもち、その中に 5 つの構造体が含まれます。

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

    テキスト ファイルの内容を構造体としてインポートします。

    ファイル music.info の内容を表示します。

    type music.info
    <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>
    

    music.info を構造体として MATLAB にインポートします。名前と値の引数 FileType を "xml" として指定して、内容を XML ファイルとして読み取ります。

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

    R2023b 以降

    JSON ファイルの内容を構造体としてインポートし、構造体から変数を作成し、その内容をクエリします。

    ファイル music.json の内容を表示します。

    type music.json
    {
        "Ensemble": {
            "Music": "jazz",
            "BandName": "Kool Katz",
            "Instrumentation": [
                {
                    "Type": "wind",
                    "Instrument": "trumpet",
                },
                {
                    "Type": "percussion",
                    "Instrument": "piano",
                    "Pianotype": "concert grand",
                },
                {
                    "Type": "percussion",
                    "Instrument": "drums",
                    "Drumkit": [
                        "bass drum",
                        "floor tom",
                        "snare drum",
                        "hi-hat",
                        "ride cymbal"
                    ],
                },
                {
                    "Type": "string",
                    "Instrument": "bass",
                    "Basstype": "upright"
                }
            ]
        },
        "Musicians": [
            {
                "Role": "trumpeter",
                "Name": "Miles"
            },
            {
                "Role": "vocalist",
                "Name": "Roger"
            },
            {
                "Role": "pianist",
                "Name": "Diana"
            },
            {
                "Role": "drummer",
                "Name": "George"
            },
            {
                "Role": "bassist",
                "Name": "John"
            }
        ]
    }
    

    music.json を構造体として MATLAB にインポートします。この構造体には、Ensemble および Musicians という名前の 2 つの兄弟ノードが含まれています。

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

    1 つ目の兄弟ノードから変数 band を作成します。band には 3 つのフィールドがあり、その 1 つは、Instrumentation という名前の構造体配列です。

    band = S.Ensemble
    band = struct with fields:
                  Music: "jazz"
               BandName: "Kool Katz"
        Instrumentation: [1x4 struct]
    
    

    bandInstrumentation をクエリし、その内容を表示します。

    ins = band.Instrumentation
    ins=1×4 struct array with fields:
        Type
        Instrument
        Pianotype
        Drumkit
        Basstype
    
    

    2 つ目の兄弟ノードから変数 musicians を作成します。

    musicians = S.Musicians
    musicians=1×5 struct array with fields:
        Role
        Name
    
    

    一様に構造化されたデータを含まないファイルから構造体を作成し、その内容を表示します。

    ある兄弟ノードに、他の兄弟ノードには存在しないフィールドがある場合、readstruct は、他のノードで見つからないフィールドに対して missing を返します。たとえば、ファイル music.json で、Instrumentation の 2 つ目のノードには、Pianotype という名前の空でないフィールドが含まれます。兄弟ノードは Pianotype に指定された値をもたないため、readstruct は、それらのノード下の Pianotype に対して missing を返します。

    type music.json
    {
        "Ensemble": {
            "Music": "jazz",
            "BandName": "Kool Katz",
            "Instrumentation": [
                {
                    "Type": "wind",
                    "Instrument": "trumpet",
                },
                {
                    "Type": "percussion",
                    "Instrument": "piano",
                    "Pianotype": "concert grand",
                },
                {
                    "Type": "percussion",
                    "Instrument": "drums",
                    "Drumkit": [
                        "bass drum",
                        "floor tom",
                        "snare drum",
                        "hi-hat",
                        "ride cymbal"
                    ],
                },
                {
                    "Type": "string",
                    "Instrument": "bass",
                    "Basstype": "upright"
                }
            ]
        },
        "Musicians": [
            {
                "Role": "trumpeter",
                "Name": "Miles"
            },
            {
                "Role": "vocalist",
                "Name": "Roger"
            },
            {
                "Role": "pianist",
                "Name": "Diana"
            },
            {
                "Role": "drummer",
                "Name": "George"
            },
            {
                "Role": "bassist",
                "Name": "John"
            }
        ]
    }
    

    music.json を構造体としてインポートします。

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

    SPianotype 構造体をクエリし、その内容を変数に代入します。

    [ins1,ins2,ins3,ins4] = S.Ensemble.Instrumentation.Pianotype
    ins1 = missing
        <missing>
    
    
    ins2 = 
    "concert grand"
    
    ins3 = missing
        <missing>
    
    
    ins4 = missing
        <missing>
    
    

    名前と値の引数 RegisteredNamespaces を使用して、入力ファイルの既存の名前空間 URL にカスタムの XML 名前空間接頭辞を登録します。

    students.xml ファイルの 2 つ目の Street 要素ノードを構造体として読み取るには、名前と値の引数 StructSelector を "//Student[2]/Address/myPrefix:Street" として指定します。RegisteredNamespaces["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"
    
    

    R2023b 以降

    JSON 標準に厳格に準拠するが、解析時に末尾のコンマを許可して、JSON ファイルから構造体を作成します。

    S = readstruct("music.json",ParsingMode="strict",AllowTrailingCommas=true)
    S = struct with fields:
         Ensemble: [1x1 struct]
        Musicians: [1x5 struct]
    
    

    入力引数

    すべて折りたたむ

    読み取るファイルの名前。string スカラーまたは文字ベクトルとして指定します。ファイル タイプは、ファイル拡張子または名前と値の引数 FileType によって判別されます。拡張子が .xml または .json のファイルはそれぞれ XML または JSON (R2023b 以降) ファイルとして解釈されます。一方、その他のファイル拡張子の場合は、名前と値の引数 FileType を指定する必要があります。

    ファイルの場所に応じて、filename は次の形式のいずれかをとります。

    場所

    形式

    現在のフォルダー、または MATLAB® パス上のフォルダー

    ファイル名を filename で指定します。

    例: "myFile.xml"

    例: "myFile.json"

    フォルダー内のファイル

    ファイルが現在のフォルダーまたは MATLAB パス上のフォルダーにない場合は、filename に絶対パス名または相対パス名を指定します。

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

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

    例: "dataDir\myFile.xml"

    例: "dataDir\myFile.json"

    インターネット URL

    ファイルをインターネットの Uniform Resource Locator (URL) として指定する場合、filename には "http://" または "https://" のプロトコル タイプが含まれていなければなりません。

    例: "http://hostname/path_to_file/my_data.xml"

    例: "http://hostname/path_to_file/my_data.json"

    リモートの場所

    リモートの場所に保存されたファイルの場合、filename は次の形式で指定されたファイルの絶対パスを含まなければなりません。

    scheme_name://path_to_file/my_file.ext

    リモートの場所に基づいて、scheme_name には次の表の値のいずれかを指定できます。

    リモートの場所scheme_name
    Amazon S3™s3
    Windows Azure® Blob Storagewasb, wasbs
    HDFS™hdfs

    詳細については、リモート データの操作を参照してください。

    例: "s3://bucketname/path_to_file/my_setup.xml"

    例: "s3://bucketname/path_to_file/my_setup.json"

    名前と値の引数

    引数のオプションのペアを Name1=Value1,...,NameN=ValueN として指定します。ここで Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後になければなりませんが、ペアの順序は重要ではありません。

    例: readstruct("myfile.xml",DateLocale="en_US") は日付に en-US ロケールを使用して myfile.xml からデータをインポートします。

    R2021a より前では、コンマを使用してそれぞれの名前と値を区切り、Name を引用符で囲みます。

    例: readstruct("myfile.xml","DateLocale","en_US") は日付に en-US ロケールを使用して myfile.xml からデータをインポートします。

    ファイル情報

    すべて折りたたむ

    ファイルのタイプ。次の値のいずれかとして指定します。

    • "xml"filename で指定されているファイル拡張子に関係なく、入力ファイルの内容を XML として読み取ります。

    • "json"filename で指定されているファイル拡張子に関係なく、入力ファイルの内容を JSON として読み取ります。 (R2023b 以降)

    .xml でも .json でもないファイル拡張子を filename で指定した場合、FileType"xml" または "json" として指定して、入力ファイルの内容をそれぞれ XML または JSON として読み取ることができます。

    例: FileType="xml"

    日付を読み取るロケール。形式 xx_YY の string スカラーまたは文字ベクトルとして指定します。

    • xx は言語を表す小文字 2 文字の ISO 639-1 コード

    • YY は国を表す大文字の ISO 3166-1 alpha-2 コード

    次の表に一般的なロケールの値を示します。

    ロケール 言語
    "de_DE"ドイツ語ドイツ
    "en_GB"英語英国
    "en_US"英語米国
    "es_ES"スペイン語スペイン
    "fr_FR"フランス語フランス
    "it_IT"イタリア語イタリア
    "ja_JP"日本語日本
    "ko_KR"韓国語韓国
    "nl_NL"オランダ語オランダ
    "zh_CN"簡体字中国語中国

    例: DateLocale="ja_JP"

    開始要素の名前。string スカラーまたは文字ベクトルとして指定します。読み取り始める位置を決定するために、readstruct は、StructNodeName で指定した値に一致する名前をもつ最初のノードをファイル内で検索します。readstruct は入力ファイルの内容をそのノードから読み取り始めます。StructNodeName を指定しなかった場合、readstruct は内容の読み取りをファイルのルートから開始します。

    例: StructNodeName="RootName"

    例: StructNodeName="Instrumentation"

    開始 XML パスまたは JSON ポインター。string スカラーまたは文字ベクトルとして指定します。readstruct は、入力ファイルの内容の読み取りを、指定した XML パスまたは JSON ポインターの要素から開始します。

    XML ファイルの場合、StructSelector の値は、有効な XPath Version 1.0 の式でなければなりません。XML パスは以下の構文を使用して指定できます。

    XML 選択操作構文
    文書内の位置に関係なく、名前でノードを選択する。名前の前にスラッシュを 2 つ (//) 付ける。
    S = readstruct("music.xml",StructSelector="//Ensemble")
    一連のノードから特定のノードをインデックスで選択する。ノードのインデックスを大かっこ ([]) で囲んで指定する。
    S = readstruct("music.xml", ...
            StructSelector= ...
            "//Ensemble/Instrumentation/Instrument[3]")
    演算の優先順位を指定する。最初に評価する式を小かっこで囲む。
    S = readstruct("students.xml", ...
            StructSelector="//Student/Name[4]")
    S = readstruct("students.xml", ...
            StructSelector="(//Student/Name)[4]")

    JSON ポインターは以下の構文を使用して指定できます。

    JSON 選択操作構文
    名前で JSON オブジェクト キーを選択する。名前の前にスラッシュを 1 つ (/) 付ける。
    S = readstruct("music.json",StructSelector="/Musicians")
    JSON 配列要素をインデックスで選択する。スラッシュ 1 つ (/) の後にノードのインデックスを指定する。このインデックスは 0 ベース。
    S = readstruct("music.json", ...
             StructSelector="/Musicians/4")

    HTTP または HTTPS 要求オプション。weboptions オブジェクトとして指定します。weboptions オブジェクトは、指定した filename がプロトコル タイプ "http://" または "https://" を含むインターネット URL である場合にデータをインポートする方式を決定します。

    XML の属性

    すべて折りたたむ

    属性のインポート。数値または logical 1 (true) または 0 (false) として指定します。値を false に指定すると、readstruct は入力ファイル内の XML 属性を出力構造体のフィールドとしてインポートしません。

    例: ImportAttributes=false

    属性接尾辞。string スカラーまたは文字ベクトルとして指定します。readstruct は、この接尾辞を入力 XML ファイルに含まれる属性に対応する出力構造体のすべてのフィールド名に付加します。AttributeSuffix を指定しない場合、readstruct は既定で接尾辞 "Attribute" を入力 XML ファイルに含まれる属性に対応するすべてのフィールド名に付加します。

    例: AttributeSuffix="_att"

    登録済みの XML 名前空間接頭辞のセット。接頭辞の string 行列として指定します。読み取り関数は、XML ファイルの XPath 式を評価する際にこれらの接頭辞を使用します。名前空間接頭辞とそれに関連付けられた URL を N 行 2 列の string 行列として指定します。ここで、N は名前空間接頭辞と URL のペアの数です。RegisteredNamespaces は、readstructStructSelectorreadtablereadtimetableVariableSelectors など、セレクターの名前と値の引数で指定された XPath 式も評価する場合に使用できます。

    既定では、読み取り関数は XPath の評価に使用する名前空間接頭辞を自動的に検出して登録しますが、名前と値の引数 RegisteredNamespaces を使用して新しい名前空間接頭辞を登録することもできます。新しい名前空間接頭辞の登録は、名前空間 URL がある XML ノードについて、XML ファイルで名前空間接頭辞が宣言されていない場合などに便利です。

    たとえば、名前空間接頭辞が含まれていない example.xml という名前の XML ファイルの XPath 式を評価するとします。RegisteredNamespaces["myprefix","https://www.mathworks.com"] と指定して、接頭辞 "myprefix" を URL https://www.mathworks.com に割り当てます。

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

    例: RegisteredNamespaces=["myprefix","https://www.mathworks.com"]

    JSON 標準

    すべて折りたたむ

    R2023b 以降

    解析時に JSON 標準にどれだけ厳格に準拠するか。次の値のいずれかとして指定します。

    R2023b 以降

    入力ファイルでコメントを許可するかどうか。次のいずれかの値として指定します。

    • 数値または logical 1 (true) (既定の設定) – インポート時にコメントはエラーになりません。ファイル内のコメントはデータとみなされず、MATLAB に読み取られません。コメントは、単一行のコメントの場合は「//」で開始できます。複数行のコメントの場合は、「/*」で開始し、「*/」で終了することができます。

    • 数値または logical 0 (false) – インポート時にコメントはエラーになります。

    R2023b 以降

    入力ファイル内の Inf および NaN リテラルを読み取るかどうか。次のいずれかの値として指定します。

    • 数値または logical 1 (true) (既定の設定) – Inf および NaN リテラル (Infinity-Inf-Infinity を含む) は MATLAB に読み取られます。

    • 数値または logical 0 (false) – インポート時に Inf および NaN リテラルはエラーになります。

    R2023b 以降

    入力ファイル内の末尾のコンマを読み取るかどうか。次のいずれかの値として指定します。

    • 数値または logical 1 (true) (既定の設定) – インポート時に JSON 配列または JSON オブジェクトの後の末尾のコンマはエラーになりません。

    • 数値または logical 0 (false) – インポート時に末尾のコンマはエラーになります。

    出力引数

    すべて折りたたむ

    出力構造体。MATLAB 構造体として返されます。構造体は、フィールドと呼ばれるデータ コンテナーを使って、関連するデータをグループとしてまとめるデータ型です。各フィールドには任意のデータ型を含めることができます。structName.fieldName の形式のドット表記を使用して、構造体内のデータにアクセスします。構造体の詳細については、struct を参照してください。

    拡張機能

    バージョン履歴

    R2020b で導入

    すべて展開する