wcstombs, _wcstombs_l

Mengonversi urutan karakter lebar ke urutan karakter multibyte yang sesuai. Versi yang lebih aman dari fungsi-fungsi ini tersedia; lihat wcstombs_s, _wcstombs_s_l.

Sintaks

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Parameter

mbstr
Alamat urutan karakter multibyte.

wcstr
Alamat urutan karakter luas.

count
Jumlah maksimum byte yang dapat disimpan dalam string output multibyte.

locale
Lokal yang akan digunakan.

Nilai hasil

Jika wcstombs berhasil mengonversi string multibyte, string tersebut mengembalikan jumlah byte yang ditulis ke dalam string output multibyte, tidak termasuk penghentian NULL (jika ada). mbstr Jika argumen adalah NULL, wcstombs mengembalikan ukuran yang diperlukan dalam byte string tujuan. Jika wcstombs menemukan karakter lebar yang tidak dapat dikonversi ke karakter multibyte, karakter tersebut mengembalikan -1 cast ke jenis size_t dan mengatur errno ke EILSEQ.

Keterangan

Fungsi ini wcstombs mengonversi string karakter lebar yang ditujukan ke karakter wcstr multibyte yang sesuai dan menyimpan hasilnya dalam mbstr array. Parameter count menunjukkan jumlah maksimum byte yang dapat disimpan dalam string output multibyte (yaitu, ukuran mbstr). Secara umum, tidak diketahui berapa banyak byte yang akan diperlukan saat mengonversi string karakter lebar. Beberapa karakter lebar hanya akan memerlukan satu byte dalam string output; yang lain membutuhkan 2 byte. Jika ada 2 byte dalam string output multibyte untuk setiap karakter lebar dalam string input (termasuk karakter NULLlebar ), hasilnya dijamin pas.

Mulai Windows 10 versi 1803 (10.0.17134.0), Universal C Runtime mendukung penggunaan halaman kode UTF-8. Gunakan wcstombs(NULL, wcstr, 0) untuk mendapatkan ukuran yang benar yang Anda butuhkan untuk konversi karena dengan asumsi Anda akan membutuhkan dua byte untuk setiap karakter lebar mungkin tidak cukup. Untuk informasi selengkapnya tentang dukungan UTF-8, lihat dukungan UTF-8

Jika wcstombs menemukan karakter karakter NULL lebar (L'\0') baik sebelum atau ketika count terjadi, karakter akan mengonversinya menjadi 8-bit 0 dan berhenti. Dengan demikian, string karakter multibyte di dihentikan mbstr null hanya jika wcstombs menemukan karakter karakter NULL luas selama konversi. Jika urutan menunjuk ke oleh wcstr dan mbstr tumpang tindih, perilaku wcstombs tidak terdefinisi.

mbstr Jika argumen adalah NULL, wcstombs mengembalikan ukuran yang diperlukan dalam byte string tujuan.

wcstombs memvalidasi parameternya. Jika wcstr adalah NULL, atau jika count lebih besar dari INT_MAX, fungsi ini memanggil handler parameter yang tidak valid, seperti yang dijelaskan dalam Validasi parameter. Jika eksekusi diizinkan untuk melanjutkan, fungsi diatur errno ke EINVAL dan mengembalikan -1.

wcstombs menggunakan lokal saat ini untuk perilaku yang bergantung pada lokal; _wcstombs_l identik kecuali menggunakan lokal yang diteruskan sebagai gantinya. Untuk informasi selengkapnya, lihat Lokal.

Di C++, fungsi-fungsi ini memiliki kelebihan beban templat yang memanggil rekan-rekan yang lebih baru dan aman dari fungsi-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.

Persyaratan

Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Contoh

Program ini menggambarkan perilaku wcstombs fungsi.

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}

Convert wide-character string:
   Characters converted: 13
    Multibyte character: Hello, world.

Lihat juga

Konversi data
Lokal
_mbclen, , mblen_mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb, _wctomb_l
WideCharToMultiByte