`wcsrtombs_s`

Artikel
10/12/2023

Mengonversi string karakter lebar ke representasi string karakter multibyte-nya. Versi wcsrtombs dengan peningkatan keamanan seperti yang dijelaskan dalam Fitur keamanan di CRT.

Sintaks

errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parameter

pReturnValue
Ukuran dalam byte string yang dikonversi, termasuk terminator null.

mbstr
Alamat buffer untuk string karakter multibyte yang dikonversi yang dihasilkan.

sizeInBytes
Ukuran dalam byte mbstr buffer.

wcstr
Arahkan ke string karakter lebar yang akan dikonversi.

count
Jumlah maksimum byte yang akan disimpan dalam mbstr buffer, atau _TRUNCATE.

mbstate
Penunjuk ke mbstate_t objek status konversi.

Nilai hasil

Nol jika berhasil, kode kesalahan pada kegagalan.

Kondisi kesalahan	Mengembalikan nilai dan `errno`
`mbstr` adalah `NULL` dan `sizeInBytes`> 0	`EINVAL`
`wcstr` is `NULL`	`EINVAL`
Buffer tujuan terlalu kecil untuk berisi string yang dikonversi (kecuali `count` adalah `_TRUNCATE`; lihat Keterangan di bawah)	`ERANGE`

Jika salah satu kondisi ini terjadi, pengecualian parameter yang tidak valid dipanggil seperti yang dijelaskan dalam Validasi parameter . Jika eksekusi diizinkan untuk melanjutkan, fungsi mengembalikan kode kesalahan dan mengatur errno seperti yang ditunjukkan dalam tabel.

Keterangan

Fungsi ini wcsrtombs_s mengonversi string karakter lebar yang diacu ke menjadi wcstr karakter multibyte yang disimpan dalam buffer yang ditujukkan oleh mbstr, menggunakan status konversi yang terkandung dalam mbstate. Konversi akan berlanjut untuk setiap karakter hingga salah satu kondisi ini terpenuhi:

Karakter lebar null ditemui
Karakter lebar yang tidak dapat dikonversi ditemui
Jumlah byte yang disimpan dalam mbstr buffer sama dengan count.

String tujuan selalu dihentikan null (bahkan jika ada kesalahan).

Jika count adalah nilai _TRUNCATEkhusus , maka wcsrtombs_s mengonversi string sebanyak yang akan masuk ke dalam buffer tujuan, sambil tetap meninggalkan ruang untuk terminator null.

Jika wcsrtombs_s berhasil mengonversi string sumber, string sumber menempatkan ukuran dalam byte string yang dikonversi, termasuk terminator null, ke dalam *pReturnValue (disediakan pReturnValue bukan NULL). Ukuran dihitung bahkan jika mbstr argumen adalah NULL; ini menyediakan cara untuk menentukan ukuran buffer yang diperlukan. Jika mbstr adalah NULL, count diabaikan.

Jika wcsrtombs_s menemukan karakter lebar yang tidak dapat dikonversi ke karakter multibyte, karakter tersebut menempatkan -1 di *pReturnValue, mengatur buffer tujuan ke string kosong, mengatur errno ke EILSEQ, dan mengembalikan EILSEQ.

Jika urutan menunjuk ke oleh wcstr dan mbstr tumpang tindih, perilaku wcsrtombs_s tidak terdefinisi. wcsrtombs_s dipengaruhi oleh kategori LC_TYPE lokal saat ini.

Penting

Pastikan dan wcstrmbstr jangan tumpang tindih, dan itu mencerminkan jumlah karakter lebar yang count akan dikonversi dengan benar.

Fungsi wcsrtombs_s ini berbeda dari wcstombs_s, _wcstombs_s_l dengan restartability-nya. Status konversi disimpan dalam mbstate untuk panggilan berikutnya ke fungsi yang sama atau dapat dimulai ulang lainnya. Hasil tidak terdefinisi saat mencampur penggunaan fungsi yang dapat dimulai ulang dan tidak dapat ditarik kembali. Misalnya, aplikasi akan menggunakan wcsrlen daripada wcslen, jika panggilan berikutnya digunakan wcsrtombs_s alih-alih wcstombs_s.

Di C++, menggunakan fungsi-fungsi ini disederhanakan oleh kelebihan beban templat; kelebihan beban dapat menyimpulkan panjang buffer secara otomatis (menghilangkan kebutuhan untuk menentukan argumen ukuran) dan mereka dapat secara otomatis mengganti fungsi lama yang tidak aman dengan rekan-rekan yang lebih baru dan aman. Untuk informasi selengkapnya, lihat Mengamankan kelebihan beban templat.

Secara default, status global fungsi ini dicakup ke aplikasi. Untuk mengubah perilaku ini, lihat Status global di CRT.

Pengecualian

Fungsi wcsrtombs_s ini aman multithread selama tidak ada fungsi dalam panggilan utas setlocale saat ini saat fungsi ini dijalankan dan mbstate null.

Contoh

// crt_wcsrtombs_s.cpp
//
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Persyaratan

Rutin	Header yang diperlukan
`wcsrtombs_s`	<wchar.h>