wcstombs, wcstombs_s
提供: cppreference.com
<tbody>
</tbody>
<tbody class="t-dcl-rev t-dcl-rev-num ">
</tbody><tbody>
</tbody>
| ヘッダ <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 を超える。src と dst がオーバーラップしている場合、動作は未規定です。2) (1) と同じですが、以下の点が異なります。
* 関数は結果を出力引数
retval として返します。 * 変換がヌル文字を書き込まずに停止した場合、関数は
dst の次のバイト (dst[len] または dst[dstsz] いずれか先に来る方) に '\0' を格納します (合計で最大 len+1/dstsz+1 バイトが書き込まれる可能性があることを意味します)。 この場合、終端のヌルの前にシフト解除シーケンスは書き込まれないかもしれません。 *
dst がヌルポインタの場合は、生成されるであろうバイト数が *retval に格納されます。 * 関数は終端のヌルから
dstsz まで格納先の配列を上書きします。 *
src と dst がオーバーラップする場合、動作は未規定です。 * 以下のエラーが実行時に検出され、現在設定されている制約ハンドラ関数を呼びます。
retvalまたはsrcがヌルポインタ。dstszまたはlenが RSIZE_MAX より大きい (dstがヌルでなければ)。dstszがゼロでない (dstがヌルでなければ)。lenがdstszより大きく、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 より大きくなければ)。 例
Run this code
#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
関連項目
(C95)(C11) |
指定された状態を使用してワイド文字列をマルチバイト文字列に変換します (関数) |
(C11) |
マルチバイト文字列をワイド文字列に変換します (関数) |
wcstombs の C++リファレンス
| |