assert_checkerror 命令が予測したエラーを発生することを確認する.

## 呼び出し手順

                flag = assert_checkerror ( instr , expectedmsg )
                flag = assert_checkerror ( instr , expectedmsg , expectederrnb )
                flag = assert_checkerror ( instr , expectedmsg , expectederrnb , a1, ... )
                [flag,errmsg] = assert_checkerror ( ... )

## パラメータ

instr:

  1行1列の文字列行列, 評価する式

expectedmsg :

  文字列または文字列ベクトル,生成するエラーメッセージ

expectederrnb :

  1行1列のdouble,整数値,エラー番号の行列 (デフォルト: expectederrnb=[]).

a1 :

  `msprintf` 関数に指定する, オプションのローカライズ用引数.

flag :

  1行1列の論理値行列,正しいエラーメッセージが生成された場合に %t , そうでない場合に %f

errmsg :

  1行1列の文字列行列で,エラーメッセージ. flag==%t の場合, errormsg==""となります. flag==%f の場合, errmsgにはエラーメッセージが出力されます.

## 説明

式がエラーを発生しない場合, `assert_checkerror` はエラーを発生します. 評価された式が予想されたエラーメッセージを生成する場合,そのまま実行されます.

エラーメッセージ`expectedmsg`が指定され, 空の行列 `[]`でない場合, 生成されたエラーメッセージが指定されたものに一致することが確認されます. エラー番号`expectederrnb`が指定され, 空の行列 `[]`でない場合, 生成されたエラー番号が指定されたものに一致することが確認されます. エラーメッセージ`expectedmsg`および エラー番号 `expectederrnb`を 同時に空の行列`[]`とすることはできません: 少なくとも一つを指定する必要があります.

文字列の一致では文字列が厳密に等しいことが確認されます: パターンまたは正規表現は使用できません.

エラーメッセージが予測値と異なるか,エラー番号が異なる場合,

- errmsg出力変数が指定されない場合,エラーが生成され,

- errmsg出力変数が指定される場合,エラーは生成されません.

この関数の目的は,簡単なフレームワークによりエラーのケースを 確認できるようにすることです. ある関数のエラーメッセージを確認することには以下のような利点があります:

- 必要な時に正しいエラーが生成されることを確認する,

- エラーメッセージが正しく整形されていることを確認する,

- エラーメッセージが正しくローカライズされていることを確認する.

予測されるメッセージをローカライズされたメッセージとすることができます. この場合,メッセージは`gettext`関数の出力と 比較され,ローカルな言語に依存します. オプション引数`a1`をこの目的, 例えばローカライズされたメッセージを整形するために,使用できます. 全てのオプション引数 `a1`, `a2`, ... は計算されたエラーメッセージと比較する前に自動的に `msprintf`関数に指定されます.

## 例

`assert_checkerror`関数を使用する複数の例を示します. まずテストする関数を定義する必要があります.

以下の関数`f`は, 入力引数の数が間違っているか`x`の型が間違っている 場合にエラーを発生します.

    function y = f(x)
        [lhs, rhs] = argn()
        if ( rhs <> 1 ) then
            lstr = gettext("%s: Wrong number of input argument: %d expected.\n")
            errmsg = msprintf ( lstr , "f" , 1 )
            error(errmsg)
        end
        if ( typeof(x) <> "constant" ) then
            lstr = gettext("%s: Wrong type for argument #%d: Matrix expected.\n")
            errmsg = msprintf ( lstr , "f" , 1 )
            error(errmsg,123456789)
        end
        y = x
    endfunction

我々のタスクは,この関数により生成されたエラーメッセージを確認することです. 以下の2つのテストをパスします: エラーメッセージが予測されたものである. ローカライズされたメッセージとオプションの パラメータ`"f"`(関数名)と `1`(入力引数の添字)のみを指定し, `assert_checkerror`がローカライズ化を管理するようにします. これらの2つのオプションパラメータは, メッセージを整形し, "%s" および "%d" フォーマットを実際の値に変換する際に使用されます.

    lcl1 = "%s: Wrong number of input argument: %d expected.\n";
    assert_checkerror ( "y = f()" , lcl1 , [] , "f" , 1);

    lcl2 = "%s: Wrong type for argument #%d: Matrix expected.\n";
    assert_checkerror ( "y = f(""a"")" , lcl2 , [] , "f" , 1);

ここで,カレントのロケール言語が英語であると仮定すると, 以下のコードを正しく使用できます. しかし,例えばカレントのロケールがフランス語である場合に失敗するため, これは推奨される手法ではありません.

    assert_checkerror ( "y = f()" , "f: Wrong number of input argument: 1 expected." );

以下のテストでは, エラー番号も確認します.

    lcl1="%s: Wrong number of input argument: %d expected.\n";
    assert_checkerror ( "y=f()" , lcl1 , 10000 , "f" , 1);

    lcl2 = "%s: Wrong type for argument #%d: Matrix expected.\n";
    assert_checkerror ( "y=f(""a"")" , lcl2 , 123456789 , "f" , 1);

以下の2つのテストは失敗します.

    assert_checkerror ( "y = f()" , "oups" );
    msg1 = msprintf(gettext("%s: Wrong number of input argument: %d expected.\n"), "f", 1);
    assert_checkerror ( "y = f()" , msg1 , 12 );

errmsgが出力引数に指定された場合,以下の例のように,エラーが生成されます. 変数`flag` および `errmsg`の内容に 注意してください.

    // パスするテスト: flag は %t, errmsg は空
    msg1 = msprintf(gettext("%s: Wrong number of input argument: %d expected.\n"), "f", 1);
    [flag, errmsg] = assert_checkerror ( "y = f()" , msg1 )
    // 失敗するテスト: flag は %f, errmsg は空でない
    [flag, errmsg] = assert_checkerror ( "y = f()" , "oups" )

以下の2つのテストのメッセージはローカライズされており, カレントの言語が何であっても動作します. オプションのパラメータ`a1`を使用する代わりに 長くはなりますが,完全に有効なコードである ローカライズされたメッセージを直接使用します.

    msg1 = msprintf(gettext("%s: Wrong number of input argument: %d expected.\n"), "f", 1);
    assert_checkerror ( "y = f()" , msg1 );
    msg2 = msprintf(gettext("%s: Wrong type for argument #%d: Matrix expected.\n"), "f", 1);
    assert_checkerror ( "y = f(""a"")" , msg2 );

エラー番号を確認したいがエラーメッセージは確認したくない場合がありえます. 以下のスクリプトは, 最初の引数が doubleの行列でない場合に 生成されるエラー番号が 123456789 であることのみを 確認します: エラーメッセージは確認しません.

    assert_checkerror("f(""foo"")", [], 123456789);

## 履歴

5.4.0 関数が導入されました