Syntaxe specifikace formátu: printf a wprintf funkce

Různé printf funkce wprintf mají formátovací řetězec a volitelné argumenty a vytvoří formátovanou sekvenci znaků pro výstup. Formátovací řetězec obsahuje nulové nebo více direktiv, které jsou buď literální znaky pro výstupní nebo kódované specifikace převodu, které popisují formátování argumentu ve výstupu. Tento článek popisuje syntaxi použitou ke kódování specifikací převodu ve formátovacím řetězci. Seznam těchto funkcí najdete v tématu Vstupně-výstupní operace streamu.

Specifikace převodu se skládá z volitelných a požadovaných polí v tomto formuláři:

%[flags][width][.precision][size]type

Každé pole specifikace převodu je znak nebo číslo, které označuje konkrétní možnost formátu nebo specifikátor převodu. Pole požadovaného typu určuje typ převodu, který se má použít u argumentu. Volitelné příznaky, šířka a přesnost polí řídí další aspekty formátu, jako jsou úvodní mezery nebo nuly, odůvodnění a zobrazená přesnost. Pole velikost určuje velikost spotřebovaného a převedeného argumentu.

Základní specifikace převodu obsahuje pouze znak procenta a znak typu . %s Například určuje převod řetězce. Pro výpis znaku procent je třeba použít %%. Pokud za znakem procenta následuje znak, který nemá žádný význam jako pole formátu, vyvolá se neplatná obslužná rutina parametru. Další informace najdete v tématu Ověření parametru.

Důležité

Kvůli zabezpečení a stabilitě se ujistěte, že řetězce specifikace převodu formátu nejsou definované koncovým uživatelem. Zvažte například program, který vyžaduje od uživatele zadání jména a ukládá vstup do proměnné řetězce s názvem user_name. Pokud chcete tisknout user_name, nikdy to neudělejte:

printf( user_name ); /* Danger! If user_name contains "%s", program will crash */

Místo toho je lepší použít:

printf( "%s", user_name );

Poznámka:

V sadě Visual Studio 2015 Byly printf deklarovány a přesunuty inline <stdio.h> do hlaviček <conio.h> a scanf funkcí. Pokud migrujete starší kód, může se zobrazit LNK2019 v souvislosti s těmito funkcemi. Další informace najdete v tématu Historie změn v jazyce Visual C++ 2003 – 2015.

Specifikátor převodu typů

Specifikátor typu určuje, zda má být interpretován odpovídající argument jako znak, řetězec, ukazatel, celé číslo nebo číslo s plovoucí desetinnou čárkou. Znak typu je jediné požadované pole specifikace převodu a zobrazí se za libovolnými volitelnými poli.

Argumenty, které následují za formátovacím řetězcem, se interpretují podle odpovídajícího znaku typu a volitelné předpony velikosti. Převody pro typy char znaků a wchar_t jsou určeny pomocí c nebo C, a jednobajtů a vícebajtů nebo široké znakové řetězce jsou určeny pomocí s nebo S, v závislosti na tom, která funkce formátování se používá. Znakové a řetězcové argumenty, které jsou určeny pomocí c a s jsou interpretovány jako char* char a podle printf funkcí rodiny, nebo jako wchar_t a wchar_t* podle wprintf funkcí rodiny. Znakové a řetězcové argumenty, které jsou určeny pomocí C a S jsou interpretovány jako wchar_t* wchar_t a podle printf funkcí rodiny, nebo jako char a char* podle wprintf funkcí rodiny. Toto chování je specifické pro Microsoft. Z historických důvodů wprintf funkce používají c a s odkazují na wchar_t znaky a C S určují úzké znaky.

