Namespaces
Variants

wcstombs, wcstombs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
ヘッダーで定義 <stdlib.h>
(1)
size_t wcstombs ( char * dst, const wchar_t * src, size_t len ) ;
(C99まで)
size_t wcstombs ( char * restrict dst, const wchar_t * restrict src, size_t len ) ;
(C99から)
errno_t wcstombs_s ( size_t * restrict retval, char * restrict dst, rsize_t dstsz,
const wchar_t * restrict src, rsize_t len ) ;
(2) (C11から)
1) 配列の最初の要素を指す src によって示されるワイド文字のシーケンスを、初期シフト状態で始まるナローマルチバイト表現に変換します。変換された文字は、 dst によって指されるchar配列の連続する要素に格納されます。宛先配列には最大で len バイトが書き込まれます。
各文字は、 wctomb の呼び出しによって変換されるかのように処理されます。ただし、wctombの変換状態は影響を受けません。以下の場合に変換は停止します：
* ナル文字 L ' \0 ' が変換され格納されました。この場合に格納されるバイトは、アンシフトシーケンス（必要な場合）とそれに続く ' \0 ' です。
* A wchar_t が現在のCロケールで有効な文字に対応していないものが見つかりました。
* 格納される次のマルチバイト文字が len を超える場合。
src と dst が重なる場合、動作は未定義です。
2) (1) と同様、ただし
* 変換は wcrtomb によるかのようであり、 wctomb ではない
* 関数は結果をout-parameterとして返します retval
* 変換がヌル文字を書き込まずに停止した場合、関数は ' \0 ' を dst の次のバイトに格納する。これは dst[len] または dst[dstsz] のいずれか先に来る方になる（つまり最大でlen+1/dstsz+1バイトが書き込まれる可能性がある）。この場合、終端ヌル文字の前にアンシフトシーケンスが書き込まれない可能性がある。
* dst がnullポインタの場合、生成されるバイト数が * retval に格納される
* この関数は終端ナル文字から dstsz まで、宛先配列を破壊します
* src と dst が重なる場合、動作は未定義です。
* 以下のエラーは実行時に検出され、現在インストールされている constraint handler 関数を呼び出します：
  • retval または src がnullポインタの場合
  • dstsz または len が RSIZE_MAX より大きい場合（ dst がnullでない限り）
  • dstsz がゼロでない場合（ dst がnullでない限り）
  • len が dstsz より大きく、かつ変換が dstsz に達するまでに src 配列でnullまたはエンコーディングエラーに遭遇しない場合（ dst がnullでない限り）
すべての境界チェック付き関数と同様に、 wcstombs_s は実装によって __STDC_LIB_EXT1__ が定義されており、かつユーザーが <stdlib.h> をインクルードする前に __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義している場合にのみ利用可能であることが保証されます。

目次

翻訳内容: - 「Contents」→「目次」のみ翻訳 - HTMLタグ、属性、リンク先はそのまま保持 - C++関連の用語（Notes, Parameters, Return value, Example, References, See also）は翻訳せず原文のまま維持 - 数値、クラス名、IDなどは変更なし

注記

ほとんどの実装では、 wcstombs は文字列を処理する際に mbstate_t 型のグローバル静的オブジェクトを更新するため、2つのスレッドで同時に呼び出すことはできません。 このような場合は wcsrtombs または wcstombs_s を使用する必要があります。

POSIXは共通の拡張機能を規定しています： dst がヌルポインタの場合、この関数は変換された場合に dst に書き込まれるバイト数を返します。同様の動作は wcsrtombs および wcstombs_s でも標準化されています。

パラメータ

dst - マルチバイト文字が格納されるナロウ文字配列へのポインタ
src - 変換対象のnull終端ワイド文字列の先頭要素へのポインタ
len - dstが指す配列で利用可能なバイト数
dstsz - 書き込まれる最大バイト数（ dst 配列のサイズ）
retval - 結果が格納されるsize_tオブジェクトへのポインタ

戻り値

1) 成功時は、 dst が指す先頭要素の文字配列に書き込まれたバイト数（シフトシーケンスを含むが、終端の ' \0 ' を除く）を返す。変換エラー時（無効なワイド文字が検出された場合）は、 ( size_t ) - 1 を返す。
2) 成功時はゼロを返し（この場合、終端ナル文字を除いて dst に書き込まれた、または書き込まれる予定のバイト数が * retval に格納される）、エラー時は非ゼロを返す。実行時制約違反の場合、 ( size_t ) - 1 を * retval に格納し（ retval がnullでない場合）、 dst [ 0 ] を ' \0 ' に設定する（ dst がnullでない、かつ dstmax がゼロでなく、かつ RSIZE_MAX より大きくない場合）

例

このコードを実行 
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
int main(void)
{
    // 4つのワイド文字
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // UTF-8では10バイトを占有
    char dst[11];
    setlocale(LC_ALL, "en_US.utf8");
    printf("wide-character string: '%ls'\n",src);
    for (size_t ndx=0; ndx < sizeof src/sizeof src[0]; ++ndx)
        printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);
    int rtn_val = wcstombs(dst, src, sizeof dst);
    printf("rtn_val = %d\n", rtn_val);
    if (rtn_val > 0)
        printf("multibyte string:  '%s'\n",dst);
    for (size_t ndx=0; ndx<sizeof dst; ++ndx)
        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
}

出力: 

wide-character string: 'zß水🍌'
   src[ 0] =     0x7a
   src[ 1] =     0xdf
   src[ 2] =   0x6c34
   src[ 3] =  0x1f34c
   src[ 4] =        0
rtn_val = 10
multibyte string:  'zß水🍌'
   dst[ 0] = 0x7a
   dst[ 1] = 0xc3
   dst[ 2] = 0x9f
   dst[ 3] = 0xe6
   dst[ 4] = 0xb0
   dst[ 5] = 0xb4
   dst[ 6] = 0xf0
   dst[ 7] = 0x9f
   dst[ 8] = 0x8d
   dst[ 9] = 0x8c
   dst[10] =  0

参考文献

  • C11規格 (ISO/IEC 9899:2011):
  • 7.22.8.2 wcstombs関数 (p: 360)
  • K.3.6.5.2 wcstombs_s関数 (p: 612-614)
  • C99規格 (ISO/IEC 9899:1999):
  • 7.20.8.2 wcstombs関数 (p: 324)
  • C89/C90規格 (ISO/IEC 9899:1990):
  • 4.10.8.2 wcstombs関数

関連項目

(C95) (C11)
ワイド文字列をナローマルチバイト文字列に変換する（状態指定付き）
(関数)
(C11)
ナローマルチバイト文字列をワイド文字列に変換する
(関数)
C++ドキュメント for wcstombs