テキストの書式設定

データをテキストに変換して書式を制御するには、"書式演算子" を、num2str や sprintf などの一般的な変換関数とともに使用できます。これらの演算子は、表記、配置、有効桁数などを制御します。C プログラミング言語で関数 printf が使用する演算子と類似しています。書式設定されたテキストの一般的な用途には、表示ファイルや出力ファイルのテキストが含まれます。

たとえば、%f は、固定小数点表記を使用して、浮動小数点値をテキストに変換します。演算子に情報を追加して書式を調整します。たとえば、小数点以下 2 桁を表す %.2f や、出力が 12 文字で、必要に応じて空白でパディングすることを表す %12f などです。

A = pi*ones(1,3);
txt = sprintf('%f | %.2f | %12f', A)

txt = 
'3.141593 | 3.14 |     3.141593'

"書式指定子" で、演算子を通常のテキストや特殊文字と組み合わせることができます。たとえば、\n は改行文字を挿入します。

txt = sprintf('Displaying pi: \n %f \n %.2f \n %12f', A)

txt = 
    'Displaying pi: 
      3.141593 
      3.14 
          3.141593'

書式演算子をサポートする関数は、compose、num2str、sprintf、fprintf と、エラー処理関数 assert、error、warning および MException です。

書式演算子のフィールド

図に示すように、書式演算子は 6 つのフィールドをもつことができます。右から左の順に、変換文字、サブタイプ、精度、フィールド幅、フラグ、数値識別子のフィールドです (演算子では空白文字は許可されていません。ここでは、図を理解しやすくするためにスペースを使用しています)。変換文字が唯一の必須フィールドで、先頭に % 文字を付ける必要があります。

Schematic of formatting operator characters.

変換文字

変換文字は、出力の表記法を指定します。変換文字は 1 文字で構成され、書式指定子の最後に配置されます。

指定子	説明
`c`	単一の文字。
`d`	10 進数表記 (符号付き)。
`e`	指数表記 (`3.1415e+00` のように小文字の `e` を使用)。
`E`	指数表記 (`3.1415E+00` のように大文字の `E` を使用)。
`f`	固定小数点表記。
`g`	`%e` または `%f` をさらにコンパクトに表現 (不要なゼロは非表示)。
`G`	`%g` と同様で、大文字 `E` を使用。
`o`	8 進法表記 (符号なし)。
`s`	文字ベクトルまたは string 配列。
`u`	10 進数表記 (符号なし)。
`x`	16 進数表記 (符号なし、小文字 `a` ～ `f` を使用)。
`X`	16 進数表記 (符号なし、大文字 `A` ～ `F` を使用)。

たとえば、数値 46 を、さまざまな変換文字を使用して書式設定し、数値を 10 進数、固定小数点、指数、16 進数の各書式で表示します。

A = 46*ones(1,4);
txt = sprintf('%d   %f   %e   %X', A)

txt = 
'46   46.000000   4.600000e+01   2E'

サブタイプ

サブタイプフィールドは、変換文字の直前にあるアルファベット 1 文字です。サブタイプフィールドがない場合、変換文字 %o、%x、%X および %u は、入力データを整数として扱います。入力データを浮動小数点値として扱い、8 進数、10 進数、16 進数のいずれかの表現に変換するには、次のいずれかのサブタイプ指定子を使用します。

`b`	入力データが符号なし整数ではなく倍精度の浮動小数点値の場合。たとえば、倍精度値を 16 進数で出力するには、`%bx` のような形式を使用します。
`t`	入力データが符号なし整数ではなく単精度の浮動小数点値の場合。

精度

書式演算子の精度フィールドはピリオドの直後に続く非負の整数です。たとえば、演算子 %7.3f では、精度は 3 です。%g 演算子の場合、精度は表示する有効桁数を示します。%f、%e、%E の各演算子については、精度は小数点の右側に表示する桁数を示します。

精度フィールドを使用して、さまざまな精度で数値を表示します。

txt = sprintf('%g   %.2g   %f   %.2f', pi*50*ones(1,4))

txt =

    '157.08   1.6e+02   157.079633   157.08'

入力テキストの書式演算子 (たとえば %s 演算子) で精度を指定できますが、通常はそうする理由はありません。精度を p と指定し、p が入力テキストの文字数より小さい場合、出力には最初の p 個の文字のみが含まれます。

フィールド幅

書式演算子のフィールド幅は、入力値を書式設定するときに出力の桁数または文字数を指定する非負の整数です。たとえば、演算子 %7.3f では、フィールド幅は 7 です。