Celočíselné typy, jako shortjsou , int, long, long longa jejich unsigned varianty, jsou určeny pomocí d, i, o, , ua xX. Typy s plovoucí desetinou čárkou, jako floatjsou , doublea long double, jsou určeny pomocí a, A, , Ee, , fF, , ga G. Ve výchozím nastavení platí, že pokud nejsou upraveny předponou velikosti , celočíselné argumenty se přetypují na int typ a argumenty s plovoucí desetinou čárkou se přepojí na double. V 64bitových systémech int je 32bitová hodnota. Proto se 64bitové celá čísla zkrátí, když se naformátují pro výstup, pokud se nepoužije předpona ll velikosti nebo I64 se použije. Typy ukazatelů, které jsou určeny p pomocí výchozí velikosti ukazatele pro platformu.

Poznámka:

Specifické pro Microsoft:
Znak Z typu a chování znaku c, C, sa S typ znaků při jejich použití s printf funkcemi wprintf , jsou rozšíření Microsoftu. Standard ISO C používá c a s konzistentně pro úzké znaky a řetězce a S C pro široké znaky a řetězce ve všech funkcích formátování.

Znaky pole typu

Typ znaku	Argument	Výstupní formát
c	Znak	Při použití s funkcemi printf určuje jednobajtů znak; při použití s funkcemi wprintf určuje široký znak.
C	Znak	Při použití s funkcemi printf určuje široký znak; při použití s funkcemi wprintf určuje jeden bajtový znak.
d	Celé číslo	Celé číslo s desetinnou čárkou.
i	Celé číslo	Celé číslo s desetinnou čárkou.
o	Celé číslo	Celé číslo bez znaménka
u	Celé číslo	Celé číslo bez znaménka
x	Celé číslo	Bez znaménka šestnáctkového celého čísla; používá "abcdef".
X	Celé číslo	Bez znaménka šestnáctkového celého čísla; používá "ABCDEF".
e	Plovoucí desetiná čárka	Podepsaná hodnota, která má tvar [-]d.dddde[-+|]dd[d], kde d je jedna desetinná číslice, dddd je jedna nebo více desetinných číslic v závislosti na zadané přesnosti nebo šesti ve výchozím nastavení a dd[d] je dvě nebo tři desetinná číslice v závislosti na výstupním formátu a velikosti exponentu.
E	Plovoucí desetiná čárka	Shodný s formátem e kromě toho, že E místo e zavedení exponentu.
f	Plovoucí desetiná čárka	Podepsaná hodnota, která má tvar [-]dddd.dddd, kde dddd je jedna nebo více desetinných číslic. Počet číslic před desetinnou čárkou závisí na velikosti čísla a počet číslic za desetinnou čárkou závisí na požadované přesnosti nebo šesti ve výchozím nastavení.
F	Plovoucí desetiná čárka	Shodný s formátem s tím rozdílem f , že nekonečno a výstup NaN je velkými písmeny.
g	Plovoucí desetiná čárka	Podepsané hodnoty se zobrazují ve formátu nebo e ve f formátu, podle toho, která zkomprimuje danou hodnotu a přesnost. Formát e se používá pouze v případech, kdy je exponent hodnoty menší než -4 nebo větší nebo roven argumentu přesnosti . Koncové nuly jsou zkráceny a desetinná čárka se zobrazí pouze v případě, že za ní následuje jedna nebo více číslic.
G	Plovoucí desetiná čárka	Shodný s g formátem s tím rozdílem, že Emísto etoho zavádí exponent (pokud je to vhodné).
a	Plovoucí desetiná čárka	Znaky šestnáctkové dvojité přesnosti s plovoucí desetinnou čárkou s plovoucí desetinnou čárkou, která má tvar [-]0xhhhhp[-+|]dd, kde h.hhhh jsou šestnáctkové číslice (s použitím malých písmen) mantisy a dd jsou jedna nebo více číslic pro exponent. Přesnost určuje počet číslic za bodem.
A	Plovoucí desetiná čárka	Hexadecimální hodnota s plovoucí desetinnou čárkou s dvojitou přesností s dvojitou přesností, která má tvar [-]0XhhhhP[-+|]dd, kde h.hhhh jsou šestnáctkové číslice (pomocí velkých písmen) mantisy a dd jsou jedna nebo více číslic exponentu. Přesnost určuje počet číslic za bodem.
n	Ukazatel na celé číslo	Počet znaků, které se zatím úspěšně zapisují do datového proudu nebo vyrovnávací paměti Tato hodnota je uložena v celé číslo, jehož adresa je uvedena jako argument. Velikost celého čísla, na které ukazuje, může být řízena předponou specifikace velikosti argumentu. Specifikátor n je ve výchozím nastavení zakázaný. Informace najdete v důležité poznámce k zabezpečení.
p	Typ ukazatele	Zobrazí argument jako adresu v šestnáctkových číslicích.
s	String	Při použití s funkcemi printf určuje řetězec jednobajtů nebo vícebajtů. Při použití s funkcemi wprintf určuje řetězec širokého znaku. Znaky se zobrazí až do prvního znaku null nebo dokud nedosáhne hodnoty přesnosti .
S	String	Při použití s funkcemi printf určuje řetězec širokého znaku; při použití s funkcemi wprintf určuje řetězec jednobajtů nebo vícebajtů. Znaky se zobrazí až do prvního znaku null nebo dokud nedosáhne hodnoty přesnosti .
Z	ANSI_STRING nebo UNICODE_STRING struktura	VS 2013 a starší Pokud je adresa objektu ANSI_STRING nebo UNICODE_STRING struktury předána jako argument, zobrazte řetězec obsažený ve vyrovnávací paměti odkazující na Buffer pole struktury. K zadání argumentu použijte předponu w modifikátoru UNICODE_STRING velikosti, %wZnapříklad . Pole Length struktury musí být nastaveno na délku řetězce v bajtech. Pole MaximumLength struktury musí být nastaveno na délku vyrovnávací paměti v bajtech. Universal C Runtime (UCRT) V UCRT je známý problém, který se v současné době udržuje kvůli kompatibilitě. S Stejně jako specifikátor Z se specifikátor bez předpony modifikátoru velikosti označuje UNICODE_STRING při použití úzké tiskové funkce (napříkladprintf) a ANSI_STRING při použití široké tiskové funkce (napříkladwprintf). Místo , Zpoužít hZ k určení .ANSI_STRING wZ(nebolZ) lze stále použít k určení .UNICODE_STRING Z Znak typu se obvykle používá pouze v funkcích ladění ovladačů, které používají specifikaci převodu, například dbgPrint a kdPrint.

