swprintf() — ワイド文字のフォーマット設定とバッファーへの書き込み

フォーマット

#include <wchar.h>
int swprintf(wchar_t *wcsbuffer, size_t n,
             const wchar_t *format, argument-list);

言語レベル

ANSI

スレッド・セーフ

はい

ロケール依存

この関数の振る舞いは、現行ロケールの LC_CTYPE カテゴリーおよび LC_NUMERIC カテゴリーの影響を受ける可能性があります。また、LOCALETYPE(*LOCALEUCS2) または LOCALETYPE(*LOCALEUTF) がコンパイル・コマンドで指定されている場合、この振る舞いは、現行ロケールの LC_UNI_CTYPE カテゴリーおよび LC_UNI_NUMERIC カテゴリーの影響も受ける可能性があります。この関数は、コンパイル・コマンドに対して LOCALETYPE(*CLD) が指定されている場合には使用できません。詳細については、CCSID およびロケールの理解を参照してください。

ワイド文字関数

詳細については、ワイド文字を参照してください。

説明

swprintf() 関数は、一連のワイド文字と値をフォーマット設定し、ワイド文字バッファー wcsbuffer に保管します。 swprintf() 関数は、ワイド文字で機能する点を除いて、sprintf() 関数と同等です。

値 n は、終了ヌル文字を含む、書き込まれるワイド文字の最大数を指定します。swprintf() 関数は、format 内の対応するワイド文字フォーマット指定子に応じて引数リスト内の各項目を変換します。この書式には printf() 関数の書式ストリングと同じ形式と機能がありますが、以下の点が異なります。

%c (l 接頭部なし) は、mbtowc() 関数を呼び出して変換したかのように、文字引数を wchar_t に変換します。
%lc および %C は wchar_t を wchar_t へコピーします。%#lc は %lc と同等で、 %#C は %C と同等です。
%s (l 接頭部なし) は、mbstowcs() 関数を呼び出して変換したかのように、マルチバイト文字の配列を wchar_t の配列に変換します。この配列は、終了ヌル文字に達するまで書き込まれます (終了ヌル文字自身は書き込まれません) 。ただし、より短い出力が精度に指定されている場合は除きます。
%ls および %S は wchar_t の配列をコピーします (変換は行われません)。この配列は、終了ヌル文字に達するまで書き込まれます (終了ヌル文字自身は書き込まれません)。ただし、より短い出力が精度に指定されている場合は除きます。 %#ls は %ls と同等で、%#S は %S と同等です。

幅および精度は常にワイド文字です。

ヌル・ワイド文字は、書き込まれるワイド文字の末尾に追加されます。ヌル・ワイド文字は、戻り値の一部として数えられません。オーバーラップしたオブジェクト間でコピーが行われる場合には、振る舞いは予期できません。

戻り値

swprintf() 関数は、出力バッファーに書き込まれるワイド文字の数を戻し、エラーが発生した場合に終了ヌル・ワイド文字または負の値をカウントしません。 n 文字以上のワイド文字の書き込みが要求された場合、負の値が戻されます。

errno の値は EINVAL (無効な引数) に設定される可能性があります。

例

この例では、swprintf() 関数を使用して、いくつかの値をフォーマット設定し、バッファーへ出力します。

#include <wchar.h>
#include <stdio.h>
 
#define BUF_SIZE 100
 
int main(void)
{
   wchar_t wcsbuf[BUF_SIZE];
   wchar_t wstring[] = L"ABCDE";
   int     num;
 
   num = swprintf(wcsbuf, BUF_SIZE, L"%s", "xyz");
   num += swprintf(wcsbuf + num, BUF_SIZE - num, L"%ls", wstring);
   num += swprintf(wcsbuf + num, BUF_SIZE - num, L"%i", 100);
   printf("The array wcsbuf contains: ¥"%ls¥"¥n", wcsbuf);
   return 0;
 
   /***************************************************************
      The output should be similar to :
 
      The array wcsbuf contains: "xyzABCDE100"
   ***************************************************************/
}