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によって指し示される配列に保管されます。 変換は終了ヌル・ワイド文字 (これを含む) まで 続行し、保管されます。 変換中、有効なマルチバイト文字に対応しないコードに達したとき、または (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"
*/

関連情報