wcstombs, wcstombs_s
ja.cppreference.net より
| ヘッダ <stdlib.h>
|
||
size_t wcstombs( char* dst, const wchar_t* src, size_t len );
|
で定義 (1) | (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'が続くものとなる。 - 現在の C ロケールにおいて有効な文字に対応しない
wchar_tが見つかった場合。 - 次に格納されるマルチバイト文字が
lenを超える場合。
src と dst が重なる場合、動作は未規定である。2) (1) と同じであるが、以下が異なる：
- 変換は wcrtomb によるかのように行われ、wctomb
- ではない。関数はその結果を out-パラメータ
retval - として返す。ナル文字を書き込まずに変換が停止した場合、関数は
'\0'をdstの次のバイトに格納する。これはdst[len]またはdst[dstsz]のいずれか早い方であり（最大で 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__ が実装によって定義され、かつユーザーが __STDC_WANT_LIB_EXT1__ を整数定数 1 として <stdlib.h> をインクルードする前に定義している場合に限られる。ノート
ほとんどの実装では、wcstombs は文字列を処理する際に mbstate_t 型の大域静的オブジェクトを更新するため、2 つのスレッドから同時に呼び出すことはできません。そのような場合には wcsrtombs または wcstombs_s を使用すべきです。
POSIX は共通の拡張を規定しています: dst がナルポインタの場合、この関数は変換された場合に dst に書き込まれるであろうバイト数を返します。同様の動作は wcsrtombs および wcstombs_s で標準化されています。
引数
| dst | - | マルチバイト文字が格納されるナロー文字配列へのポインタ |
| src | - | 変換するナル終端ワイド文字列の先頭要素へのポインタ |
| len | - | dst が指す配列で使用可能なバイト数 |
| dstsz | - | 書き込まれる最大バイト数（dst 配列のサイズ）
|
| retval | - | 結果が格納される size_t オブジェクトへのポインタ |
戻り値
1) 成功した場合、
'\0' によって先頭要素が指された文字配列に書き込まれたバイト数（シフト文字の並びを含み、終端の dst は除く）を返す。変換エラー（無効なワイド文字に遭遇した場合）は (size_t)-1 を返す。2) 成功した場合はゼロを返し（その場合、終端のゼロを除いた
dst に書き込まれた（または書き込まれるであろう）バイト数が *retval に格納される）、エラーの場合は非ゼロを返す。実行時制約違反の場合、(size_t)-1 に *retval を格納し（retval がナルでない場合）、dst[0] を '\0' に設定する（dst がナルの場合、または dstmax がゼロもしくは RSIZE_MAX より大きい場合を除く）。例
このコードを実行
#include <locale.h>
#include <stdio.h>
#include <stdlib.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
参考文献
- C23 標準 (ISO/IEC 9899:2024):
- 7.22.8.2 The wcstombs function (p: TBD)
- K.3.6.5.2 The wcstombs_s function (p: TBD)
- C17 標準 (ISO/IEC 9899:2018):
- 7.22.8.2 The wcstombs function (p: TBD)
- K.3.6.5.2 The wcstombs_s function (p: TBD)
- 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
| |