V sadě Visual Studio 2015 a novějších verzích je argument odpovídající specifikátoru převodu s plovoucí desetinnou čárkou (a, A, e, Ef, , F, , ) gGnekonečný, neurčitý nebo naN, formátovaný výstup odpovídá standardu C99. Tato tabulka obsahuje formátovaný výstup:

Hodnota	Výstup
Infinity	inf
Quiet NaN	nan
Signaling NaN	nan(snan)
Neurčené nan	nan(ind)

Každý z těchto řetězců může mít předponu znaménko. Pokud je specifikátorem převodu typu s plovoucí desetinou čárkou velké písmeno, výstup je také formátován velkými písmeny. Pokud je %F například specifikátor formátu namísto %f, je nekonečno formátováno jako INF místo inf. Funkce scanf můžou tyto řetězce také analyzovat, takže tyto hodnoty můžou provést odezvu printf a scanf funkce.

Před sadou Visual Studio 2015 použil CRT jiný nestandardní formát pro výstup nekonečných, nekonečných a neneurčitých hodnot NaN:

Hodnota	Výstup
+ Nekonečno	1.#INFnáhodná číslice
-Nekonečno	-1.#INFnáhodná číslice
Neomezená (stejná jako tichá naN)	číslice .#IND s náhodnými číslicemi
Není číslo	číslice .#NAN s náhodnými číslicemi

Některé z těchto řetězců můžou mít předponu znaménko a můžou být formátované odlišně v závislosti na šířce a přesnosti pole, někdy s neobvyklými efekty. Vytiskne 1.#J se například proto, printf("%.2f\n", INFINITY) že #INF bude zaokrouhleno na dvě číslice přesnosti.

Poznámka:

Pokud argument odpovídající %s argumentu nebo %SBuffer poli argumentu, který odpovídá %Z, je null ukazatel, "(null)" se zobrazí.

