wcstombs, wcstombs_s
From cppreference.com
| ヘッダー <stdlib.h> で定義 |
||
| (1) | ||
| (C99まで) | ||
| (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' です。
* 現在のCロケールで有効な文字に対応しない wchar_t が見つかった場合。
* 次に格納されるマルチバイト文字が
len を超える場合。src と dst が重複する場合、動作は未定義です。2) 以下を除いて (1) と同じです。
* 関数は結果を出力パラメータ
retval として返します。 * 変換がヌル文字を書き込まずに停止した場合、関数は
dst の次のバイトに '\0' を格納します。これは dst[len] または dst[dstsz] のいずれか早い方になります（つまり、最大 len+1 / dstsz+1 バイトが書き込まれる可能性があります）。この場合、終端ヌルの前にアンシフトシーケンスが書き込まれないことがあります。 *
dst がヌルポインタの場合、生成されるバイト数が *retval に格納されます。 * 関数は、終端ヌルから
dstsz まで宛先配列を破壊します。 *
src と dst が重複する場合、動作は未定義です。 * 実行時に以下のエラーが検出され、現在インストールされている 制約ハンドラ関数が呼び出されます。
-
retvalまたはsrcがヌルポインタである。 -
dstszまたはlenが RSIZE_MAX より大きい（dstがヌルでない場合）。 -
dstszがゼロでない（dstがヌルでない場合）。 -
lenがdstszより大きく、かつdstszに達する時点でsrc配列でヌルまたはエンコーディングエラーに遭遇しない場合（dstがヌルでない場合）。
-
- すべての境界チェック付き関数と同様に、
wcstombs_sは、実装によって __STDC_LIB_EXT1__ が定義されており、ユーザーが <stdlib.h> をインクルードする前に __STDC_WANT_LIB_EXT1__ を整数定数 1 として定義した場合にのみ、使用が保証されます。
目次 |
[編集] 注記
ほとんどの実装では、wcstombs は文字列を処理する際に、mbstate_t 型のグローバル静的オブジェクトを更新するため、2つのスレッドから同時に呼び出すことはできません。このような場合は、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標準 (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標準 (ISO/IEC 9899:1999)
- 7.20.8.2 The wcstombs function (p: 324)
- C89/C90標準 (ISO/IEC 9899:1990)
- 4.10.8.2 The wcstombs function
[編集] 関連項目
| (C95)(C11) |
与えられた状態で、ワイド文字列をナローマルチバイト文字列に変換する (関数) |
| (C11) |
ナローマルチバイト文字列をワイド文字列に変換する (関数) |
| C++ ドキュメント for wcstombs
| |
