structfun

スカラー構造体の各フィールドに関数を適用

構文

A = structfun(func,S)

A = structfun(func,S,Name,Value)

[A1,...,Am] = structfun(___)

説明

A = structfun(func,S) は、関数 func をスカラー構造体 S の各フィールドに適用します。次に、structfun は func からの出力を列ベクトル A に連結します。入力引数 func は関数ハンドルであり、この関数は 1 つの入力引数を取ってスカラーを返します。この構文を使用するには、func からの出力が常に同じデータ型でなければなりません。関数の出力のデータ型が異なる場合は、名前と値の引数 UniformOutput を false に設定する必要があります。A における要素の数は、S 内のフィールドの数と等しくなります。

structfun での A の要素の計算順序を指定したり、特定の順序で計算される要素に依存することはできません。

A = structfun(func,S,Name,Value) は、1 つ以上の Name,Value のペアの引数で指定された追加オプションを使って func を適用します。たとえば、出力値を構造体で返すには、'UniformOutput',false を指定します。func が配列に連結できない値を返す場合に、A を構造体として返すことができます。返された構造体には、S と同じフィールドがあります。

[A1,...,Am] = structfun(___) は、func が m 個の出力値を返す場合に、複数の出力配列 A1,...,Am を返します。func は異なるデータ型の出力引数を返すことができますが、func の呼び出しごとに各出力のデータ型は同じでなければなりません。この構文では、前述の構文の入力引数のいずれかを使用できます。

例

構造体のフィールドに関数を適用

異なるサイズの数値配列を含むフィールドをもつスカラー構造体を作成します。

S.f1 = 1:10;
S.f2 = [2; 4; 6];
S.f3 = []

S = struct with fields:
    f1: [1 2 3 4 5 6 7 8 9 10]
    f2: [3×1 double]
    f3: []

各数値配列の平均値を計算し、その平均値を配列で返します。

A = structfun(@mean,S)

A = 3×1

    5.5000
    4.0000
       NaN

オブジェクト配列を返す

各フィールドに乱数の配列を含むスカラー構造体を作成します。

S.X = rand(1,10);
S.Y = rand(1,10);
S.Z = rand(1,10)

S = struct with fields:
    X: [0.8147 0.9058 0.1270 0.9134 0.6324 0.0975 0.2785 0.5469 0.9575 0.9649]
    Y: [0.1576 0.9706 0.9572 0.4854 0.8003 0.1419 0.4218 0.9157 0.7922 0.9595]
    Z: [0.6557 0.0357 0.8491 0.9340 0.6787 0.7577 0.7431 0.3922 0.6555 0.1712]

配列をプロットします。関数 plot から chart line オブジェクトの配列を返し、これらを使用して各データ点セットに異なるマーカーを追加します。structfun は、そのデータ型のオブジェクトが連結できる限り、任意のデータ型の配列を返すことができます。

figure
hold on
p = structfun(@plot,S);
p(1).Marker = 'o';
p(2).Marker = '+';
p(3).Marker = 's';
hold off

スカラー構造体を返す

フィールドに行列を含むスカラー構造体を作成します。

S.f1 = 1:10;
S.f2 = [2 3; 4 5; 6 7];
S.f3 = rand(4,4)

S = struct with fields:
    f1: [1 2 3 4 5 6 7 8 9 10]
    f2: [3×2 double]
    f3: [4×4 double]

各行列の平均値を計算します。mean は各列の平均値を含むベクトルを返すため、平均値を配列として返すことはできません。構造体の平均値を返すには、'UniformOutput',false の名前と値のペアを指定します。

A = structfun(@mean,S,'UniformOutput',false)

A = struct with fields:
    f1: 5.5000
    f2: [4 5]
    f3: [0.6902 0.3888 0.7627 0.5962]

複数の出力配列を返す

スカラー構造体を作成します。

S.f1 = 1:10;
S.f2 = [2 3; 4 5; 6 7];
S.f3 = rand(4,4)

S = struct with fields:
    f1: [1 2 3 4 5 6 7 8 9 10]
    f2: [3×2 double]
    f3: [4×4 double]

S 内の各配列のサイズを計算します。行数と列数は、それぞれ 3 行 1 列の数値配列です。

