Namespaces
Variants

wcsrtombs, wcsrtombs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
定義済みヘッダー <wchar.h>
(1)
size_t wcsrtombs ( char * dst, const wchar_t ** src, size_t len, mbstate_t * ps ) ;
(C95以降)
(C99まで)
size_t wcsrtombs ( char * restrict dst, const wchar_t ** restrict src, size_t len,
mbstate_t * restrict ps ) ;
(C99以降)
errno_t wcsrtombs_s ( size_t * restrict retval, char * restrict dst, rsize_t dstsz,

const wchar_t ** restrict src, rsize_t len,

mbstate_t * restrict ps ) ;
(2) (C11以降)
1) * src が指す配列の最初の要素から始まるワイド文字のシーケンスを、 * ps で記述される変換状態で開始するナローマルチバイト表現に変換する。 dst がnullでない場合、変換された文字は dst が指すchar配列の連続する要素に格納される。宛先配列には最大 len バイトまで書き込まれる。各文字は wcrtomb の呼び出しによって変換される。変換は以下の場合に停止する:
  • ナル文字 L ' \0 ' が変換され格納された場合。この場合、格納されるバイトは（必要であれば）アンシフトシーケンスとそれに続く ' \0 ' であり、 * src はnullポインタ値に設定され、 * ps は初期シフト状態を表す。
  • 現在のCロケールで有効な文字に対応しない wchar_t が見つかった場合。 * src は変換されなかった最初のワイド文字を指すように設定される。
  • 次に格納されるマルチバイト文字が len を超える場合。 * src は変換されなかった最初のワイド文字を指すように設定される。この条件は dst がnullポインタの場合にはチェックされない。
2) (1) と同様だが、以下の点が異なる：
  • 関数は結果を出力パラメータ retval として返す
  • 変換がヌル文字を書き込まずに停止した場合、関数は ' \0 ' を dst の次のバイトに格納する（これは dst [ len ] または dst [ dstsz ] のいずれか先に到達する方）。この場合、終端ヌル文字の前にアンシフトシーケンスが書き込まれない可能性がある。
  • 関数は終端ヌル文字から dstsz まで宛先配列を上書きする
  • src と dst が重複する場合、動作は未定義
  • 以下のエラーが実行時に検出され、現在設定されている 制約ハンドラ 関数を呼び出す：
  • retval 、 ps 、 src または * src がヌルポインタ
  • dstsz または len が RSIZE_MAX より大きい（ dst がヌルの場合を除く）
  • dstsz がゼロでない（ dst がヌルの場合を除く）
  • len が dstsz より大きく、かつ dstsz に達するまでに src 配列でヌルまたはエンコーディングエラーに遭遇しない（ dst がヌルの場合を除く）
すべての境界チェック付き関数と同様に、 wcsrtombs_s は実装によって __STDC_LIB_EXT1__ が定義され、かつユーザーが <wchar.h> をインクルードする前に __STDC_WANT_LIB_EXT1__ を整数定数 1 に定義した場合にのみ利用可能であることが保証される。

目次

パラメータ

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

戻り値

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

例

このコードを実行 
#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
void print_wide(const wchar_t* wstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + wcsrtombs(NULL, &wstr, 0, &state);
    char mbstr[len];
    wcsrtombs(mbstr, &wstr, len, &state);
    printf("Multibyte string: %s\n", mbstr);
    printf("Length, including '\\0': %zu\n", len);
}
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_wide(L"z\u00df\u6c34\U0001f34c"); // or L"zß水🍌"
}

出力: 

Multibyte string: zß水🍌
Length, including '\0': 11

参考文献

  • C17規格 (ISO/IEC 9899:2018):
  • 7.29.6.4.2 wcsrtombs関数 (p: 324-325)
  • K.3.9.3.2.2 wcsrtombs_s関数 (p: 471-472)
  • C11規格 (ISO/IEC 9899:2011):
  • 7.29.6.4.2 wcsrtombs関数 (p: 446)
  • K.3.9.3.2.2 wcsrtombs_s関数 (p: 649-651)
  • C99規格 (ISO/IEC 9899:1999):
  • 7.24.6.4.2 wcsrtombs関数 (p: 392)

関連項目

(C11)
ワイド文字列をナローマルチバイト文字列に変換する
(関数)
(C95) (C11)
ワイド文字をマルチバイト表現に変換する（状態指定）
(関数)
(C95) (C11)
ナローマルチバイト文字列をワイド文字列に変換する（状態指定）
(関数)
C++ documentation for wcsrtombs