`wcsrtombs`

Artikel
10/12/2023

Mengonversi string karakter lebar ke representasi string karakter multibyte-nya. Versi fungsi ini yang lebih aman tersedia; lihat wcsrtombs_s.

Sintaks

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

Parameter

mbstr
Lokasi alamat string karakter multibyte yang dikonversi yang dihasilkan.

wcstr
Secara tidak langsung menunjuk ke lokasi string karakter lebar yang akan dikonversi.

count
Jumlah karakter yang akan dikonversi.

mbstate
Penunjuk ke mbstate_t objek status konversi.

Nilai hasil

Mengembalikan jumlah byte yang berhasil dikonversi, tidak termasuk byte null yang mengakhiri null (jika ada), jika tidak, -1 jika terjadi kesalahan.

Keterangan

Fungsi mengonversi wcsrtombs string karakter lebar, dimulai dalam status konversi yang ditentukan yang terkandung dalam mbstate, dari nilai yang tidak langsung diarahkan ke dalam wcstr, ke alamat mbstr. Konversi akan berlanjut untuk setiap karakter sampai: setelah karakter lebar null berakhir ditemui, ketika karakter yang tidak sesuai ditemui atau ketika karakter berikutnya akan melebihi batas yang terkandung dalam count. Jika wcsrtombs menemukan karakter null karakter lebar (L'\0') baik sebelum atau ketika count terjadi, karakter tersebut akan mengonversinya menjadi 0 8-bit dan berhenti.

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

Fungsi wcsrtombs ini berbeda dari wcstombs, _wcstombs_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 wcsnlen, jika panggilan berikutnya digunakan wcsrtombs alih-alih wcstombs.

mbstr Jika argumen adalah NULL, wcsrtombs mengembalikan ukuran yang diperlukan dalam byte string tujuan. Jika mbstate null, status konversi internal mbstate_t digunakan. Jika urutan wchar karakter tidak memiliki representasi karakter multibyte yang sesuai, -1 dikembalikan, dan errno diatur ke EILSEQ.

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

Contoh

// crt_wcsrtombs.cpp
// compile with: /W3
// 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;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfuly converted.\n" );
    }
}

The string was successfuly converted.

Persyaratan

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

Bagikan melalui