sprintf

データの文字列または文字ベクトルへの書式設定

構文

str = sprintf(formatSpec,A1,...,An)

[str,errmsg] = sprintf(formatSpec,A1,...,An)

str = sprintf(literalText)

説明

str = sprintf(formatSpec,A1,...,An) は、formatSpec で指定された書式演算子を使用して、配列 A1,...,An のデータを書式設定し、結果のテキストを str に返します。関数 sprintf は A1,...,An の値を列の順序で書式設定します。formatSpec が string の場合、出力 str も string となります。それ以外の場合、str は文字ベクトルです。

書式設定された複数のテキストを string 配列または文字ベクトルの cell 配列として返すには、関数 compose を使用します。

演算に失敗した場合、[str,errmsg] = sprintf(formatSpec,A1,...,An) はエラー メッセージを文字ベクトルとして返します。それ以外の場合、errmsg は空です。

str = sprintf(literalText) は literalText 内の \n や \t などのエスケープ文字シーケンスを変換します。その他すべての文字を変更せずに返します。literalText に書式演算子 (%f など) が含まれる場合、str はそれ以降のすべての文字を破棄します。

例

浮動小数点形式

%e、%f および %g 指定子を使用して、浮動小数点数を書式設定します。

A = 1/eps;
str_e = sprintf('%0.5e',A)

str_e = 
'4.50360e+15'

str_f = sprintf('%0.5f',A)

str_f = 
'4503599627370496.00000'

str_g = sprintf('%0.5g',A)

str_g = 
'4.5036e+15'

リテラル テキストと配列の入力

リテラル テキストと配列値を組み合わせて、文字ベクトルを作成します。

formatSpec = 'The array is %dx%d.';
A1 = 2;
A2 = 3;
str = sprintf(formatSpec,A1,A2)

str = 
'The array is 2x3.'

書式設定されたテキストを string 配列として指定

書式設定されたテキストを string として返すには、関数 sprintf を呼び出す際に formatSpec を文字ベクトルではなく string として指定します。

データを変換し、結果を string として返します。

formatSpec = "The current time is: %d:%d %s";
A1 = 11;
A2 = 20;
A3 = 'a.m.';
str = sprintf(formatSpec,A1,A2,A3)

str = 
"The current time is: 11:20 a.m."

入力 string を変換します。テキストを含む入力配列は文字ベクトルまたは string のいずれかにすることができます。

A1 = 2;
A2 = 35;
A3 = "p.m.";
str = sprintf(formatSpec,A1,A2,A3)

str = 
"The current time is: 2:35 p.m."

浮動小数点入力の整数形式

倍精度値を整数に明示的に変換します。

str = sprintf('%d',round(pi))

str = 
'3'

印刷値のフィールド幅の指定

印刷値の最大幅を指定します。

str = sprintf('%025d',123456)

str = 
'0000000000000000000123456'

%025d 書式指定子の 0 フラグは、出力で先頭にゼロを付加するよう要求します。

位置識別子 (n$) を使用した入力の並べ替え

n$ 位置識別子を使用して入力値を並べ替えます。

A1 = 'X';
A2 = 'Y';
A3 = 'Z';
formatSpec = ' %3$s %2$s %1$s';
str = sprintf(formatSpec,A1,A2,A3)

str = 
' Z Y X'

cell 配列の値から文字ベクトルを作成

C = { 1,   2,   3 ;
     'AA','BB','CC'};

str = sprintf(' %d %s',C{:})

str = 
' 1 AA 2 BB 3 CC'

構文 C{:} は、列順序で、C の各 cell の内容を含む配列のコンマ区切りリストを作成します。たとえば C{1}==1 および C{2}=='AA' などです。

入力引数

formatSpec — 出力フィールドの書式

書式演算子

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

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

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

書式演算子

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

変換文字

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

値のタイプ	変換	詳細
整数、符号付き	%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 例: sprintf('\x5A') は 'Z' を返す
  Unicode 数値を 8 進数 N で表現できる文字	\N 例: sprintf('\132') は 'Z' を返す

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

• 数値変換は複素数の実数部のみを出力します。

• 数値のテキスト変換など、データに適さない変換を指定すると、MATLAB^® は指定した変換をオーバーライドし、%e を使用します。

  例: '%s' は、pi を 3.141593e+00 に変換します。

• 整数値にテキスト変換 (%c または %s) を適用する場合、MATLAB は有効な文字コードに対応する値を文字に変換します。

  例: '%s' は、[65 66 67] を ABC に変換します。

A1,...,An — 数値、文字または string 配列

