wcstombs_s, _wcstombs_s_l

Mengonversi urutan karakter lebar ke urutan karakter multibyte yang sesuai. Versi wcstombs, _wcstombs_l dengan peningkatan keamanan seperti yang dijelaskan dalam Fitur keamanan di CRT.

Sintaks

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count
);

errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);

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

template <size_t size>
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // 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 untuk disimpan dalam mbstr buffer, tidak termasuk karakter null yang mengakhiri, atau _TRUNCATE.

locale
Lokal yang akan digunakan.

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 wcstombs_s mengonversi string karakter lebar yang diacu ke menjadi wcstr karakter multibyte yang disimpan dalam buffer yang ditujukkan oleh mbstr. 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 dengan count.

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

Jika count adalah nilai _TRUNCATEkhusus , maka wcstombs_s mengonversi string sebanyak yang akan masuk ke dalam buffer tujuan, sambil tetap meninggalkan ruang untuk terminator null. Jika string dipotong, nilai yang dikembalikan adalah STRUNCATE, dan konversi dianggap berhasil.

Jika wcstombs_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 wcstombs_s menemukan karakter lebar yang tidak dapat dikonversi ke karakter multibyte, karakter tersebut menempatkan 0 di *ReturnValue, mengatur buffer tujuan ke string kosong, mengatur errno ke EILSEQ, dan mengembalikan EILSEQ.

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

Penting

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

wcstombs_s menggunakan lokal saat ini untuk perilaku yang bergantung pada lokal; _wcstombs_s_l identik dengan wcstombs 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
wcstombs_s	<stdlib.h>

Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Contoh

Program ini menggambarkan perilaku wcstombs_s fungsi.

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

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

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

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE,
               pWCBuffer, (size_t)BUFFER_SIZE - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n", pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
        free(pMBBuffer);
    }
    
    return 0;
}

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

Baca juga

Konversi data
Lokal
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte