Dizge Dönüşümleri

Önceki bölümde bahsedilen işlevler bir defada sadece tek bir karakteri dönüştürmek içindi. Gerçekte uygulanan çoğu işlem dizgeler üzerinde yapılır ve ISO C standardı dizgelerin tamamının dönüşümlerini de tanımlamıştır. Bununla birlikte, tanımlı işlevler bazı sınırlamalara sahiptir; ancak, GNU C kütüphanesi bazı önemli durumlarda yardımcı olabilecek bazı genişletmeler içerir.

size_t mbsrtowcs

(wchar_t *restrict     hedef,
 const char **restrict kaynak,
 size_t                uzunluk,
 mbstate_t *restrict   ps)

işlev

mbsrtowcs işlevi ("multibyte string restartable to wide character string" kısaltması) *kaynak içindeki boş karakter sonlandırmalı çokbaytlı karakter dizgesini eşdeğer geniş karakter dizgesine dönüştürür. Dönüşüm, ps ile gösterilen nesnedeki ya da ps bir boş gösterici ise mbsrtowcs içindeki dahili durum bilgisi kullanılarak başlatılır. İşlev dönmeden önce, durum nesnesi son karakter dönüştürüldükten sonraki durumla güncellenir. Sonlandırıcı boş karakter işlenmişse durum, ilk durum olur.

hedef bir boş gösterici değilse, sonuç mbsrtowcs ile gösterilen dizide saklanır; aksi takdirde, dönüşüm sonucu bir iç tamponda saklanmış olacağından sonuç kullanılabilir olmayacaktır.

hedef dizgesi uzunluk geniş karakterlik olarak belirlenmişse, girdi dizgesinin dönüştürülen kısmı uzunluk geniş karakterlik olduğunda dönüşüm durdurulur ve uzunluk döner. hedef bir boş dizge ise uzunluk anlamlı değildir.

Eksik dönüşümlü bir dönüşün sebeplerinden biri de girdi dizgesinin geçersiz çokbaytlı dizilim içermesidir. Bu durumda errno genel değişkenine EILSEQ değeri atanarak işlev, (size_t) -1 ile döner.

Tüm diğer durumlarda işlev, bu çağrı ile dönüştürülmüş geniş karakterlerin sayısı ile döner. hedef boş değilse, mbsrtowcs işlevi kaynak ile ya bir boş gösterici (girdi dizgesinde boş karaktere erişilmişse) ya da son dönüştürülen çokbaytlı karakterden sonraki baytın adresini döndürür.

mbsrtowcs işlevi ISO C90 standardının 1. düzeltmesinde tanımlanmış ve wchar.h başlık dosyasında bildirilmiştir.

mbsrtowcs işlevinin tanımı önemli bir sınırlama içerir. hedef'in bir boş karakter sonlandırmalı dizge içermesi gereksinimi metin içeren tamponlarda dönüştürme yapmak isterseniz sorunlara sebep olur. Bir tampon normalde, boş karakter sonlandırmalı dizgeler değil, herbiri satırsonu karakteri ile biten satırlar içerir. Şimdi bir işlevin tampon içindeki satırlardan birini dönüştürmesini istediğimizi varsayalım. Satır boş karakterle bitmediğinden kaynak gösterici değiştirilmemiş metin tamponunu doğrudan gösteremez. Bunun anlamı: Ya mbsrtowcs çağrısı sırasında uygun bir yere boş karakter yerleştirilmeli (bu, salt okunur tamponlarda ve çok evreli uygulamalarda yapılamaz) ya da satır, boş karakterle sonlandırılmış olarak başka bir tampona kopyalanmalıdır. uzunluk parametresine belli bir değer atayarak dönüştürülecek karakterlerin sayısını sınırlamak genellikle mümkün değildir. Her çokbaytlı karakterin kaç bayttan oluştuğu bilinemediğinden sadece tahmin yapılabilir.

Satırsonu karakterinden sonra bir boş karakter koyarak satırın sonlandırılması ile ilgili olarak çok tuhaf sonuçlara sebep olan bir sorun hala mevcuttur. Yukarıda mbsrtowcs işlevinin açıklamasında bahsedildiği gibi girdi dizgesinin sonundaki boş karakter işlendikten sonra durumun ilk öteleme durumu olacağı garanti edilmiştir. Fakat bu boş karakter gerçekte metnin bir parçası değildir (yani, orjinal metinde satırsonu karakterinden sonraki dönüşüm durumu ilk öteleme durumundan farklı olacaktı ve sonraki satırın ilk karakteri bu durum kullanarak kodlanacaktı). Diğer taraftan, dönüşüm boş baytta duracağından (öteleme durumu sıfırlanacağından) gerçekte olması gereken durum bilgisi kaybolacaktır. Günümüzdeki çoğu karakter kümesi bir satırsonu karakterinden sonraki öteleme durumunun ilk durum olmasını gerektirse de bu kesin bir garanti değildir. Basitçe, metnin üzerinde çalışılan parçasının boş karakterle sonlandırılması her zaman uygun bir çözüm değildir ve genellikle hiç kullanılmaz.

Soysal dönüşüm arayüzü (Soysal Karakter Kümesi Dönüşümü) bu sınırlamaya sahip değildir (basitçe tamponlarla çalışır, dizgelerle değil) ve GNU C kütüphanesi girdi dizgesinde işlenecek baytların azami sayısının belirtilebildiği ek parametreler alan işlevler içerir. Bu yolla, mbsrtowcs işlevinin yukarıdaki örneğindeki sorun, satır uzunluğu saptanıp bu uzunluk işleve aktarılarak çözülebilir.

