名前空間
変種
操作

wcstombs, wcstombs_s

提供: cppreference.com
< c‎ | string‎ | multibyte
ヘッダ <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 の指す文字配列の連続する要素に格納されます。 最大 len バイトが格納先の配列に書き込まれます。
各文字は wctomb の変換状態が影響を受けないことを除いて wctomb を呼んだかのように変換されます。 変換は以下の場合に停止します。
* ヌル文字 L'\0' が変換され格納された。 この場合、格納されるバイト列はシフト解除シーケンス (必要であれば) に '\0' が続いたものになります。
* 現在の C のロケールにおいて有効な文字に対応しない wchar_t が見つかった。
* 格納される次のマルチバイト文字が len を超える。
srcdst がオーバーラップしている場合、動作は未規定です。
2) (1) と同じですが、以下の点が異なります。
* 変換は wctomb ではなく wcrtomb によって行われたかのように行われます。
* 関数は結果を出力引数 retval として返します。
* 変換がヌル文字を書き込まずに停止した場合、関数は dst の次のバイト (dst[len] または dst[dstsz] いずれか先に来る方) に '\0' を格納します (合計で最大 len+1/dstsz+1 バイトが書き込まれる可能性があることを意味します)。 この場合、終端のヌルの前にシフト解除シーケンスは書き込まれないかもしれません。
* dst がヌルポインタの場合は、生成されるであろうバイト数が *retval に格納されます。
* 関数は終端のヌルから dstsz まで格納先の配列を上書きします。
* srcdst がオーバーラップする場合、動作は未規定です。
* 以下のエラーが実行時に検出され、現在設定されている制約ハンドラ関数を呼びます。
  • retval または src がヌルポインタ。
  • dstsz または lenRSIZE_MAX より大きい (dst がヌルでなければ)。
  • dstsz がゼロでない (dst がヌルでなければ)。
  • lendstsz より大きく、 src 配列の dstsz に達するまでヌルまたはエンコーディングエラーに遭遇しない (dst がヌルでなければ)。
すべての境界チェック付き関数と同様に、 wcstombs_s__STDC_LIB_EXT1__ が処理系によって定義されていて、 <stdlib.h> をインクルードする前にユーザが __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義した場合にのみ、利用可能であることが保証されます。

目次

[編集] ノート

ほとんどの処理系では、 wcstombs は文字列を処理するにあたって mbstate_t 型のグローバルな静的オブジェクトを更新し、複数のスレッドから同時に呼ぶことができません。 そのような場合は wcsrtombs または wcstombs_s を使用するべきです。

POSIX は次のようなよくある拡張を規定しています。 dst がヌルポインタの場合、この関数は、もし変換が行われたならば dst に書き込まれたであろうバイト数を返します。 同様の動作は wcsrtombs および wcstombs_s の場合は標準です。

[編集] 引数

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

[編集] 戻り値

1) 成功した場合は、 dst によって最初の要素が指されている文字配列に書き込まれた (シフトシーケンスを含み、終端の '\0' を含まない) バイト数を返します。 変換エラーが発生した (無効なワイド文字に遭遇した) 場合は、 (size_t)-1 を返します。
2) 成功した場合はゼロを返し、 dst に書き込まれた、または書き込まれたであろう、終端のゼロを除くワイド文字数が *retval に格納されます。 エラーの場合は非ゼロを返します。 実行時制約違反の場合は、 (size_t)-1*retval に格納し (retval がヌルでなければ)、 dst[0]'\0' に設定します (dst がヌルでなく、 dstmax がゼロでなく RSIZE_MAX より大きくなければ)。

[編集]

#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
 
int main(void)
{
    // 4 wide characters
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // they occupy 10 bytes in UTF-8
    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 standard (ISO/IEC 9899:2011):
  • 7.22.8.2 The wcstombs function (p: 360)
  • K.3.6.5.2 The wcstombs_s function (p: 612-614)
  • C99 standard (ISO/IEC 9899:1999):
  • 7.20.8.2 The wcstombs function (p: 324)
  • C89/C90 standard (ISO/IEC 9899:1990):
  • 4.10.8.2 The wcstombs function

[編集] 関連項目

指定された状態を使用してワイド文字列をマルチバイト文字列に変換します
(関数) [edit]
マルチバイト文字列をワイド文字列に変換します
(関数) [edit]