wcstombs() - ワイド文字ストリングのマルチバイト文字ストリングへの変換

標準

形式

#include <stdlib.h>

size_t wcstombs(char * __restrict__dest, 
                const wchar_t * __restrict__string, size_t count);

機能説明

string が指すワイド文字ストリングを dest が指すマルチバイト配列に変換します。変換されたストリングは初期シフト状態で始まります。dest の count バイトがフルになったか、NULL ワイド文字が見つかった後で、変換は停止します。

このワイド文字関数の動作は、現行ロケールの LC_CTYPE カテゴリーの影響を受けます。 カテゴリーを変更すると、未定義の結果が発生する可能性があります。

正常に実行されなかった場合、mbstowcs() は (size_t)-1 を戻して、errno を次のいずれかの値に設定します。

エラー・コード

説明

EINVAL

この入力引数は、ワイド文字に対するポインターではなく、NULL です。

EILSEQ

wcstombs() は、有効なワイド文字コードではないシーケンスを検出しました。

mbstowcs() インターフェースは、無効な入力引数の有無をチェックします。 3 番目の引数 (wchar_t elements のストリングへのポインターである必要がある) が NULL である場合、このインターフェースは errno を EINVAL に設定し、-1 を戻します。 これにより、3 番目の引数がヌルのポインターである状態 (この場合では 1 が戻されるはずで、マルチバイト・ターゲット・ストリングがヌル・バイトを含む可能性がある) とはっきり区別できます。

戻り値

終了 NULL ワイド文字を除く、マルチバイト文字ストリングの 長さ (バイト単位) を戻します。無効のマルチバイト文字が見つかった場合、または *string が NULL ポインターである場合は、値 (size_t)-1 が戻されます。

count が戻り値の場合には、配列は NULL 終了ではありません。

*dest が NULL ポインターの場合には、ワイド文字ストリングを変換するのに必要な文字数が戻されます。

*dest が指すエリアが (count の値が 示すとおり) 小さすぎて、マルチバイト文字として表示された ワイド文字コードを入れることができない場合には、完全マルチバイト文字を含むバイト数が戻されます。

例

⁄* CELEBW24

   In this example, a wide-character string is converted to a
   char string twice.  The first call converts the entire string, while
   the second call only converts three characters.  The results are
   printed each time.

 *⁄
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define SIZE 20

int main(void)
{
  char dest[SIZE];
  wchar_t * dptr = L"string";
  size_t count = SIZE;
  size_t length;

  length = wcstombs( dest, dptr, count );
  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 *⁄
  length = wcstombs( dest, dptr, 3 );
  printf( "%d characters were converted.¥n", length );
  printf( "The converted string is ¥"%s¥"¥n", dest );
}

6 characters were converted.
The converted string is "string"

3 characters were converted.
The converted string is "str"

関連情報

• stdlib.h
• mbstowcs() - マルチバイト文字のワイド文字への変換
• wcslen() - ワイド文字ストリング長の計算
• wcsrtombs() - ワイド文字ストリングのマルチバイト・ストリングへの変換
• wctomb() - ワイド文字のマルチバイト文字への変換