print

R2026a

プラグインによって生成されたテキストを出力ストリームに書き込む

構文

print(stream,formatSpec,A1,...,An)

説明

print(stream,formatSpec,A1,...,An) は、書式設定済みデータを出力 stream に書き込みます。このメソッドは、formatSpec 書式演算子を使用して、TestRunnerPlugin インスタンスなどのプラグインによって配列 A1,...,An で生成されたデータの書式を設定します。

プラグインによって生成されないデータについては、fprintf を使用してテキストファイルまたは画面にデータを書き込むか、sprintf を使用してデータを string または文字ベクトルとして書式設定します。

例

入力引数

すべて展開する

`stream` — プラグインがテキスト出力を送信する場所
`OutputStream` インスタンス

プラグインがテキスト出力を送る場所。OutputStream インスタンスとして指定します。

`formatSpec` — 出力フィールドの書式
書式演算子

出力フィールドの書式。書式演算子を使用して指定します。formatSpec には通常のテキストおよび特殊文字を含めることもできます。

formatSpec に \n などのエスケープ文字を表すリテラルテキストが含まれる場合、print はエスケープ文字を変換します。

formatSpec は一重引用符で囲まれた文字ベクトルか、または string スカラーとすることができます。

書式演算子

書式演算子はパーセント記号 % で始まり、変換文字で終わります。変換文字は必須です。オプションとして、% と変換文字の間に識別子、フラグ、フィールド幅、精度およびサブタイプ演算子を指定できます (ここでは読みやすいようにスペースが表示されていますが、実際には演算子の間にスペースは使用できません)。

Schematic of formatting operator characters.

変換文字

次の表では、数値データおよび文字データをテキストとして書式設定するための変換文字を説明します。

値のタイプ	変換	詳細
整数、符号付き	`%d` または `%i`	基数 10
整数、符号なし	`%u`	基数 10
	`%o`	基数 8 (8 進法)
	`%x`	基数 16 (16 進法)、小文字 `a`–`f`
	`%X`	`%x` と同じ、大文字 `A`–`F`
浮動小数点数	`%f`	固定小数点表記 (小数点以下の桁数の指定には精度演算子を使用)
	`%e`	`3.141593e+00` などの指数表現 (小数点以下の桁数の指定には精度演算子を使用)
	`%E`	`%e` と同じだが、`3.141593E+00` のように大文字 (小数点以下の桁数の指定には精度演算子を使用)
	`%g`	`%e` または `%f` をコンパクトにしたもので、後続のゼロなし (有効桁数の指定には精度演算子を使用)
	`%G`	`%E` または `%f` をコンパクトにしたもので、後続のゼロなし (有効桁数の指定には精度演算子を使用)
文字または文字列	`%c`	単一の文字
文字または文字列	`%s`	文字ベクトルまたは string 配列。出力テキストのタイプは `formatSpec` のタイプと同じです。

オプションの演算子

オプションの識別子、フラグ、フィールド幅、精度およびサブタイプ演算子は、出力テキストの書式をさらに細かく定義します。

識別子
関数の入力引数の処理順序。構文 n$ を使用します。ここで、n は関数呼び出し内の他の入力引数の位置を表します。
例: ('%3$s %2$s %1$s %2$s','A','B','C') は入力引数 'A'、'B'、'C' を C B A B として出力します。
メモ: 入力引数が配列の場合、識別子を使用してその入力引数の特定の配列要素を指定することはできません。

フラグ

`'–'`	左揃えにします。例: `%-5.2f` 例: `%-10s`
`'+'`	常に数値の符号文字 (+ または –) を出力します。例: `%+5.2f` テキストを右揃えにします。例: `%+10s`
`' '`	値の前にスペースを 1 つ挿入します。例: `% 5.2f`
`'0'`	値の前にゼロを入れてフィールド幅をパディングします。例: `%05.2f`
`'#'`	選択した数値変換を次のように変更します。 `%o`、`%x`、または `%X` の場合は、接頭辞 `0`、`0x`、または `0X` を出力します。 `%f`、`%e`、または `%E` の場合は、精度が 0 であっても小数点を出力します。 `%g` または `%G` の場合は、後続のゼロまたは小数点を削除しないでください。例: `%#5.0f`

