`mbrtowc`

Artikel
10/12/2023

Konversikan karakter multibyte di lokal saat ini menjadi karakter lebar yang setara, dengan kemampuan memulai ulang di tengah karakter multibyte.

Sintaks

size_t mbrtowc(
   wchar_t *wchar,
   const char *mbchar,
   size_t count,
   mbstate_t *mbstate
);

Parameter

wchar
Alamat karakter lebar untuk menerima string karakter lebar yang dikonversi (jenis wchar_t). Nilai ini bisa menjadi penunjuk null jika tidak ada karakter lebar pengembalian yang diperlukan.

mbchar
Alamat urutan byte (karakter multibyte).

count
Jumlah byte yang akan diperiksa.

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

Nilai hasil

Salah satu dari nilai berikut:

0 Byte berikutnya count atau lebih sedikit menyelesaikan karakter multibyte yang mewakili karakter lebar null, yang disimpan dalam wchar, jika wchar bukan penunjuk null.

1 hingga count, inklusif Byte berikutnya count atau lebih sedikit menyelesaikan karakter multibyte yang valid. Nilai yang dikembalikan adalah jumlah byte yang menyelesaikan karakter multibyte. Karakter lebar yang setara disimpan di wchar, jika wchar bukan penunjuk null.

(size_t) (-1) Terjadi kesalahan pengodean. Byte berikutnya count atau lebih sedikit tidak berkontribusi pada karakter multibyte yang lengkap dan valid. Dalam hal ini, errno diatur ke EILSEQ dan status pergeseran konversi dalam mbstate tidak ditentukan.

(size_t) (-2) Byte berikutnya count berkontribusi pada karakter multibyte yang tidak lengkap tetapi berpotensi valid, dan semua count byte telah diproses. Tidak ada nilai yang disimpan di , tetapi mbstate diperbarui wcharuntuk memulai ulang fungsi.

Keterangan

Jika mbchar adalah penunjuk null, fungsi setara dengan panggilan:

mbrtowc(NULL, "", 1, &mbstate)

Dalam hal ini, nilai wchar argumen dan count diabaikan.

Jika mbchar bukan penunjuk null, fungsi memeriksa count byte dari mbchar untuk menentukan jumlah byte yang diperlukan yang diperlukan untuk menyelesaikan karakter multibyte berikutnya. Jika karakter berikutnya valid, karakter multibyte yang sesuai disimpan jika wchar bukan penunjuk null. Jika karakter adalah karakter null lebar yang sesuai, status yang dihasilkan adalah mbstate status konversi awal.

Fungsi mbrtowc ini berbeda dari mbtowc, _mbtowc_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 wcsrlen alih-alih wcslen jika panggilan berikutnya digunakan wcsrtombs alih-alih wcstombs.

Secara default, status global fungsi ini dicakup ke aplikasi. Untuk mengubah perilaku ini, lihat Status global di CRT.

Contoh

Mengonversi karakter multibyte ke karakter lebar yang setara.

// crt_mbrtowc.cpp

#include <stdio.h>
#include <mbctype.h>
#include <string.h>
#include <locale.h>
#include <wchar.h>

#define BUF_SIZE 100

int Sample(char* szIn, wchar_t* wcOut, int nMax)
{
    mbstate_t   state = {0}; // Initial state
    size_t      nConvResult,
                nmbLen = 0,
                nwcLen = 0;
    wchar_t*    wcCur = wcOut;
    wchar_t*    wcEnd = wcCur + nMax;
    const char* mbCur = szIn;
    const char* mbEnd = mbCur + strlen(mbCur) + 1;
    char*       szLocal;

    // Sets all locale to French_Canada.1252
    szLocal = setlocale(LC_ALL, "French_Canada.1252");
    if (!szLocal)
    {
        printf("The fuction setlocale(LC_ALL, \"French_Canada.1252\") failed!\n");
        return 1;
    }

    printf("Locale set to: \"%s\"\n", szLocal);

    // Sets the code page associated current locale's code page
    // from a previous call to setlocale.
    if (_setmbcp(_MB_CP_SBCS) == -1)
    {
        printf("The fuction _setmbcp(_MB_CP_SBCS) failed!");
        return 1;
    }

    while ((mbCur < mbEnd) && (wcCur < wcEnd))
    {
        //
        nConvResult = mbrtowc(wcCur, mbCur, 1, &state);
        switch (nConvResult)
        {
            case 0:
            {  // done
                printf("Conversion succeeded!\nMultibyte String: ");
                printf(szIn);
                printf("\nWC String: ");
                wprintf(wcOut);
                printf("\n");
                mbCur = mbEnd;
                break;
            }

            case -1:
            {  // encoding error
                printf("The call to mbrtowc has detected an encoding error.\n");
                mbCur = mbEnd;
                break;
            }

            case -2:
            {  // incomplete character
                if   (!mbsinit(&state))
                {
                    printf("Currently in middle of mb conversion, state = %x\n", state);
                    // state will contain data regarding lead byte of mb character
                }

                ++nmbLen;
                ++mbCur;
                break;
            }

            default:
            {
                if   (nConvResult > 2) // The multibyte should never be larger than 2
                {
                    printf("Error: The size of the converted multibyte is %d.\n", nConvResult);
                }

                ++nmbLen;
                ++nwcLen;
                ++wcCur;
                ++mbCur;
            break;
            }
        }
    }

   return 0;
}

int main(int argc, char* argv[])
{
    char    mbBuf[BUF_SIZE] = "AaBbCc\x9A\x8B\xE0\xEF\xF0xXyYzZ";
    wchar_t wcBuf[BUF_SIZE] = {L''};

    return Sample(mbBuf, wcBuf, BUF_SIZE);
}

Sampel output

Locale set to: "French_Canada.1252"
Conversion succeeded!
Multibyte String: AaBbCcÜïα∩≡xXyYzZ
WC String: AaBbCcÜïα∩≡xXyYzZ

Persyaratan

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