Poznámka:

Ve všechexpoch _set_output_format Pomocí funkce můžete nastavit počet číslic zobrazených na tři pro zpětnou kompatibilitu s kódem napsaným pro Visual Studio 2013 a před tím.

Důležité

Vzhledem k tomu, že formát %n je ze své podstaty nezabezpečený, je ve výchozím nastavení zakázaný. Pokud %n se v řetězci formátu zjistí, vyvolá se neplatná obslužná rutina parametru, jak je popsáno v ověření parametru. Pokud chcete povolit %n podporu, přečtěte si téma _set_printf_count_output.

Direktivy příznaku

První volitelné pole ve specifikaci převodu obsahuje direktivy příznaku. Toto pole obsahuje nula nebo více znaků příznaku, které určují výstupní odůvodnění a řídí výstup značek, prázdných hodnot, počátečních nul, desetinných míst a osmičkových a šestnáctkových předpon. Ve specifikaci převodu se může objevit více než jedna direktiva příznaku a znaky příznaku se můžou objevit v libovolném pořadí.

Znaky příznaku

Příznak	Význam	Výchozí
-	Výsledek zarovnejte doleva v rámci dané šířky pole.	Zarovnání doprava
+	Pokud se jedná o typ podpisu, použijte znaménko (+ nebo -) k předponě výstupní hodnoty.	Znaménko se zobrazí pouze pro záporné hodnoty se znaménkem (-).
0	Pokud je šířka předponou 0, počáteční nuly se přidají, dokud nedosáhnete minimální šířky. Pokud se zobrazí obojí 0 a - zobrazí se, 0 bude ignorován. Je-li 0 zadán pro celočíselné formátování (i, u, xX, , o, d) a specifikace přesnosti je také přítomna – například %04.d– 0 bude ignorována. Pokud 0 je zadán pro a formát s A plovoucí desetinou čárkou, počáteční nuly jsou před mantisou za předponou nebo 0X předponou0x.	Žádné odsazení.
blank (' ')	Pokud je hodnota výstupu podepsaná a kladná, použijte prázdnou hodnotu. Prázdná hodnota se ignoruje, pokud se zobrazí prázdné i + příznaky.	Nezobrazí se žádná prázdná hodnota.
#	Pokud se používá s příznakem , nebo formátem, # použije 00xpříznak , nebo 0X, v uvedeném pořadí, k předponě jakékoli nenulové výstupní hodnoty.X xo	Nezobrazí se žádná předpona.
	Když se použije s příznakem e, , Ef, F, a, nebo A formát, # vynutí výstupní hodnotu obsahovat desetinnou čárku.	Desetinná čárka se zobrazí jenom v případě, že číslice následují.
	Při použití s formátem g nebo G příznak # vynutí výstupní hodnotu, aby obsahovala desetinnou čárku a zabraňuje zkrácení koncových nul. Ignorováno při použití s c, , id, u, nebo s.	Desetinná čárka se zobrazí jenom v případě, že číslice následují. Koncové nuly jsou zkráceny.

Specifikace šířky

Ve specifikaci převodu se po znacích příznaků zobrazí volitelné pole specifikace šířky . Argument width je nezáporné desetinné číslo, které řídí minimální počet znaků, které jsou výstupem. Pokud je početznakůch znaky menší než zadaná zadaná šířka, přidají se prázdné hodnoty vlevo nebo vpravo od hodnot-, dokud nedosáhnete minimální šířky. Pokud width je předpona 0, počáteční nuly se přidají k celočíselnému nebo plovoucímu bodě, dokud nedosáhnete minimální šířky, s výjimkou případů, kdy je převod na nekonečno nebo NaN.

Specifikace šířky nikdy nezpůsobí zkrácení hodnoty. Pokud je počet znaků ve výstupní hodnotě větší než zadaná šířka nebo pokud width není zadaný, jsou všechny znaky hodnoty výstupem, s výhradou specifikace přesnosti.

