Main Content

readstruct

ファイルからの構造体の作成

R2020b 以降

    説明

    S = readstruct(filename) は、ファイルから構造化データを読み取り、構造体を作成します。入力ファイルには、適切にフォーマットされた XML 構造が含まれていなければなりません。

    readstruct は、入力ファイルの内容のデータ型を自動的に検出します。

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

    すべて折りたたむ

    XML ファイルを構造体として読み取り、構造体から変数を作成し、その内容をクエリします。

    ファイル music.xml の構造は以下のとおりです。

    music.png

    music.xml を、構造体 S として MATLAB に読み込みます。この構造体には、1 つの親ノード MusicalEnsemble があり、その親ノードは 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 をクエリし、その内容を表示します。

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

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

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

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

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

    music.png

    XML ファイル music.xml を構造体 S に読み込みます。

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

    S の Instrument 構造体をクエリし、その内容を表示します。

    S.Ensemble.Instrumentation.Instrument
    ans=1×4 struct array with fields:
        typeAttribute
        Text
        pianotype
        drumkit
        basstype
    
    

    テキスト ファイルを構造体として読み取ります。

    ファイル music.txt の構造は以下のとおりです。

    music.png

    テキスト ファイル music.txt を構造体 S として MATLAB® に読み取ります。'FileType''xml' として指定して、入力の内容を XML ファイルとして読み取ります。

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

    'StructNodeName' 名前と値のペアを使用して、入力ファイルに含まれる特定の要素ノードから構造体を作成します。

    XML ファイル music.xml から Instrumentation ノードを読み取ります。

    S = readstruct("music.xml","StructNodeName","Instrumentation")
    S = struct with fields:
        Instrument: [1x4 struct]
    
    

    入力ファイルの構造の読み取りを開始する XML 要素ノードを正確に指定します。

    XML ファイル music.xml の 5 番目の Name 要素を読み取ります。'StructSelector' の値として、要素ノードの完全な XPath 式を指定します。

    S = readstruct("music.xml","StructSelector","/MusicalEnsemble/Musicians/Name[5]")
    S = struct with fields:
        roleAttribute: "bassist"
                 Text: "John"
    
    

    名前と値の引数 RegisteredNamespaces を使用して、入力ファイルの既存の名前空間 URL にカスタムの 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"
    
    

    入力引数

    すべて折りたたむ

    読み取るファイルの名前。文字ベクトルまたは string スカラーとして指定します。

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

    場所

    形式

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

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

    例: 'myFile.xml'

    フォルダー内のファイル

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

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

    例: 'dataDir\myFile.xml'

    インターネット URL

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

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

    リモートの場所

    リモートの場所に保存されたファイルの場合、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'

    名前と値の引数

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

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

    例: 'ImportAttributes',true は、要素ノードに関連付けられている属性を、出力構造体のフィールドとしてインポートするよう指定します。

    ファイルの種類。'FileType' と次の値のいずれかで構成されるコンマ区切りのペアとして指定します。

    • 'auto'filename で指定された拡張子から、入力ファイルのファイル形式を自動的に検出します。

    • 'xml' — 入力ファイルの内容を XML として読み取ります。

    filename に含まれるファイル拡張子が .xml でない場合、'FileType' の値を 'xml' に指定することで、入力ファイルの内容を XML として読み取ることができます。

    例: 'FileType','xml'

    日付を読み取るロケール。'DateLocale' と、xx_YY の形式の文字ベクトルまたは string スカラーで構成されるコンマ区切りのペアとして指定します。ここで、次のようになります。

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

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

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

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

    例: 'DateLocale','ja_JP'

    開始 XML 要素。'StructNodeName' と、文字ベクトルまたは string スカラーのいずれかで構成されるコンマ区切りのペアとして指定します。readstruct は、入力ファイルの構造の読み取りを、指定した XML 要素から開始します。StructNodeName を指定しない場合、readstruct は構造の読み取りを XML ファイルのルートから開始します。

    readstruct は、名前が StructNodeName で指定した値に一致する XML 文書内の最初のノードに一致します。

    例: 'StructNodeName','RootName'

    開始 XML パス。'StructSelector' と、文字ベクトルまたは string スカラーのいずれかで構成されるコンマ区切りのペアとして指定します。readstruct は、入力ファイルの構造の読み取りを、指定したパスの要素から開始します。'StructSelctor' の値は、有効な XPath Version 1.0 の式でなければなりません。

    属性のインポート。'ImportAttributes' と、1 (true) または 0 (false) のいずれかで構成されるコンマ区切りのペアとして指定します。値を false に指定すると、readstruct は入力ファイル内の XML 属性を出力構造体のフィールドとしてインポートしません。

    例: 'ImportAttributes',false

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

    例: 'AttributeSuffix','_att'

    登録済みの XML 名前空間接頭辞のセット。RegisteredNamespaces と、接頭辞の配列として指定します。読み取り関数は、XML ファイルの XPath 式を評価する際にこれらの接頭辞を使用します。名前空間接頭辞とそれに関連付けられた URL を N 行 2 列の string 配列として指定します。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"]

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

    出力引数

    すべて折りたたむ

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

    ヒント

    • インポートする XML 入力文書の要素を指定するには、XPath セレクターを使用します。次の表は、XPath セレクターの名前と値の引数 StructSelector でサポートされている XPath 構文を示しています。

      選択操作構文結果
      文書内の位置に関係なく、選択するノードに名前が一致するノードを選択する。名前の前にスラッシュを 2 つ (//) 付ける。
      data = readstruct("music.xml",StructSelector="//Ensemble")
      data = 
      
        struct with fields:
      
                    Music: "Jazz"
                 BandName: "Kool Katz"
          Instrumentation: [1×1 struct]
      一連のノードから特定のノードを選択する。選択するノードのインデックスを大かっこ ([]) で囲んで指定する。
      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"]
      演算の優先順位を指定する。最初に評価する式を小かっこで囲む。
      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"

    バージョン履歴

    R2020b で導入