mbstowcs_s, _mbstowcs_s_l

Mengonversi urutan karakter multibyte ke urutan karakter lebar yang sesuai. Versi ,_mbstowcs_ldengan peningkatan keamanan seperti yang dijelaskan dalam Fitur keamanan di CRT.mbstowcs

Sintaks

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Parameter

pReturnValue
Jumlah karakter yang dikonversi.

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

sizeInWords
Ukuran wcstr buffer dengan kata-kata.

mbstr
Alamat urutan karakter multibyte null yang dihentikan.

count
Jumlah maksimum karakter lebar untuk disimpan dalam wcstr buffer, tidak termasuk penghentian null, atau _TRUNCATE.

locale
Lokal yang akan digunakan.

Nilai hasil

Nol jika berhasil, kode kesalahan pada kegagalan.

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

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 mbstowcs_s mengonversi string karakter multibyte yang diacu ke mbstr menjadi karakter lebar yang disimpan dalam buffer yang ditujukkan oleh wcstr. Konversi akan berlanjut untuk setiap karakter hingga salah satu kondisi ini terpenuhi:

• Karakter null multibyte ditemui

• Ditemui karakter multibyte yang tidak valid

• Jumlah karakter lebar yang wcstr disimpan dalam buffer sama dengan count.

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

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

Jika mbstowcs_s berhasil mengonversi string sumber, string sumber menempatkan ukuran dalam karakter luas string yang dikonversi, termasuk terminator null, ke dalam *pReturnValue (disediakan pReturnValue bukan NULL). Ukuran dihitung bahkan jika wcstr argumen adalah NULL, dan menyediakan cara untuk menentukan ukuran buffer yang diperlukan. Jika wcstr adalah NULL, count diabaikan, dan sizeInWords harus 0.

Jika mbstowcs_s menemukan karakter multibyte yang tidak valid, karakter tersebut menempatkan 0 dalam *pReturnValue, mengatur buffer tujuan ke string kosong, mengatur errno ke EILSEQ, dan mengembalikan EILSEQ.

Jika urutan menunjuk ke oleh mbstr dan wcstr tumpang tindih, perilaku mbstowcs_s tidak terdefinisi.

Penting

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

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

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.

Persyaratan

Rutin	Header yang diperlukan
mbstowcs_s	<stdlib.h>
_mbstowcs_s_l	<stdlib.h>

Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Baca juga

Konversi data
Lokal
MultiByteToWideChar
Interpretasi urutan karakter multibyte
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l