wcstombs() fonksiyonu

Bildirim

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

size_t wcstombs(char *restrict dest, const wchar_t *restrict src, size_t len); (C99)

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

Açıklama

Src parametresi ile gösterilen geniş bir karakter dizisini çok byte'lı 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 geniş bir karakter boş bir karaktere ('\0') çevrilene kadar devam eder.

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

wcstombs_s() fonksiyonunda ayrıca;

Elde edilen sonuç retval parametresine aktarılır.
Eğer dönüşüm boş bir karakter ('\0') yazmadan durursa, fonksiyon dest parametresinde bir sonraki byte'a (dest[len] veya dest[destsz]) '\0' karakteri yükler.
Eğer dest NULL bir işaretçi ise, elde edilecek byte 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 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 çevirme esnasında src parametresinde NULL veya kodlama hatası ile karşılaşmazsa(dest NULL olmadıkça).

Parametreler

dest: Çoklu byte'a çevrilen karakter dizisinin aktarılacağı dizi işaretçisidir.

src: Çevrilecek olan geniş karakter dizisidir.

len: Dest parametresine yazılacak olan maksimum byte 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

wcstombs() fonksiyonu başarı durumunda, dest parametresine yazılan byte sayısını (sondaki '\0' karakteri hariç) geri döndürür. Geniş karakter geçerli olmayan bir çoklu byte karakterine karşılık geldiğinde -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 '\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>
#include <string.h>

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

    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);
    }

    /* buffer ile gösterilen geniş karakterin boyutunu alma */
	length = mblen (buffer, sizeof(buffer));

    printf("Çoklu byte karakter dizi uzunluğu: %d, karakter uzunluğu: %d", strlen(buffer), length);

    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
Çoklu byte karakter dizi uzunluğu: 10, karakter uzunluğu: 1

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, mblen() fonksiyonu ile çok byte'lı dizinin ilk karakterinin boyutunu ve strlen() fonksiyonu ile dizinin boyutunu alarak ekrana yazar.