Ana sayfa > Programlama > C Programlama > C standart kütüphanesi > <stdio.h> > snprintf

snprintf() fonksiyonu

Bildirim

int snprintf(char *restrict buffer, size_t bufsz, const char *restrict *format, ...); (C99)

int snprintf_s(char *restrict buffer, rsize_t bufsz, const char *restrict *format, ...); (C11)

Açıklama

Bir karakter dizisi içinde format tanımlayıcıları ile tanımlanan değerleri boyutu bufsz parametresi ile tanımlanan bir karakter dizisi içine yazar.

En fazla bufsz-1 kadar karakter yazılır. Sonuçta ortaya çıkan karakter dizisi, bufsz sıfır olmadıkça boş bir karakterle ('\0') sonlandırılır. Eğer bufsz sıfır ise, hiçbir şey yazılmaz ve buffer NULL bir işaretçi olabilir, ancak dönüş değeri hesaplanarak geri döndürülür.

Format parametresi ile gösterilen karakter dizisi içinde yer alan karakterleri normal bir şekilde, % işareti ile başlayan format tanımlayıcılarını ise tanımlanan her bir format tanımlayıcı için, format parametresinden sonra yer alan parametrelerden sıra ile değer okuyarak format karakter dizisini buffer parametresi ile gösterilen karakter dizisine yazar.

Format parametresinde yer alan karakter dizisi buffer parametre dizi genişliğini aşarsa belirsiz sonuçlar yaratabilir.

int snprintf (char buffer, size_t bufsz, const char *format, par1, par2, ...);

Kontrol dizisinin içinde hem normal karakterler hem de % işareti ile başlayan format tanımlayıcıları adı verilen ifadeler yer alabilir. snprintf() fonksiyonu " " işaretleri arasında yer alan normal karakterleri sıra ile ekrana yazar. Kontrol dizisi içinde yer alan her bir format tanımlayıcısı için par ifadesi ile gösterilen bir değer tanımlanır. Ancak, burada dikkat edilmesi gereken 2 önemli nokta vardır:

1. Kontrol dizisi içinde yer alan format tanımlayıcısı kadar par ifadesi ile gösterilen argüman tanımlanmalıdır.

2. Her argümanın veri türü kendisine karşılık gelen format tanımlayıcısının veri türüne uygun olmalıdır.

par ifadesi ile gösterilen argümanlar bir değişken, sabit, ifade veya bir fonksiyon çağrısı olabilir.

Fonksiyon çalışmaya başladığında, önce kontrol dizisi içinde yer alan ilk karaktere bakar. Eğer normal bir karakter ise hemen ekrana yazar. Eğer bir format tanımlayıcısı ise, bu format tanımlayıcısına karşılık gelen ilk argüman değerini ekrana yazar. Kontrol dizisi içindeki bütün karakterleri sıra ile bu şekilde kontrol edip işlem yaptıktan sonra çalışması sona erer.

Format tanımlayıcıları kendilerine karşılık gelen argümanların ekrana nasıl yazılacağını belirler. snprintf() fonksiyonu format tanımlayıcıları ile karşılaştığında ekrana farklı bir veri yazacağını ve bu verinin snprintf() fonksiyonu çağrılırken karakter dizisinden sonra tanımlanmış olan argüman değerlerinden sıra ile alınacağını anlar.

Snprintf_s() fonksiyonu aynı işlemleri yapar. Farklı olarak, ç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:

  • %n format tanımlayıcısı format parametresi ile gösterilen karakter dizisi içinde yer alıyorsa,
  • %s format tanımlayıcısına karşılık gelen parametrelerden herhangi birisi NULL bir işaretçi ise,
  • Buffer veya format parametresi NULL bir işaretçi ise,
  • Bufsz parametresi 0 ise veya RSIZE_MAX değerinden büyük ise,
  • Tespit edilebilen diğer hatalar oluşursa,
  • Buffer parametresine yüklenecek karakter dizisinin boyutu bufsz parametre değerinden büyük olursa.

Parametreler

buffer: Format parametresinde oluşturulan karakter dizisinin yazdırılacağı karakter dizisidir.

bufsz: Buffer parametresine yazdırılabilecek maksimum karakter sayısını gösterir (boş sonlandırıcı karakter dahil).

format: Buffer parametresine yazdırılacak olan bir karakter dizisidir.

Bu karakter dizisi stdout'a yazılacak olan metni içerir. Karakter dizisi içinde normal karakterler veya % karakteri ile başlayan ve format karakter dizisinden sonra gelen parametreler ile doldurulacak olan format tanımlayıcıları yer alabilir.

Format tanımlayıcı genel yapısı :

%[göstergeler][genişlik][.hassasiyet][uzunluk]format tanımlayıcısı

Bir format tanımlayıcısı toplam 6 farklı ifadeden oluşmaktadır. En baştaki % işareti ile en sonda yer alan format tanımlayıcı harfi mutlaka kullanılmalıdır. [] işaretleri arasında yer alan diğer dört ifade isteğe bağlı olarak kullanılır.

