wcsrtombs() — ワイド文字ストリングからマルチバイト・ストリングへの変換 (再開可能)

フォーマット

#include <wchar.h>
size_t wcsrtombs (char *dst, const wchar_t **src, size_t len,
                  mbstate_t  *ps);

言語レベル

ANSI

スレッド・セーフ

4 番目のパラメーター ps が NULL ではない場合は対応しています。

ロケール依存

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

ワイド文字関数

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

説明

この関数は、wcstombs() の再始動可能バージョンです。

wcsrtombs() 関数は、src が間接的に指す配列にあるワイド文字列を、対応するマルチバイト文字列 (ps が記述するシフト状態で開始されるもの) に変換します。変換された文字列は、dst が指す配列に保管されます (dst が NULL ポインターでない場合)。変換は終了ヌル・ワイド文字 (これを含む) まで続行し、保管されます。変換中、有効なマルチバイト文字に対応しないコードに達したとき、または (dst が NULL ポインターでない場合に) dst によって指される配列に、次にマルチバイト・エレメントが保管されると、合計バイト len の限界を超えてしまうときは、変換が早い段階で停止してしまいます。それぞれの変換は、wcrtomb() の呼び出しであるかのように行われます。

dst が NULL ポインターでない場合には、 src が指すオブジェクトは (終了ヌル文字に達したので変換が終了した場合に) NULL ポインターが割り当てられるか、最後のワイド文字が変換された直後にコードのアドレスが割り当てられます。終了ヌル・ワイド文字に達したので変換が停止した場合には、記述されている結果の状態は初期変換状態になります。

戻り値

最初のコードが有効なワイド文字でない場合、エンコード・エラーが発生します。 wcsrtombs() は、マクロ EILSEQ の値を errno に保管し、 (size_t) -1 を戻しますが、変換状態は未変更のままになります。そうでない場合、結果のマルチバイト文字シーケンスでバイト文字を戻します。これは、dst が NULL ポインターでないときに変更された配列エレメント数と同じです。

変換エラーが発生した場合、errno は ECONVERT に設定される可能性があります。

例

#include <stdio.h>
#include <wchar.h>
#include <string.h>
 
#define SIZE 20
 
int main(void)
{
   char     dest[SIZE];
   wchar_t *wcs = L"string";
   wchar_t *ptr;
   size_t   count = SIZE;
   size_t   length;
   mbstate_t ps = 0;
 
   ptr = (wchar_t *) wcs;
   length = wcsrtombs(dest, ptr, count, &ps);
   printf("%d characters were converted.¥n", length);
   printf("The converted string is ¥"%s¥"¥n¥n", dest);
 
   /* Reset the destination buffer */
   memset(dest, '¥0', sizeof(dest));
 
   /* Now convert only 3 characters */
   ptr = (wchar_t *) wcs;
   length = wcsrtombs(dest, ptr, 3, &ps);
   printf("%d characters were converted.¥n", length);
   printf("The converted string is ¥"%s¥"¥n¥n", dest);
}
 
/*****************  Output should be similar to:  **********************
6 characters were converted.
The converted string is "string"
 
3 characters were converted.
The converted string is "str"
*/