[nrows,ncols] = structfun(@size,S)

nrows = 3×1

     1
     3
     4

ncols = 3×1

    10
     2
     4

入力引数

func — 適用する関数

関数ハンドル

入力スカラー構造体のフィールドに適用する関数。関数ハンドルとして指定します。

func は複数の関数ファイルに対応できるため、オーバーロードされた関数セットを表すことができます。このような場合、MATLAB^® は入力引数のクラスに基づいて呼び出す関数を決定します。

例: A = structfun(@max,S) は、S の各フィールドの最大値を返します。

S — 入力構造体

スカラー構造体

入力構造体。スカラー構造体として指定します。

名前と値の引数

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

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

例: A = structfun(@mean,S,'UniformOutput',false) は、mean からの出力を S と同じフィールドをもつ構造体に返します。

UniformOutput — true または false

true (既定値) | false

true または false。'UniformOutput' と、true (1) または false (0) のいずれかで構成されるコンマ区切りのペアとして指定します。

'UniformOutput' の値	説明
true (1)	func は、structfun が列ベクトルに連結するスカラーを返さなければなりません。func の出力は同じデータ型でなければならず、そうでない場合、このオプションを使用すると structfun はエラーになります。
false (0)	structfun は、func の出力を 1 つ以上のスカラー構造体に返します。出力スカラー構造体には、入力スカラー構造体と同じフィールドがあります。func の出力は、任意のデータ型にすることができます。

ErrorHandler — エラーをキャッチする関数

関数ハンドル

エラーをキャッチする関数。'ErrorHandler' と関数ハンドルで構成されるコンマ区切りのペアとして指定します。func がエラーをスローした場合、'ErrorHandler' で指定されたエラー ハンドラーがエラーをキャッチし、その関数に指定されたアクションを実行します。エラー ハンドラーはエラーをスローするか、または func と同じ出力数を返さなければなりません。'UniformOutput' の値が true の場合、エラー ハンドラーの出力引数は func の出力と同じデータ型のスカラーでなければなりません。

エラー ハンドラーの最初の入力引数は、次のフィールドをもつ構造体です。

• identifier — エラー識別子

• message — エラー メッセージ テキスト

• index — func がエラーをスローした入力配列の線形インデックス

エラー ハンドラーの残りの入力引数は、func がエラーをスローした原因である func の呼び出しの入力引数です。

func が出力引数として 2 つの double 型を返すと仮定します。エラー ハンドラーを 'ErrorHandler',@errorFunc として指定できます。ここで、errorFunc は警告を発行して 2 つの出力引数を返す関数です。

function [A,B] = errorFunc(S,varargin)
    warning(S.identifier, S.message); 
    A = NaN; 
    B = NaN;
end

'ErrorHandler' を指定しない場合、structfun は func がスローしたエラーを再スローします。

出力引数

A — 出力配列

任意のデータ型の列ベクトル | スカラー構造体

出力配列。任意のデータ型の列ベクトルまたはスカラー構造体として返されます。

既定では、structfun は func からの出力を列ベクトルに連結します。func はスカラーを返さなければなりません。func がオブジェクトを返す場合、そのオブジェクトが属するクラスは次の要件を満たさなければなりません。

• オブジェクト配列の線形インデックス付けによる代入をサポートする

• 入力と同じサイズをもつ配列を返す reshape メソッドをもつ

名前と値のペアの引数 'UniformOutput' の値が false (0) の場合、structfun は出力をスカラー構造体のフィールドとして返します。その場合、func の出力は任意のサイズと異なるデータ型をもつことができます。

拡張機能

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用上の注意および制限:

• ErrorHandler オプションはサポートされていません。

• 出力の数は 3 以下でなければなりません。

スレッドベースの環境

MATLAB® の backgroundPool を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の ThreadPool を使用してコードを高速化します。

この関数はスレッドベースの環境を完全にサポートしています。詳細については、スレッドベースの環境での MATLAB 関数の実行を参照してください。

バージョン履歴

R2006a より前に導入

参考

cellfun | arrayfun | cell2mat | spfun | splitapply

トピック

• 無名関数
• 関数ハンドルの作成