Format tanımlayıcısı Karşılığı
c Karakter
d signed int
i signed int
e Bilimsel gösterim
E Bilimsel gösterim
f Ondalıklı sayı
g e ve %f'den kısa olanı kullanır.
G E ve %f'den kısa olanı kullanır.
o unsigned 8'lik sayı
s Karakter dizisi
u unsigned int
x unsigned 16'lık sayı (Küçük harf)
X unsigned 16'lık sayı (Büyük harf)
p İşaretçi
n Karşılık gelen argüman ekrana yazılan karakterlerin sayısının atandığı int bir değeri gösteren bir işaretçi olmalıdır.
% % işaretini ekrana yazar.
Gösterge Karşılığı
- Verilen alan genişliği içerisindeki değerleri sola yaslar. Ön tanımlı değer sağa yaslamadır.
+ Pozitif sayılar da dahil olmak üzere sonuç değerinin önüne artı veya eksi işareti (+ veya -) ekler. Ön tanımlı olarak, yalnızca negatif sayılar önüne - işareti konur.
Boşluk karakteri Hiçbir işaret yazılmayacaksa, değerden önce bir boşluk eklenir.
# o, x veya X format tanımlayıcıları ile kullanıldığında, sıfırdan farklı değerler için değerlerin önüne sırasıyla 0, 0x veya 0X ifadeleri konur. E, E ve f ile birlikte kullanıldığında, ondalık işaretinden sonra değer olmasa bile elde edilen değerin ondalık bir nokta içermesini sağlar. Ön tanımlı olarak, ondalık işaretinden sonra değer yoksa, herhangi bir ondalık basamağı yazılmaz. G veya g ile kullanıldığında, sonuç e veya E ile aynıdır, ancak takip eden sıfırlar kaldırılmaz.
0 Değerin sol tarafında yer alan boşluklar sıfır değeriyle doldurulur.
Genişlik Karşılığı
Sayı Yazdırılacak minimum karakter sayısıdır. Yazdırılacak değer bu sayıdan daha kısaysa, sonuç boşluklarla doldurulur. Sonuç daha büyük olsa bile değer kesilmez.
* Genişlik, format karakter dizisinde belirtilmez, ancak biçimlendirilmesi gereken argümandan önce ek bir tamsayı değeri argümanı olarak belirtilir.
Hassasiyet Karşılığı
.sayı
  • Tamsayı format tanımlayıcıları için (d, i, o, u, x, X) - hassasiyet yazılacak minimum basamak sayısını ifade eder. Yazılacak değer bu sayıdan kısaysa, elde edilen değerin baş tarafı sıfırlarla doldurulur. Sonuç daha uzun olsa bile değer kesilmez. 0 değerinin hassasiyeti, 0 değeri için karakter yazılmadığını gösterir.
  • E, e ve f format tanımlayıcıları için bu değer, ondalık noktadan sonra yazdırılacak basamak sayısını gösterir.
  • G ve g format tanımlayıcıları için bu değer, yazdırılacak maksimum önemli basamak sayısıdır.
  • s format tanımlayıcısı için bu değer yazdırılacak maksimum karakter sayısıdır. Ön tanımlı olarak, boş karakterle ('\0') karşılaşılana kadar tüm karakterler yazdırılır.
  • c format tanımlayıcısı için bu değerin bir etkisi yoktur. Hassasiyet belirtilmediğinde, ön tanımlı değer 1'dir.
.* Hassasiyet, format karakter dizisinde belirtilmez, ancak formatlanması gereken argümandan önce ek bir tamsayı değeri olarak belirtilir.

uzunluk : İsteğe bağlı olarak tanımlanan bu değer okutulacak argümanın boyutunu gösterir. hh, h, l, ll, j, z, t, L değerlerinden biri kullanıldığında, karşılık gelen argümanın gösterdiği veri tipini değiştirir.

Uzunluk değeri Format tanımlayıcısı Okunacak değer
(Yok) c int
s char*
d, i int
u, o, x, X unsigned int
f, F, e, E, a, A, g, G double
n int*
p void*
h d, i short
u, o, x, X unsigned short
n short*
hh (C99) d, i signed char
u, o, x, X unsigned char
n signed char*
j (C99) d, i intmax_t
u, o, x, X uintmax_t
n intmax_t*
l c wint_t
s wchar_t*
d, i long
u, o, x, X unsigned long
f, F, e, E, a, A, g, G double (C99)
n long*
L f, F, e, E, a, A, g, G long double
ll (C99) d, i long long
u, o, x, X unsigned long long
n long long*
t (C99) d, i ptrdiff_t
u, o, x, X unsigned ptrdiff_t
n ptrdiff_t*
z (C99) d, i signed size_t
u, o, x, X size_t
n signed size_t*

... : Format parametresi ile gösterilen karakter dizisinde yer alan ve % karakteri ile başlayan her bir format tanımlayıcı için, format karakter dizisinden sonra bir parametre tanımlanması gerekir.

Dönüş değeri

Snprintf() fonksiyonu buffer parametresine yazılan karakter sayısını int bir değer olarak geri döndürür (sonda yer alan boş karakter hariç ('\0')). Karakter dizisi ve karakter format tanımlayıcılarında bir kodlama hatası meydana gelirse, negatif bir sayı geri döndürür.

Snprintf_s() fonksiyonu buffer parametresine yazılan karakter sayısını int bir değer olarak geri döndürür (sonda yer alan boş karakter hariç ('\0')). Eğer bir çalışma zamanı kısıt ihlal hatası veya bir kodlama hatası oluşursa negatif bir sayı geri döndürür.

Örnek


#include <stdio.h>

int main(void)
{
    int id = 36;
    float fd = 121.45;
    char cdizi[] = "C Programlama Dili";
    char buffer[100];

    snprintf(buffer, 100, "%d %.2f %s\n", id, fd, cdizi);

    printf("Oluşturulan karakter dizisi: %s", buffer);

    return 0;
}

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

Oluşturulan karakter dizisi: 36 121.45 C Programlama Dili

Program, snprintf() fonksiyonu ile birer adet int ve float değer ile ve bir karakter dizisini tek bir karakter dizisi altında toplayarak ekrana yazar.