wcsrtombs_s
Mengonversi string karakter lebar ke representasi string karakter multibyte-nya. Versi wcsrtombs
dengan peningkatan keamanan seperti yang dijelaskan dalam Fitur keamanan di CRT.
Sintaks
errno_t wcsrtombs_s(
size_t *pReturnValue,
char *mbstr,
size_t sizeInBytes,
const wchar_t **wcstr,
sizeof count,
mbstate_t *mbstate
);
template <size_t size>
errno_t wcsrtombs_s(
size_t *pReturnValue,
char (&mbstr)[size],
const wchar_t **wcstr,
sizeof count,
mbstate_t *mbstate
); // C++ only
Parameter
pReturnValue
Ukuran dalam byte string yang dikonversi, termasuk terminator null.
mbstr
Alamat buffer untuk string karakter multibyte yang dikonversi yang dihasilkan.
sizeInBytes
Ukuran dalam byte mbstr
buffer.
wcstr
Arahkan ke string karakter lebar yang akan dikonversi.
count
Jumlah maksimum byte yang akan disimpan dalam mbstr
buffer, atau _TRUNCATE
.
mbstate
Penunjuk ke mbstate_t
objek status konversi.
Nilai hasil
Nol jika berhasil, kode kesalahan pada kegagalan.
Kondisi kesalahan | Mengembalikan nilai dan errno |
---|---|
mbstr adalah NULL dan sizeInBytes > 0 |
EINVAL |
wcstr is NULL |
EINVAL |
Buffer tujuan terlalu kecil untuk berisi string yang dikonversi (kecuali count adalah _TRUNCATE ; lihat Keterangan di bawah) |
ERANGE |
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 wcsrtombs_s
mengonversi string karakter lebar yang diacu ke menjadi wcstr
karakter multibyte yang disimpan dalam buffer yang ditujukkan oleh mbstr
, menggunakan status konversi yang terkandung dalam mbstate
. Konversi akan berlanjut untuk setiap karakter hingga salah satu kondisi ini terpenuhi:
Karakter lebar null ditemui
Karakter lebar yang tidak dapat dikonversi ditemui
Jumlah byte yang disimpan dalam
mbstr
buffer sama dengancount
.
String tujuan selalu dihentikan null (bahkan jika ada kesalahan).
Jika count
adalah nilai _TRUNCATE
khusus , maka wcsrtombs_s
mengonversi string sebanyak yang akan masuk ke dalam buffer tujuan, sambil tetap meninggalkan ruang untuk terminator null.
Jika wcsrtombs_s
berhasil mengonversi string sumber, string sumber menempatkan ukuran dalam byte string yang dikonversi, termasuk terminator null, ke dalam *pReturnValue
(disediakan pReturnValue
bukan NULL
). Ukuran dihitung bahkan jika mbstr
argumen adalah NULL
; ini menyediakan cara untuk menentukan ukuran buffer yang diperlukan. Jika mbstr
adalah NULL
, count
diabaikan.
Jika wcsrtombs_s
menemukan karakter lebar yang tidak dapat dikonversi ke karakter multibyte, karakter tersebut menempatkan -1 di *pReturnValue
, mengatur buffer tujuan ke string kosong, mengatur errno
ke EILSEQ
, dan mengembalikan EILSEQ
.
Jika urutan menunjuk ke oleh wcstr
dan mbstr
tumpang tindih, perilaku wcsrtombs_s
tidak terdefinisi. wcsrtombs_s
dipengaruhi oleh kategori LC_TYPE lokal saat ini.
Penting
Pastikan dan wcstr
mbstr
jangan tumpang tindih, dan itu mencerminkan jumlah karakter lebar yang count
akan dikonversi dengan benar.
Fungsi wcsrtombs_s
ini berbeda dari wcstombs_s
, _wcstombs_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-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 wcsrtombs_s
ini aman multithread selama tidak ada fungsi dalam panggilan utas setlocale
saat ini saat fungsi ini dijalankan dan mbstate
null.
Contoh
// crt_wcsrtombs_s.cpp
//
// This code example converts a wide
// character string into a multibyte
// character string.
//
#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>
#define MB_BUFFER_SIZE 100
int main()
{
const wchar_t wcString[] =
{L"Every good boy does fine."};
const wchar_t *wcsIndirectString = wcString;
char mbString[MB_BUFFER_SIZE];
size_t countConverted;
errno_t err;
mbstate_t mbstate;
// Reset to initial shift state
::memset((void*)&mbstate, 0, sizeof(mbstate));
err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
&wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
if (err == EILSEQ)
{
printf( "An encoding error was detected in the string.\n" );
}
else
{
printf( "The string was successfully converted.\n" );
}
}
The string was successfully converted.
Persyaratan
Rutin | Header yang diperlukan |
---|---|
wcsrtombs_s |
<wchar.h> |
Lihat juga
Konversi data
Lokal
Interpretasi urutan karakter multibyte
wcrtomb
wcrtomb_s
wctomb
, _wctomb_l
wcstombs
, _wcstombs_l
mbsinit
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk