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() 関数は、フォーマット内の対応するワイド文字フォーマット指定子に従って、引数リスト内の各エントリーを変換します。 フォーマットの形式と機能は、 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 の配列をコピーします (変換は行われません)。 精度により短い出力が指定されていない限り、配列は末尾の NULL 文字まで書き込まれますが、終了 NULL 文字は含まれません。%#ls および %#S は、それぞれ %ls および %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"
   ***************************************************************/
}

関連情報