mbstowcs() fonksiyonu

Bildirim

size_t mbstowcs(wchar_t *dest, const char *src, size_t len);

size_t mbstowcs(wchar_ *restrict dest, const char *restrict src, size_t len); (C99)

errno_t mbstowcs_s(size_t *restrict retval, wchar_t *restrictdest, rsize_t destsz, const char *restrict src, rsize_t len); (C11)

Açıklama

Src parametresi ile gösterilen çok byte'lı karakter dizisini geniş bir karakter dizisine çevirerek dest parametresi ile gösterilen adrese aktarır. Bu işlem en fazla len parametre değeri ile gösterilen uzunlukta veya src parametresi içinde boş bir karakterle ('\0') karşılaşılana kadar devam eder.

Eğer len parametre değeri kadar karakter çevrilirse, dest parametresine aktarılan karakter dizisinin sonunda boş karakter ('\0') yer almaz.

mbstowcs_s() fonksiyonunda ayrıca;

Elde edilen sonuç retval parametresine aktarılır.
Eğer len parametre değeri kadar geniş karakter yazıldıktan sonra dest parametresine boş bir karakter ('\0') yazılmazsa, L'\0' değeri dest[len] adresine yazılır.
Eğer dest NULL bir işaretçi ise, elde edilecek geniş karakter sayısı retval parametresine yüklenir.
Eğer src ve dest parametreleri çakışırsa, belirsiz sonuçlar ortaya çıkar.

Ayrıca, çalışma zamanında aşağıdaki hatalar tespit edildiğinde, yüklenmiş olan kısıtlayıcı işlem fonksiyonu çağrılır:

Retval veya src parametre değeri NULL bir işaretçi ise,
Destsz veya len parametre değeri RSIZE_MAX/sizeof(wchar_t) değerinden büyük ise (dest NULL olmadıkça),
Destsz parametre değeri 0 değil ise (dest NULL olmadıkça),
Len parametre değeri destsz parametre değerinden büyük ise ve src parametresi içinde destsize kadar ilk çoklu byte karakterleri içinde boş bir karakter yoksa (dest NULL olmadıkça).

Parametreler

dest: Geniş karaktere çevrilen karakter dizisinin aktarılacağı dizi işaretçisidir.

src: Çevrilecek olan çoklu byte karakter dizisini gösteren bir işaretçidir.

len: Dest parametresindeki dizide bulunan geniş karakter sayısıdır.

destsz: Dest parametresi ile gösterilen dizi boyutudur.

retval: Sonuçların aktarılacağı size_t türünden bir işaretçidir.

Dönüş değeri

mbstowcs() fonksiyonu başarı durumunda, dest parametresine yazılan geniş karakter sayısını (sondaki L'\0' karakteri hariç) geri döndürür. Çevirme hatası oluştuğunda yani geçersiz bir çoklu byte karakteri ile karşılaşıldığında, -1 değeri geri döndürür.

wcstombs_s() fonksiyonu başarı durumunda 0 değeri, hata durumunda ise sıfır olmayan bir değer geri döndürür. Bir çalışma zamanı kısıtlaması ihlali durumunda, retval parametresi NULL değilse, retval parametresine -1 değeri ve dest[0] adresine L'\0' karakteri yükler (dest NULL olmadıkça veya destsz sıfır veya RSIZE_MAX'tan büyük değilse).

Örnek


#include <stdio.h>
#include <stdlib.h>

int main(void) {
    const wchar_t cwdizi[] = L"Bilgisayar";
    char buffer[40];
    wchar_t wbuffer[40];
    int ret;

    printf ("Geniş karakter dizisi: %ls\n", cwdizi);

    /* Geniş karakter dizisini çoklu byte diziye çevirme */
    ret = wcstombs (buffer, cwdizi, sizeof(buffer));
    if (ret) {
        printf("Çoklu byte karakter dizisi: %s\n", buffer);
        printf("Çevrilen karakter sayısı: %d\n", ret);
    }

    /* Çoklu byte karakter dizisini geniş karakter dizisine çevirme */
    ret = mbstowcs (wbuffer, buffer, sizeof(wbuffer));
    if (ret) {
        printf("Geniş karakter dizisi: %ls\n", wbuffer);
        printf("Çevrilen karakter sayısı: %d\n", ret);
    }

    return 0;
}

Yukarıdaki örnekte, program aşağıdaki satırları ekrana yazar:

Geniş karakter dizisi: Bilgisayar
Çoklu byte karakter dizisi: Bilgisayar
Çevrilen karakter sayısı: 10
Geniş karakter dizisi: Bilgisayar
Çevrilen karakter sayısı: 10

Yukarıdaki program, geniş bir karakter dizisini ekrana yazdıktan sonra wcstombs() fonksiyonu ile çoklu byte dizisine çevirir. Çevrilen diziyi ve çevrilen karakter sayısını ekrana yazar. Daha sonra, mbstowcs() fonksiyonu ile yaptığı işlemin tersini yaparak elde ettiği değerleri tekrar ekrana yazar.