`wcrtomb`

Artikel
10/12/2023

Mengonversi karakter lebar menjadi representasi karakter multibyte-nya. Versi fungsi ini yang lebih aman tersedia; lihat wcrtomb_s.

Sintaks

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

Parameter

mbchar
Karakter yang dikonversi multibyte yang dihasilkan.

wchar
Karakter lebar untuk dikonversi.

mbstate
Penunjuk ke mbstate_t objek.

Nilai hasil

Mengembalikan jumlah byte yang diperlukan untuk mewakili karakter multibyte yang dikonversi, jika tidak, -1 jika terjadi kesalahan.

Keterangan

Fungsi mengonversi wcrtomb karakter lebar, dimulai dalam status konversi yang ditentukan yang terkandung dalam mbstate, dari nilai yang terkandung dalam wchar, ke alamat yang diwakili oleh mbchar. Nilai yang dikembalikan adalah jumlah byte yang diperlukan untuk mewakili karakter multibyte yang sesuai, tetapi tidak akan mengembalikan lebih dari MB_CUR_MAX byte.

Jika mbstate null, objek internal mbstate_t yang berisi status mbchar konversi digunakan. Jika urutan wchar karakter tidak memiliki representasi karakter multibyte yang sesuai, -1 dikembalikan, dan errno diatur ke EILSEQ.

Fungsi wcrtomb ini berbeda dari wctomb, _wctomb_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 wcsnlen, jika panggilan berikutnya digunakan wcsrtombs alih-alih wcstombs.

Di C++, fungsi ini memiliki kelebihan beban templat yang memanggil rekan yang lebih baru dan aman dari fungsi ini. 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 ini aman multithread selama tidak ada fungsi dalam panggilan utas setlocale saat ini saat fungsi ini dijalankan dan sementara mbstate null.

Contoh

// crt_wcrtomb.c
// compile with: /W3
// This program converts a wide character
// to its corresponding multibyte character.

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

int main( void )
{
    size_t      sizeOfCovertion = 0;
    mbstate_t   mbstate;
    char        mbStr = 0;
    wchar_t*    wcStr = L"Q";

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

    sizeOfCovertion = wcrtomb(&mbStr, *wcStr, &mbstate); // C4996
    // Note: wcrtomb is deprecated; consider using wcrtomb_s instead
    if (sizeOfCovertion > 0)
    {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wcStr);
        printf(" was converted to the \"%c\" ", mbStr);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

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

Persyaratan

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

Bagikan melalui