フィールド幅
出力する最小文字数。フィールド幅演算子は、数字、あるいは入力引数を参照するアスタリスク (*) にすることができます。
フィールド幅演算子として * を指定する場合、他の入力引数は出力される幅と値の両方を提供しなければなりません。幅と値は引数のペア、または数値配列内のペアにすることができます。フィールド幅演算子として * を使用すると、さまざまな値をさまざまな幅で出力できます。
例: 入力引数 ('%12d',intmax) は ('%*d',12,intmax) と等価です。
例: 入力引数 ('%*d',[2 10 5 100]) は '10 100' を返します。このとき、10 には 2 つのスペース、100 には 5 つのスペースが割り当てられます。あるいは、フィールドの幅と値を ('%*d',2,10,5,100) のように複数の引数として指定することもできます。
フラグで特に指定されていない限り、この関数は値の前にスペースを追加してフィールド幅までパディングします。
精度
%f、%e または %E
小数点以下の桁数
例: '%.4f' は pi を '3.1416' と出力します
%g または %G
有効桁数
例: '%.4g' は pi を '3.142' と出力します。
精度演算子は、数字、あるいは引数を参照するアスタリスク (*) にすることができます。
フィールド精度演算子として * を指定する場合、他の入力引数は出力される精度と値の両方を提供しなければなりません。精度と値は引数のペア、または数値配列内のペアにすることができます。精度演算子として * を使用すると、さまざまな値をさまざまな精度で出力できます。
フィールド幅と精度演算子として *.* を指定する場合、フィールド幅、精度、値を 3 成分として指定しなければなりません。
例: 入力引数 ('%.4f',pi) は ('%.*f',4,pi) と等価です。
例: 入力引数 ('%6.4f',pi) は ('%*.*f',6,4,pi) と等価です。
例: 入力引数 ('%*.*f',6,4,pi,9,6,exp(1)) は、'3.1416 2.718282' を返します。ここで、9 および 6 は exp(1) の出力のフィールド幅と精度です。
メモ
浮動小数点値の精度演算子を入力の数値データ型の精度より大きい値に指定すると、入力値の精度が指定の精度にならない場合があります。結果はコンピューターのハードウェアとオペレーティングシステムによって異なります。

サブタイプ

サブタイプ演算子を使用して、浮動小数点値を 8 進数、10 進数または 16 進数の値として出力できます。サブタイプ演算子は、変換文字の直前に指定します。次の表では、サブタイプを使用できる変換を示します。

入力値の型	サブタイプと変換文字	出力値の型
浮動小数点数	`%bx` または `%bX` `%bo` `%bu`	16 進数、8 進数または 10 進数の倍精度値例: `%bx` は `pi` を `400921fb54442d18` と出力します
浮動小数点数	`%tx` または `%tX` `%to` `%tu`	16 進数、8 進数または 10 進数の単精度値例: `%tx` は `pi` を `40490fdb` と出力します

書式演算子の前後のテキスト

formatSpec では、パーセント記号 % の前や、変換文字の後に追加のテキストを含めることができます。次のテキストを追加できます。

出力する通常のテキスト。

通常のテキストとして入力できない特殊文字。次の表では、formatSpec で特殊文字を表す方法を説明します。

特殊文字	表現
一重引用符	`''`
パーセント文字	`%%`
バックスラッシュ	`\\`
アラーム	`\a`
バックスペース	`\b`
フォームフィード	`\f`
改行	`\n`
キャリッジリターン	`\r`
水平タブ	`\t`
垂直タブ	`\v`
Unicode^® 数値を 16 進数 `N` で表現できる文字	`\xN` 例: `print('\x5A')` は `'Z'` を返す
Unicode 数値を 8 進数 `N` で表現できる文字	`\N` 例: `print('\132')` は `'Z'` を返す

書式演算子を使用した変換動作の注意点

テキスト変換に非整数の数値を指定するなど、変換に適さない値を指定すると、指定した変換が MATLAB^® でオーバーライドされることがあります。
例: '%s' は、pi を 3.141593e+00 に変換します。
整数値にテキスト変換 (%c または %s) を適用する場合、MATLAB は有効な文字コードに対応する値を文字に変換します。
例: '%s' は、[65 66 67] を ABC に変換します。

`A1,...,An` — 表示データ
配列

表示データ。数値、文字または string 配列として指定します。

属性

Abstract true

メソッドの属性の詳細については、メソッドの属性を参照してください。

例

すべて展開する

カスタム出力ストリームの作成

現在のフォルダーにあるファイルで、プラグイン出力を Figure にリダイレクトする ToFigure という名前のクラスを作成し、それを Figure 内のリストボックスに表示します。Figure およびリストボックスへのハンドルをそれぞれ表す Figure プロパティと ListBox プロパティを定義します。

classdef ToFigure < matlab.automation.streams.OutputStream
    
    properties(SetAccess = private)
        Figure
    end
    properties(Access = private)
        ListBox
    end