Pokud je specifikace šířky hvězdičkou (*), int zadá argument ze seznamu argumentů hodnotu. Argument width musí předcházet hodnotě formátované v seznamu argumentů, jak je znázorněno v tomto příkladu:

printf("%0*d", 5, 3); /* 00003 is output */

Chybějící nebo malá width hodnota ve specifikaci převodu nezpůsobí zkrácení výstupní hodnoty. Pokud je výsledek převodu širší než width hodnota, pole se rozbalí tak, aby obsahovalo výsledek převodu.

Specifikace přesnosti

Ve specifikaci převodu je třetím volitelným polem specifikace přesnosti. Skládá se z tečky (.) následované nezáporným desetinným číslem, které v závislosti na typu převodu určuje počet znaků řetězce, počet desetinných míst nebo počet významných číslic, které mají být výstupem.

Na rozdíl od specifikace šířky může specifikace přesnosti způsobit zkrácení výstupní hodnoty nebo zaokrouhlování hodnoty s plovoucí desetinnou čárkou. Pokud precision je zadán jako 0 a hodnota, která se má převést, je 0, výsledek není výstup znaků, jak je znázorněno v tomto příkladu:

printf( "%.0d", 0 ); /* No characters output */

Pokud je specifikace přesnosti hvězdičkou (*), int zadá argument ze seznamu argumentů hodnotu. V seznamuargumentch precision

printf( "%.*f", 3, 3.14159265 ); /* 3.142 output */

Znak type určuje interpretaci precision nebo výchozí přesnost, pokud precision je vynechána, jak je znázorněno v následující tabulce.

Vliv hodnot přesnosti na typ

Typ	Význam	Výchozí
a, A	Přesnost určuje počet číslic za bodem.	Výchozí přesnost je 13. Pokud je přesnost 0, není vytištěna žádná desetinná čárka, pokud # není použit příznak.
c, C	Přesnost nemá žádný vliv.	Znak se vytiskne.
d, i, o, u, , xX	Přesnost určuje minimální počet číslic, které se mají vytisknout. Pokud je počet číslic v argumentu menší než přesnost, výstupní hodnota je vycpaná vlevo nulami. Hodnota se nezkrátí, když počet číslic překročí přesnost.	Výchozí přesnost je 1.
e, E	Přesnost určuje počet číslic, které se mají vytisknout za desetinnou čárkou. Poslední vytištěná číslice se zaokrouhlí.	Výchozí přesnost je 6. Pokud je přesnost 0 nebo tečka (.) se zobrazí bez čísla za ním, nevytiskne se žádná desetinná čárka.
f, F	Hodnota přesnosti určuje počet číslic za desetinnou čárkou. Pokud se zobrazí desetinná čárka, zobrazí se před ní alespoň jedna číslice. Hodnota se zaokrouhlí na odpovídající počet číslic.	Výchozí přesnost je 6. Pokud je přesnost 0 nebo pokud se tečka (.) zobrazí bez čísla za číslem, nevytiskne se žádná desetinná čárka.
g, G	Přesnost určuje maximální počet významných číslic vytištěných.	Vytiskne se šest významných číslic a všechny koncové nuly se zkrátí.
s, S	Přesnost určuje maximální počet znaků, které se mají vytisknout. Znaky nad přesností se nevytisknou.	Znaky se vytisknou, dokud se nenajde znak null.

Specifikace velikosti argumentu

