`mbsrtowcs`

Artikel
10/12/2023

Mengonversi string karakter multibyte di lokal saat ini ke string karakter lebar yang sesuai, dengan kemampuan memulai ulang di tengah karakter multibyte. Versi fungsi ini yang lebih aman tersedia; lihat mbsrtowcs_s.

Sintaks

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

Parameter

wcstr
Alamat untuk menyimpan string karakter lebar yang dikonversi yang dihasilkan.

mbstr
Penunjuk tidak langsung ke lokasi string karakter multibyte untuk dikonversi.

count
Jumlah maksimum karakter (bukan byte) untuk dikonversi dan disimpan dalam wcstr.

mbstate
Penunjuk ke mbstate_t objek status konversi. Jika nilai ini adalah penunjuk null, objek status konversi internal statis digunakan. Karena objek internal mbstate_t tidak aman untuk utas, kami sarankan Anda selalu meneruskan parameter Anda sendiri mbstate .

Nilai hasil

Mengembalikan jumlah karakter yang berhasil dikonversi, tidak termasuk karakter null yang dihentikan, jika ada. Mengembalikan (size_t)(-1) jika terjadi kesalahan, dan diatur errno ke EILSEQ.

Keterangan

Fungsi ini mbsrtowcs mengonversi string karakter multibyte yang secara tidak langsung diarahkan oleh mbstr, menjadi karakter lebar yang disimpan dalam buffer yang diarahkan oleh wcstr, dengan menggunakan status konversi yang terkandung dalam mbstate. Konversi berlanjut untuk setiap karakter hingga karakter multibyte null yang berakhir ditemukan, urutan multibyte yang tidak sesuai dengan karakter yang valid di lokal saat ini ditemui, atau sampai count karakter telah dikonversi. Jika mbsrtowcs menemukan karakter null multibyte ('\0') baik sebelum atau ketika count terjadi, karakter null akan dikonversi ke karakter null penghentian 16-bit dan berhenti.

Dengan demikian, string karakter lebar di dihentikan wcstr null hanya jika mbsrtowcs menemukan karakter null multibyte selama konversi. Jika urutan menunjuk ke oleh mbstr dan wcstr tumpang tindih, perilaku mbsrtowcs tidak terdefinisi. mbsrtowcs dipengaruhi oleh LC_TYPE kategori lokal saat ini.

Fungsi mbsrtowcs ini berbeda dari mbstowcs, _mbstowcs_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 harus menggunakan mbsrlen alih-alih mbslen, jika panggilan berikutnya digunakan mbsrtowcs alih-alih mbstowcs.

Jika wcstr bukan penunjuk null, objek penunjuk yang diakhiri oleh mbstr ditetapkan penunjuk null jika konversi berhenti karena karakter null yang mengakhiri tercapai. Jika tidak, alamat ditetapkan hanya melewati karakter multibyte terakhir yang dikonversi, jika ada. Ini memungkinkan panggilan fungsi berikutnya untuk memulai ulang konversi di mana panggilan ini berhenti.

wcstr Jika argumen adalah penunjuk null, count argumen diabaikan, dan mbsrtowcs mengembalikan ukuran yang diperlukan dalam karakter lebar untuk string tujuan. Jika mbstate adalah penunjuk null, fungsi menggunakan objek status konversi internal mbstate_t statis non-thread-safe. Jika urutan mbstr karakter tidak memiliki representasi karakter multibyte yang sesuai, -1 dikembalikan, dan errno diatur ke EILSEQ.

Jika mbstr adalah penunjuk null, handler parameter yang tidak valid dipanggil, seperti yang dijelaskan dalam Validasi parameter. Jika eksekusi diizinkan untuk melanjutkan, fungsi ini diatur errno ke EINVAL dan mengembalikan -1.

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 mbsrtowcs ini aman multithread selama tidak ada fungsi dalam panggilan utas setlocale saat ini selama fungsi ini dijalankan dan mbstate argumen bukan penunjuk null.

Persyaratan

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

Bagikan melalui