別のフィールド幅を指定します。各出力の幅を表示するには、| 文字を使用します。既定では、フィールド幅が文字数より大きい場合、出力テキストは空白文字でパディングされます。

txt = sprintf('|%e|%15e|%f|%15f|', pi*50*ones(1,4))

txt =

    '|1.570796e+02|   1.570796e+02|157.079633|     157.079633|'

テキスト入力で使用する場合、フィールド幅によって、出力テキストに空白をパディングするかどうかを決定できます。フィールド幅が入力テキスト内の文字数以下の場合は、変化はありません。

txt = sprintf('%30s', 'Pad left with spaces')

txt =

    '          Pad left with spaces'

フラグ

オプションのフラグは、出力テキストの追加の書式設定を制御します。次の表で、フラグとして使用できる文字について説明します。

文字	説明	例
マイナス記号 (`-`)	変換された引数をフィールド内で左揃えします。	`%-5.2d`
プラス記号 (`+`)	数値の場合は、常に先頭の符号文字 (`+` または `-`) を表示します。テキスト値の場合は、変換された引数をフィールド内で右揃えします。	`%+5.2d` `%+5s`
スペース	値の前にスペースを 1 個挿入します。	`% 5.2f`
ゼロ (`0`)	空白ではなくゼロでパディングします。	`%05.2f`
シャープ記号 (`#`)	選択した数値変換を次のように変更します。 `%o`、`%x`、または `%X` の場合は、接頭辞 `0`、`0x`、または `0X` を出力します。 `%f`、`%e`、または `%E` の場合は、精度が 0 であっても小数点を出力します。 `%g` または `%G` の場合は、後続のゼロまたは小数点を削除しません。	`%#5.0f`

出力を右揃え、または左揃えします。既定の動作では、出力テキストを右揃えします。

txt = sprintf('right-justify: %12.2f\nleft-justify: %-12.2f',...
              12.3, 12.3)

txt =

    'right-justify:        12.30
     left-justify: 12.30       '

正の数に対して + 符号を表示します。既定の動作では、正の数値の場合は先頭の + 符号を省略します。

txt = sprintf('no sign: %12.2f\nsign: %+12.2f',...
              12.3, 12.3)

txt =

    'no sign:        12.30
     sign:       +12.30'

左に空白およびゼロを付け加えます。既定の動作では、空白をパディングします。

txt = sprintf('Pad with spaces: %12.2f\nPad with zeroes: %012.2f',...
              5.2, 5.2)

txt =

    'Pad with spaces:         5.20
     Pad with zeroes: 000000005.20'

メモ

書式演算子では複数のフラグを指定できます。

値識別子

既定では、sprintf のような関数は、入力引数から出力テキストへ、シーケンス順で値を挿入します。シーケンス順以外で入力引数を処理するには、書式指定子で数値識別子を使用して順序を指定します。シーケンス順ではない引数を指定するには、% 記号、整数、$ 記号を続けて使用します。

演算子のシーケンスに従う場合	識別子で順序を決める場合
sprintf('%s %s %s',... '1st','2nd','3rd') ans = '1st 2nd 3rd'	sprintf('%3$s %2$s %1$s',... '1st','2nd','3rd') ans = '3rd 2nd 1st'

特殊文字

特殊文字を出力テキストの一部とすることができます。ただし、通常のテキストとしては入力できないので、これらの文字を表すには特定の文字列が必要です。出力テキストに特殊文字を挿入するには、次の表に示すいずれかの文字列を使用します。

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

フィールド幅と精度の設定

書式演算子は、出力テキストを指定したフィールド幅と精度に書式設定するための一連のルールに従います。書式指定子の外でフィールド幅や精度の値を指定し、番号付き識別子をフィールド幅や精度で使用することもできます。

精度およびフィールド幅の書式設定のルール

次の図は、フィールド幅と精度の設定が書式設定関数の出力にどのように影響するかを説明しています。この図では、書式演算子の % 記号に続くゼロは、出力テキストの先頭に空白文字ではなくゼロを付加することを意味します。

Flowchart relating input value, Format operator, and output text.

精度が指定されないと、既定では 6 になります。
精度 p が入力値の小数部分の桁数より小さい場合、小数点以下 p 桁のみが表示されます。出力では、小数値は丸められます。
精度 p が入力値の小数部分の桁数 f より大きい場合は、小数点以下 p 桁が表示されます。小数部分は右に拡大し、出力には p-f 個のゼロが付加されます。
フィールド幅が指定されないと、既定では p+1+n (n は入力値の整数部分の桁数) になります。
フィールド幅 w が p+1+n より大きい場合は、出力値の整数部分の左側に w-(p+1+n) 個の追加文字がパディングされます。追加文字は、書式演算子に 0 フラグが含まれていない場合は空白文字です。このフラグが含まれている場合は、追加文字はゼロとなります。

