`wcrtomb_s`

Artikel
10/12/2023

Mengonversi karakter lebar menjadi representasi karakter multibyte-nya. Versi wcrtomb dengan peningkatan keamanan seperti yang dijelaskan dalam Fitur keamanan di CRT.

Sintaks

errno_t wcrtomb_s(
   size_t *pReturnValue,
   char *mbchar,
   size_t sizeOfmbchar,
   wchar_t *wchar,
   mbstate_t *mbstate
);
template <size_t size>
errno_t wcrtomb_s(
   size_t *pReturnValue,
   char (&mbchar)[size],
   wchar_t *wchar,
   mbstate_t *mbstate
); // C++ only

Parameter

pReturnValue
Mengembalikan jumlah byte yang ditulis atau -1 jika terjadi kesalahan.

mbchar
Karakter yang dikonversi multibyte yang dihasilkan.

sizeOfmbchar
Ukuran mbchar variabel dalam byte.

wchar
Karakter lebar untuk dikonversi.

mbstate
Penunjuk ke mbstate_t objek.

Nilai hasil

Mengembalikan nol atau errno nilai jika terjadi kesalahan.

Keterangan

Fungsi mengonversi wcrtomb_s karakter lebar, dimulai dalam status konversi yang ditentukan yang terkandung dalam mbstate, dari nilai yang terkandung dalam wchar, ke alamat yang diwakili oleh mbchar. Nilainya pReturnValue adalah jumlah byte yang dikonversi, tetapi tidak lebih dari MB_CUR_MAX byte, atau -1 jika terjadi kesalahan.

Jika mbstate null, status konversi internal mbstate_t digunakan. Jika karakter yang terkandung tidak wchar memiliki karakter multibyte yang sesuai, nilainya pReturnValue adalah -1, dan fungsi mengembalikan errno nilai .EILSEQ

Fungsi wcrtomb_s ini berbeda dari wctomb_s, _wctomb_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 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 wcrtomb_s ini aman multithread selama tidak ada fungsi dalam panggilan utas setlocale saat ini saat fungsi ini dijalankan dan mbstate null.

Contoh

// crt_wcrtomb_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    errno_t     returnValue;
    size_t      pReturnValue;
    mbstate_t   mbstate;
    size_t      sizeOfmbStr = 1;
    char        mbchar = 0;
    wchar_t*    wchar = L"Q\0";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
                            *wchar, &mbstate);
    if (returnValue == 0) {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wchar);
        printf(" was converted to a the \"%c\" ", mbchar);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to a the "Q" multibyte character.

Persyaratan

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