size_t wcsrtombs

(char *restrict           hedef,
 const wchar_t **restrict kaynak,
 size_t                   uzunluk,
 mbstate_t *restrict      ps)

işlev

wcsrtombs işlevi ("wide character string restartable to multibyte string" kısaltması) boş karakter sonlandırmalı bir geniş karakter dizgesi olan *kaynak'ı eşdeğeri olan çokbaytlı karaktere dönüştürür ve sonucu hedef ile gösterilen dizide saklar. Boş geniş karakter ayrıca dönüştürülür. Dönüşüm, ps ile gösterilen nesnedeki ya da ps bir boş gösterici ise wcsrtombs içindeki dahili durum bilgisi kullanılarak başlatılır. hedef bir boş gösterici ise dönüşüm yine yapılır ama sonuç döndürülmez. Girdi dizgesindeki tüm karakterler dönüşütürülmüşse ve hedef bir boş gösterici değilse kaynak göstericisi bir boş gösterici olarak döner.

Geniş karakterlerden birinin geçerli bir çokbaytlı karakter eşdeğeri yoksa dönüşüm durdurulur ve errno genel değişkenine EILSEQ değeri atanarak işlev (size_t) -1 ile döner.

İşlemin eksik kalmasına başka bir sebep de hedef'in bir boş karakter olmadığı durumda dönüştürülecek karakterin uzunluk bayttan fazlasını gerektirmesidir. Bu durumda kaynak başarıyla dönüştürülmüş son karakterden sonraki karakteri gösterecek bir gösterici olarak döner.

Bir kodlama hatası dışında wcsrtombs işlevinin dönüş değeri hedef içinde saklanan çokbaytlı karakterlerin toplam bayt sayısıdır. İşlev dönmeden önce, durum nesnesi son karakter dönüştürüldükten sonraki durumla güncellenir. Sonlandırıcı boş geniş karakter işlenmişse durum, ilk durum olur.

The wcsrtombs işlevi ISO C90 standardının 1. düzeltmesinde tanımlanmış ve wchar.h başlık dosyasına bildirilmiştir.

Yukarıda mbsrtowcs işlevi ile ilgili sınırlama bu işlevde de geçerlidir. Girdi karakterlerinin sayısını doğrudan belirlemek mümkün değildir. Ya doğru yere bir boş geniş karakter yerleştirilmeli ya da girdi uzunluğu dolaylı olarak çıktı dizgesinin uzunluğu (uzunluk parametresi) sınanarak saptanmalıdır.

size_t mbsnrtowcs

(wchar_t *restrict     hedef,
 const char **restrict kaynak,
 size_t                nmc,
 size_t                uzunluk,
 mbstate_t *restrict   ps)

işlev

İşlev, mbsrtowcs işlevine çok benzer. nmc parametresi dışında tüm parametreler ve işlevin dönüş durumu aynıdır.

nmc parametresi ile çokbaytlı karakter dizgesinin en çok kaç baytının kullanılacağı belirtilir. Başka bir deyişle, *kaynak çokbaytlı karakter dizisinin boş karakter sonlandırmalı olması gerekli değildir. Fakat dizge içinde ilk nmc karakter içinde bir boş karaktere rastlanırsa dönüşüm orada durur.

Bu işlev bir GNU oluşumudur. Amacı yukarıda belirtilen sorunun etrafından dolanmaktır. Böylece çokbaytlı karakterler içeren bir tamponun dönüştürülmesi boş karakter yerleştirmeden ve boş karakter dönüşüm durumunu etkilemeksizin mümkün olur.

Bir çokbaytlı karakter dizgesini bir geniş karakter dizgesine dönüştürecek ve gösterecek bir işlev şöyle yazılabilir (bu kullanılabilir bir örnek değildir):

void
showmbs (const char *src, FILE *fp)
{
  mbstate_t state;
  int cnt = 0;
  memset (&state, '\0', sizeof (state));
  while (1)
  {
    wchar_t linebuf[100];
    const char *endp = strchr (src, '\n');
    size_t n;

    /* Başka satır yoksa çık.  */
    if (endp == NULL)
      break;

    n = mbsnrtowcs (linebuf, &src, endp - src, 99, &state);
    linebuf[n] = L'\0';
    fprintf (fp, "line %d: \"%S\"\n", linebuf);
  }
}

mbsnrtowcs çağrısından sonra durumla ilgili bir sorun çıkmaz. Dizgelere dışarıdan bir karakter yerleştirmediğimizden state durumunu sadece verilen tamponu dönüştürmek için kullandık. Durumun değişmesiyle ilgili bir sorun yaşamadık.

size_t wcsnrtombs

(char *restrict           hedef,
 const wchar_t **restrict kaynak,
 size_t                   nwc,
 size_t                   uzunluk,
 mbstate_t *restrict      ps)

işlev

wcsnrtombs işlevi geniş karakter dizgesini çokbaytlı karakter dizgesine dönüştürmekte kullanılır. wcsrtombs işlevine benzemekle birlikte mbsnrtowcs işlevi gibi girdi dizgesinin uzunluğunun belirtilebildiği bir ek parametre alır.

*kaynak dizgesinin sadece ilk nwc geniş karakteri dönüştürülür. Bu parça içinde bir boş karaktere rastlanırsa dönüşüm bu karakterde durdurulur.

wcsnrtombs işlevi bir GNU oluşumudur ve mbsnrtowcs işlevi gibi boş karakter içermeyen dizgelerin dönüştürülmesinde yararlı olur.