OutputStream のすべてのサブクラスに print メソッドを実装しなければなりません。この例では、メソッドが新規 Figure を作成し (必要な場合)、受信したテキストを書式設定した後、それを出力ストリームに追加します。

    methods
        function print(stream,formatSpec,varargin)
            % Create the figure
            if isempty(stream.Figure) || ~ishghandle(stream.Figure)
                stream.createFigure
            end
            newStr = sprintf(formatSpec,varargin{:});
            oldStr = strjoin(stream.ListBox.String','\n');
            
            % Create the full message
            fullStr = strjoin([oldStr,newStr]);
            fullStrArray = strsplit(fullStr,'\n','CollapseDelimiters',false);
            
            % Set the string and selection
            stream.ListBox.String = fullStrArray';
            stream.ListBox.Value = numel(fullStrArray);
            drawnow
        end
    end

private にアクセスできる methods ブロックで、プラグインによって使用される Figure およびリストボックスを作成する createFigure という名前のヘルパーメソッドを実装します。

    methods(Access = private)
        function createFigure(stream)
            stream.Figure = figure(...
                'Name',         'Unit Test Output',...
                'WindowStyle',  'docked');
            
            stream.ListBox = uicontrol(...
                'Parent',       stream.Figure,...
                'Style',        'listbox',...
                'String',       {},...
                'Units',        'normalized',...
                'Position',     [.05 .05 .9 .9],...
                'Max',          2, ...
                'FontName',     'Monospaced',...
                'FontSize',     13);
        end
    end
end

ToFigure クラスを保存します。次に、現在のフォルダーで、以下のテストクラスを含む ExampleTest.m という名前のファイルを作成します。testOne の verifyEqual 検定がテストエラーの原因です。testTwo での検証はパスします。testThree に対応するテストは、出力を生成せずにパスします。

classdef ExampleTest < matlab.unittest.TestCase
    methods(Test)
        function testOne(testCase)  % Test fails
            testCase.verifyEqual(5,4,'Testing 5==4');
        end
        function testTwo(testCase)  % Test passes
            testCase.verifyEqual(5,5,'Testing 5==5');
        end
        function testThree(testCase)
            % test code
        end
    end
end

コマンドプロンプトで ExampleTest クラスからテストスイートを作成します。

import matlab.unittest.TestRunner
import matlab.unittest.plugins.DiagnosticsValidationPlugin

suite = testsuite('ExampleTest');

出力をコマンドウィンドウに表示するテストランナーを作成します。

runner = TestRunner.withTextOutput;

DiagnosticsValidationPlugin インスタンスを作成して、その出力が ToFigure 出力ストリームを使用して Figure に送信されるよう明示的に指定します。

plugin = DiagnosticsValidationPlugin(ToFigure);

プラグインをランナーに追加して、テストを実行します。

runner.addPlugin(plugin)
result = runner.run(suite);

Running ExampleTest

================================================================================
Verification failed in ExampleTest/testOne.
    ----------------
    Test Diagnostic:
    ----------------
    Testing 5==4
    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyEqual failed.
    --> The numeric values are not equal using "isequaln".
    --> Failure table:
            Actual    Expected    Error    RelativeError
            ______    ________    _____    _____________
                                                        
              5          4          1          0.25     
    
    Actual Value:
         5
    Expected Value:
         4
    ------------------
    Stack Information:
    ------------------
    In C:\work\ExampleTest.m (ExampleTest.testOne) at 4
================================================================================
...
Done ExampleTest
__________

Failure Summary:

     Name                 Failed  Incomplete  Reason(s)
    ==================================================================
     ExampleTest/testOne    X                 Failed by verification.

テストの失敗時のみ画面に出力が生成されます。既定で、TestRunner.withTextOutput は DiagnosticsOutputPlugin を使用して画面に出力を表示します。

画面上に表示される既定のテキスト出力に加え、DiagnosticsValidationPlugin の出力がドッキング状態の Figure に送信されます。Figure は、このテストを示します。

------------------------------
Validation of Test Diagnostic:
------------------------------
Testing 5==4
------------------------------
Validation of Test Diagnostic:
------------------------------
Testing 5==5

テストでエラー条件が発生するかどうかにかかわらず、DiagnosticsValidationPlugin は診断情報を表示します。

バージョン履歴

R2014a で導入

参考

fprintf | sprintf

トピック

テキストの書式設定

`%f`、`%e` または `%E`	小数点以下の桁数例: `'%.4f'` は `pi` を `'3.1416'` と出力します
`%g` または `%G`	有効桁数例: `'%.4g'` は `pi` を `'3.142'` と出力します。