配列

数値、文字または string 配列。

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string

literalText — 書式演算子なしの入力テキスト

文字ベクトル | string スカラー

書式演算子なしの入力テキスト。文字ベクトルまたは string スカラーとして指定します。sprintf は literalText 内のエスケープ文字シーケンスをすべて変換します。

データ型: char | string

出力引数

str — 書式設定されたテキスト

文字ベクトル | string スカラー

書式設定されたテキスト。文字ベクトルまたは string スカラーとして返されます。出力の型は formatSpec の型と一致します。

errmsg — エラー メッセージ

文字ベクトル

エラー メッセージ。演算に失敗した場合に文字ベクトルとして返されます。それ以外の場合、errmsg は空です。

ヒント

• 関数 sprintf は fprintf と似ていますが、fprintf の場合はファイルに出力したりあるいはコマンド ウィンドウに表示したりします。

• 関数 sscanf および fscanf の読み取りに対する書式指定子は、関数 sprintf および fprintf の書き込み用の形式とは異なります。読み取り関数は精度フィールドをサポートしません。幅フィールドは、書き込み用には最小値を、読み取り用には最大値を指定します。

• 無効な書式演算子または特殊文字を指定すると、sprintf はその無効な演算子または文字までのすべてのテキストを出力し、残りを破棄します。

  例: formatSpec が 'value = %z' の場合、%z は書式演算子ではないため、sprintf は 'value =' を出力します。

  例: formatSpec が 'character \x99999 = %s' の場合、\x99999 は有効な特殊文字ではないため、sprintf は 'character' を出力します。

参照

[1] Kernighan, B. W., and D. M. Ritchie, The C Programming Language, Second Edition, Prentice-Hall, Inc., 1988.

[2] ANSI specification X3.159-1989: “Programming Language C,” ANSI, 1430 Broadway, New York, NY 10018.

拡張機能

C/C++ コード生成

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

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

• formatSpec パラメーターは定数でなければなりません。

• formatSpec では、16 進数は [0 7F]、8 進数は [0 177] の範囲になければなりません。

• すべての入力配列が定数の場合、コード ジェネレーターはコンパイル時に MATLAB での sprintf の呼び出しを評価します。この場合、sprintf のコード生成に関する制限は適用されません。また、生成されたコードでの sprintf の動作は、MATLAB での動作と同じです。

• 外部呼び出しができない場合、コード ジェネレーターは sprintf の C コードを生成します。外部呼び出しが無効になっている場合、または sprintf が parfor ループ内で呼び出された場合に外部呼び出しができません。

• 次のような場合、生成されたコードでの sprintf の動作は、MATLAB の動作ではなく C コンパイラの動作と一致します。

  • 書式指定子に %e や %E などの対応する C 書式指定子がある。

  • sprintf が parfor ループの内部で呼び出される。

  • 外部呼び出しが無効になっている。

• 次のオプションと機能はサポートされません。

  • 入力値を並べ替えるための n$ 位置識別子。

  • 配列の出力。

  • サブタイプを使用した、浮動小数点数の 8 進数、10 進数または 16 進数の値としての出力。

• 書式指定子 %s を指定して sprintf を呼び出す場合は、入力文字ベクトルの途中に null 文字を含めることはできません。null 文字を書き込むには、sprintf(fid, '%c', char(0)) を使用します。

• 入力引数の型は、書式の型と一致していなければなりません。たとえば、n が double の場合、コード生成で次のコードは許可されません。

  str = sprintf('%d',n)

  コード生成では、最初に n を int8 などの符号付き整数型にキャストします。

  str = sprintf('%d',int8(n))

• 整数の書式指定子を指定して sprintf を呼び出す場合、整数引数の型はターゲットのハードウェアがネイティブ C 型として表現できる型でなければなりません。たとえば、sprintf('%d', int64(n)) を呼び出す場合、ターゲットのハードウェアは 64 ビット整数をサポートするネイティブ C 型を備えていなければなりません。

• 動的メモリ割り当てを有効にしなければなりません。

スレッドベースの環境

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

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

GPU 配列

Parallel Computing Toolbox™ を使用してグラフィックス処理装置 (GPU) 上で実行することにより、コードを高速化します。

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

この関数は GPU 配列を受け入れますが、GPU 上では実行されません。

詳細については、GPU での MATLAB 関数の実行 (Parallel Computing Toolbox)を参照してください。

バージョン履歴

R2006a より前に導入

参考

char | fprintf | int2str | num2str | sscanf | fscanf | compose | string

トピック

• テキストの書式設定