書式指定子の外でのフィールド幅と精度の指定

シーケンス順の引数リストからの値を使用してフィールド幅と精度を指定できます。書式演算子のフィールド幅または精度のフィールドの代わりにアスタリスク (*) を使用します。

例として、3 つの数値を書式設定して表示します。どの場合も、アスタリスクを使用して、フィールド幅または精度が、書式指定子の後に続く入力引数から取得されることを指定します。

txt = sprintf('%*f   %.*f   %*.*f',...
              15,123.45678,...     
              3,16.42837,...       
              6,4,pi)

txt =

    '     123.456780   16.428   3.1416'

次の表は、例に挙げたそれぞれの書式演算子の効果について説明しています。

書式演算子	説明
`%*f`	後に続く入力引数 `15` で幅を指定します。
`%.*f`	後に続く入力引数 `3` で精度を指定します。
`%.f`	後に続く入力引数 `6` および `4` で幅と精度を指定します。

2 つの書式を組み合わせて使用できます。たとえば、後に続く入力引数からフィールド幅を、書式指定子から精度を取得します。

txt = sprintf('%*.2f', 5, 123.45678)

txt =

    '123.46'

幅と精度のフィールドでの番号付き識別子の指定

次の図に示す代替の構文を使用して、シーケンス順ではない引数リストからの値としてフィールド幅と精度を指定することもできます。書式演算子内で、番号付き識別子と $ 記号の後にアスタリスクを使用してフィールド幅と精度を指定します。書式指定子の後に入力引数を使用して、フィールド幅と精度の値を指定します。

Schematic of formatting operator characters.

例として、3 つの数値を書式設定して表示します。どの場合も、番号付き識別子を使用して、フィールド幅または精度が、書式指定子の後に続く入力引数から取得されることを指定します。

txt = sprintf('%1$*4$f   %2$.*5$f   %3$*6$.*7$f',...
              123.45678, 16.42837, pi, 15, 3, 6, 4)

txt =

    '     123.456780   16.428   3.1416'

次の表は、例に挙げたそれぞれの書式演算子の効果について説明しています。

書式演算子	説明
`%1$*4$f`	`1$` は、最初の入力引数 `123.45678` を値として指定します。
`%1$*4$f`	`*4$` は、4 番目の入力引数 `15` をフィールド幅として指定します。
`%2$.*5$f`	`2$` は、2 番目の入力引数 `16.42837` を値として指定します。
`%2$.*5$f`	`.*5$` は、5 番目の入力引数 `3` を精度として指定します。
`%3$6$.7$f`	`3$` は、3 番目の入力引数 `pi` を値として指定します。
	`*6$` は、6 番目の入力引数 `6` をフィールド幅として指定します。
	`.*7$` は、7 番目の入力引数 `4` を精度として指定します。

識別子を使用する場合の制限

いずれかの書式演算子に識別子フィールドが含まれている場合は、書式指定子のすべての演算子に識別子フィールドを含めなければなりません。同じ関数呼び出しでシーケンス順を使用するものとそうでないものの両方を使用する場合、シーケンス順の識別子とシーケンス順でない識別子が最初に切り替わる位置で出力が切り捨てられます。

有効な構文	無効な構文
sprintf('%d %d %d %d',... 1,2,3,4) ans = '1 2 3 4'	sprintf('%d %3$d %d %d',... 1,2,3,4) ans = '1 '

関数呼び出しで指定する入力引数の数が、書式指定子内の書式演算子の数より多い場合、演算子は再利用されます。ただし、シーケンス順を使用する関数呼び出しのみが、書式演算子を再利用します。番号付き識別子を使用する場合は、書式演算子を再利用できません。

有効な構文	無効な構文
sprintf('%d',1,2,3,4) ans = '1234'	sprintf('%1$d',1,2,3,4) ans = '1'

入力データがベクトルまたは配列である場合に番号付き識別子を使用した場合、出力には書式設定されたデータは含まれません。

有効な構文	無効な構文
v = [1.4 2.7 3.1]; sprintf('%.4f %.4f %.4f',v) ans = '1.4000 2.7000 3.1000'	v = [1.4 2.7 3.1]; sprintf('%3$.4f %1$.4f %2$.4f',v) ans = 1×0 empty char array