Ve specifikaci převodu je pole velikostí modifikátor délky argumentu pro specifikátor převodu typů . Předpony pole velikosti pro pole typu ,hh , h, , j( l malá písmena L), L, llt, , w, zI (velká písmena i) I32a I64– určují "velikost" odpovídajícího argumentu – dlouhý nebo krátký, 32bitový nebo 64bitový, jednobajtů nebo široký znak – v závislosti na specifikátoru převodu, který upraví. Tyto předpony velikosti se používají s znaky typu ve printf funkcích a wprintf rodinami funkcí k určení interpretace velikostí argumentů, jak je znázorněno v následující tabulce. Pole velikost je volitelné pro některé typy argumentů. Pokud nezadáte předponu velikosti, bude formátovací modul využívat celočíselné argumenty, například znaménkový nebo nepodepsaný , , , a typy výčtu – jako 32bitové int typy a doublefloat, a argumenty long double s plovoucí desetinou čárkou se spotřebují jako 64bitové double typy. longintshortchar Toto chování odpovídá výchozím pravidlu povýšení argumentů pro seznamy argumentů proměnných. Další informace o povýšení argumentu naleznete v tématu Tři tečky a Výchozí argumenty ve výrazech přípony. U 32bitových i 64bitových systémů musí specifikace převodu 64bitového celočíselného argumentu obsahovat předponu ll velikosti nebo I64. V opačném případě není definováno chování formátovače.

Některé typy se liší v 32bitovém a 64bitovém kódu. Například size_t je 32 bitů dlouhé v kódu zkompilovaném pro x86 a 64 bitů v kódu kompilovaném pro x64. Pokud chcete vytvořit kód nezávislé na platformě pro typy s proměnlivou šířkou, můžete použít modifikátor velikosti argumentu s proměnnou a šířku. Místo toho použijte modifikátor 64bitového argumentu a explicitně upřednostníte typ argumentu s proměnnou šířkou na 64 bitů. Modifikátor velikosti argumentu specifické pro I Microsoft (velká písmena i) zpracovává celočíselné argumenty s proměnlivou šířkou, ale pro přenositelnost doporučujeme specifikátory typu ja tz modifikátory.

Předpony velikosti pro specifikátory formátu printf a wprintf

Určení	Použít předponu	Se specifikátorem typu
char unsigned char	hh	d, i, o, u, , xnebo X
short int short unsigned int	h	d, i, o, u, , xnebo X
__int32 unsigned __int32	I32	d, i, o, u, , xnebo X
__int64 unsigned __int64	I64	d, i, o, u, , xnebo X
intmax_t uintmax_t	j nebo I64	d, i, o, u, , xnebo X
long double	l (malá písmena L) nebo L	a, A, , e, fE, F, , nebo gG
long int long unsigned int	l (malá písmena L)	d, i, o, u, , xnebo X
long long int unsigned long long int	ll (malá písmena LL)	d, i, o, u, , xnebo X
ptrdiff_t	t nebo I (velká písmena i)	d, i, o, u, , xnebo X
size_t	z nebo I (velká písmena i)	d, i, o, u, , xnebo X
Jednobajtů	h	c nebo C
Široký znak	l (malá písmena L) nebo w	c nebo C
Řetězec jednobajtů znaků	h	s, S nebo Z
Řetězec širokého znaku	l (malá písmena L) nebo w	s, S nebo Z

size_t Typy ptrdiff_t a typy jsou nebo unsigned __int32 na __int32 32bitových platformách nebo __int64 unsigned __int64 na 64bitových platformách. Předpony I (velká písmena i), j, ta z velikost mají správnou šířku argumentu pro platformu.

V jazyce Visual C++ je sice long double odlišný typ, ale má stejnou interní reprezentaci jako double.

hc Specifikátor typu nebo typ hC je synonymem c funkcí printf a C funkcíwprintf. Specifikátor lc, , lCwcnebo wC typ je synonymem s funkcemi C printf a funkcemi c wprintf. hs Specifikátor typu nebo typ hS je synonymem s funkcí printf a S funkcíwprintf. Specifikátor , , nebo typ je synonymem s funkcemi S printf a funkcemi wprintf s.wS wslSls

Poznámka:

Specifické pro Microsoft:
Předpony I modifikátoru velikosti argumentu (velká písmena i), I32a I64w velikost argumentu jsou rozšíření Microsoftu a nejsou kompatibilní s ISO C. Předpona h při použití s daty typu char a předponou l (malými písmeny L), když se používá s daty typu double , jsou rozšíření Microsoftu.

Viz také

printf, _printf_l, , wprintf_wprintf_l
printf_s, _printf_s_l, , wprintf_s_wprintf_s_l
printf_p Poziční parametry