sprintf


書式付き出力を行います。

[所属]

標準ライブラリ

[指定形式]

#include <stdio.h>

int sprintf(char *s, const char *format[, arg, ...]);

[戻り値]

出力された文字(null文字(\0)は除きます)の数を返します。

エラー・リターンはありません。

[詳細説明]

それぞれのargformatの指す文字列で指定された書式を適用し,それにより出力された書式付きデータをsの指す配列に書き出します。

書式に対して引数が十分にない場合,動作は不定です。書式文字列の終わりに到達するとリターンします。書式で必要としている以上に引数がある場合,余分の引数を無視します。また,sの領域が引数の1つと重なっていると動作は不定になります。

formatは,“後ろに続く引数がどのような出力に変換されるか”を指定しています。書き込まれた文字の最後にはnull文字(\0)が付加されます(null文字(\0)は返り値におけるカウントの対象とはなりません)。

formatは,次に示す2種類のディレクティブにより構成されます。

通常文字

変換されずにそのまま出力にコピーされるものです(“%”以外)。

変換指示

0個以上の引数を取り込み,指示を与えるものです。

 

各変換指示は,文字“%”で始まります(出力中に“%”を入れたい場合は,書式文字列の中では“%%”とします)。“%”の後ろは,次のようになります。

 

%[フラグ][フィールド長][精度][サイズ][型指定文字]

 

それぞれの変換指示について,次に説明します。

(1)

フラグ

任意の順に置かれた,変換指示の意味を修飾する0個以上のフラグです。フラグ文字とその意味を次に示します。

-

変換された結果をフィールド中に左詰めにし,右側は空白で満たされます(このフラグが指定されない場合,変換された結果は右詰めにされます)。

+

符号付きの変換の結果を常に+符号,または-符号で始めます(このフラグが指定されない場合,変換された結果は,負の値が変換された場合にのみ符号で始められます)。

スペース

符号付きの変換の最初の文字が符号でない場合,または符号付きの変換が文字を生じない場合,その結果の前にスペース(“ ”)を付けます。スペース・フラグと+フラグとが両方現れる場合,スペース・フラグは無視されます。

#

結果を“別の形式注1”に変換します。o変換に対しては,その変換結果の最初の数字が0になるようにその精度を増やします。x,またはX変換に対しては,0以外の変換結果の先頭に0x,または0Xを付加します。e,f,g,E,G変換に対しては,その変換結果に小数点以下の数字が存在しない場合であっても,小数点“.”を付加します注2。g,G変換に対しては,変換結果から後ろに続く0が削除されないようにします。これら以外の変換に対しては,その動作は不定となります。

0

d,e,f,g,i,o,u,x,E,G,X変換に対し,フィールド長を埋めるために,符号,または基底の指示に続いて0を付加します。

0フラグと-フラグの両方が指定された場合,0フラグは無視されます。d,i,o,u,x,X変換については,精度を指定している場合,ゼロ(0)フラグを無視します。

0はフラグとして解釈され,フィールド幅の始まりとは解釈されないことに注意してください。

これら以外の変換に対してはその動作は不定となります。

注 1.

alternate formatのことです。

注 2.

通常,小数点は,その後ろに数字が続く場合にのみ現れます。

(2)

フィールド長

オプショナルな最小フィールド長です。変換された値がこのフィールド長より小さい場合,左側にスペースが詰められます(前述の左詰めフラグが与えられた場合は右側にスペースが詰められます)。このフィールド長は“*”,または10進整数の形を取ります。“*”で指定した場合,int型の引数をフィールド長として使用します。負のフィールド長は,サポートしていません。負のフィールド長を指定しようとすると,正のフィールド長の前にマイナス(-)フラグが付いたものと解釈されます。

(3)

精度

これに与えられる値は,d,i,o,u,x,X変換に対しては現れる数字の個数の最小値であり,e, f, E変換に対しては“.”の後ろに現れる数字の個数であり,g,G変換に対しては最大有効桁数です。精度は,“*”,または10進整数が後ろに続く“.”の形式を取ります。“*”を指定した場合,int型の引数を精度として使用します。負の精度を指定した場合,精度を省略したものとみなされます。“.”のみが指定された場合,精度は0とされます。精度がこれら以外の変換指示とともに現れた場合,動作は不定となります。

precisionのことです。

(4)

サイズ

対応する引数のデータ型を解釈するためのデフォルトの方法を変更する,任意選択のサイズ文字h,l,ll,およびLです。

hを指定した場合,後ろに続くd,i,o,n,u,x,Xの型指定を強制的にshort,またはunsigned shortに適用します。

lを指定した場合,後ろに続くd,i,o,u,x,Xの型指定を強制的にlong,またはunsigned longに適用します。lはさらに,後ろに続くnの型指定を強制的にlongへのポインタに適用します。h,またはlといっしょにこれと別の型指定文字を使用した場合,その動作は不定です。

llを指定した場合,後ろに続くd,i,o,u,x,Xの型指定を強制的にlong long,またはunsigned long longに適用します。llはさらに,後ろに続くnの型指定を強制的にlong longへのポインタに適用します。llと一緒にこれ以外の型指定文字を使用した場合,その動作は不定です。

Lを指定した場合,後ろに続くe,E,f,g,Gの型指定を強制的にlong doubleに適用します。Lといっしょにこれ以外の型指定文字を使用した場合,その動作は不定です。

(5)

型指定文字

適用される変換の型を指定する文字です。

変換の型を指定する文字とその意味を次に示します。

%

文字“%”を出力します。引数は変換されません。変換指示は“%%”となります。

c

int型の引数をunsigned char型に変換し,変換結果の文字を出力します。

d

int型の引数を符号付きの10進数に変換します。

e,E

double型の引数を,小数点の前に(引数が0でない場合0でない)1つの文字を持ち,小数点以下の数字の個数は精度に等しい[-]d.dddde±ddの形式に変換します。E変換指示は,指数部が“e”ではなく“E”で始まる数字を生成します。

f

double型の引数を[-]dddd.ddddの形式の10進表記に変換します。

g,G

精度には仮数部の数字の個数を指定するものとし,double型の引数をe(G変換指示の場合E),またはfの形式に変換します。変換結果の末尾の0は結果の小数点部から除かれます。小数点は,後ろに数字が続く場合にのみ現れます。

i

dの変換と同じ変換をします。

n

同じオブジェクト内で出力された文字の個数を格納します。int型へのポインタを引数とします。

p

ポインタを出力します。CC-RHでは,ポインタをunsigned longとして扱っています(luの指定と同じです)。

o,u,x,X

unsigned int型の引数をddddの形式の8進表記(o),符号なしの10進表記(u),符号なしの16進表記(x,またはX)に変換します。x変換に対しては文字abcdefが用いられX変換に対しては文字ABCDEFが用いられます。

s

引数は文字型の配列を指すポインタでなければなりません。この配列からの文字を,終端を示すnull文字(\0)の前まで(null文字(\0)自身は含まずに)出力します。精度が指定された場合,それ以上の個数の文字は出力されません。精度が指定されなかった,または精度がこの配列の大きさ以上の値であった場合,この配列はnull文字(\0)を含むようにしてください。

[使用例]

#include    <stdio.h>
void func(int val) {
  char    s[20];
  sprintf(s, "%-10.51x\n", val);  /*valの値に対し,左詰め,フィールド長10,精度5,サイズlong,*/
                                  /*16進表記を指定し,改行文字を付加してsの指す配列へ出力*/
}