2)
Schreibt die Ergebnisse in einen Dateistrom
stream
.
3)
Schreibt die Ergebnisse in einen Zeichenketten-
buffer
.
4)
Schreibt die Ergebnisse in einen Zeichenstring
buffer
. Höchstens
buf_size
-
1
Zeichen werden geschrieben. Der resultierende Zeichenstring wird mit einem Nullzeichen abgeschlossen, es sei denn
buf_size
ist null. Wenn
buf_size
null ist, wird nichts geschrieben und
buffer
kann ein Nullzeiger sein, jedoch wird der Rückgabewert (Anzahl der Bytes, die ohne den Nullterminator geschrieben würden) weiterhin berechnet und zurückgegeben.
Wenn ein Aufruf von
sprintf
oder
snprintf
dazu führt, dass das Kopieren zwischen Objekten erfolgt, die sich überlappen, ist das Verhalten undefiniert (z.B.
sprintf
(
buf,
"%s text"
, buf
)
;
).
Zeiger auf einen Zeichenstring, in den geschrieben wird
buf_size
-
bis zu
buf_size
-
1
Zeichen können geschrieben werden, plus den Nullterminator
format
-
Zeiger auf einen nullterminierten Multibyte-String, der angibt, wie die Daten zu interpretieren sind
...
-
Argumente, die die auszugebenden Daten spezifizieren. Wenn ein Argument nach
Standardargument-Promotions
nicht dem von der entsprechenden Konvertierungsspezifikation erwarteten Typ entspricht (der erwartete Typ ist der gepromote Typ oder ein kompatibler Typ des gepromoten Typs), oder wenn weniger Argumente vorhanden sind als von
format
benötigt, ist das Verhalten undefiniert. Wenn mehr Argumente vorhanden sind als von
format
benötigt, werden die überzähligen Argumente ausgewertet und ignoriert
Der
Format
-String besteht aus gewöhnlichen Byte-Zeichen (außer
%
), die unverändert in den Ausgabestrom kopiert werden, und Konvertierungsspezifikationen. Jede Konvertierungsspezifikation hat folgendes Format:
Einleitendes
%
Zeichen.
(optional)
ein oder mehrere Flags, die das Verhalten der Konvertierung modifizieren:
-
: das Ergebnis der Konvertierung wird innerhalb des Feldes linksbündig ausgerichtet (standardmäßig ist es rechtsbündig).
+
: das Vorzeichen von vorzeichenbehafteten Konvertierungen wird immer dem Ergebnis vorangestellt (standardmäßig wird das Ergebnis nur dann mit einem Minus versehen, wenn es negativ ist).
space
: wenn das Ergebnis einer vorzeichenbehafteten Konvertierung nicht mit einem Vorzeichen beginnt oder leer ist, wird dem Ergebnis ein Leerzeichen vorangestellt. Es wird ignoriert, wenn das
+
-Flag vorhanden ist.
#
: die
alternative Form
der Konvertierung wird durchgeführt. Siehe die nachfolgende Tabelle für genaue Auswirkungen, andernfalls ist das Verhalten undefiniert.
0
: für Ganzzahl- und Gleitkommazahl-Konvertierungen werden führende Nullen zum Auffüllen des Feldes verwendet anstelle von
space
-Zeichen. Für Ganzzahlen wird es ignoriert, wenn die Genauigkeit explizit angegeben ist. Für andere Konvertierungen führt die Verwendung dieses Flags zu undefiniertem Verhalten. Es wird ignoriert, wenn das
-
-Flag vorhanden ist.
(optional)
Ganzzahlwert oder
*
, der die minimale Feldbreite angibt. Das Ergebnis wird bei Bedarf links (bei rechtsbündiger Ausrichtung) oder rechts (bei linksbündiger Ausrichtung) mit
Leerzeichen
aufgefüllt (standardmäßig). Falls
*
verwendet wird, wird die Breite durch ein zusätzliches Argument vom Typ
int
angegeben, das vor dem zu konvertierenden Argument und dem die Genauigkeit liefernden Argument (falls vorhanden) erscheint. Wenn der Wert des Arguments negativ ist, führt dies zur Angabe des
-
Flags mit positiver Feldbreite (Hinweis: Dies ist die minimale Breite: Der Wert wird niemals abgeschnitten.).
(optional)
.
gefolgt von einer Ganzzahl oder
*
, oder keines von beiden, was die
Präzision
der Konvertierung angibt. Falls
*
verwendet wird, wird die
Präzision
durch ein zusätzliches Argument vom Typ
int
spezifiziert, das vor dem zu konvertierenden Argument erscheint, aber nach dem Argument, das die minimale Feldbreite angibt, falls eines angegeben wurde. Wenn der Wert dieses Arguments negativ ist, wird er ignoriert. Wenn weder eine Zahl noch
*
verwendet wird, wird die Präzision als Null angenommen. Siehe die nachfolgende Tabelle für die genauen Auswirkungen der
Präzision
.
(optional)
Längenmodifikator
der die Größe des Arguments spezifiziert (in Kombination mit dem Konvertierungsformat-Spezifizierer bestimmt er den Typ des entsprechenden Arguments).
Konvertierungsformat-Spezifizierer.
Die folgenden Formatbezeichner sind verfügbar:
Konvertierung
Spezifizierer
Erklärung
Erwarteter
Argumenttyp
Längenmodifikator→
hh
h
keine
l
ll
j
z
t
L
Nur verfügbar seit C++11→
Ja
Ja
Ja
Ja
Ja
%
Schreibt ein literales
%
. Die vollständige Konvertierungsspezifikation muss
%%
lauten.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
c
Schreibt ein
einzelnes Zeichen
.
Das Argument wird zuerst in
unsigned
char
konvertiert.
Wenn der
l
-Modifikator verwendet wird, wird das Argument zuerst in eine Zeichenkette konvertiert, als ob durch
%ls
mit einem
wchar_t
[
2
]
-Argument.
N/A
N/A
int
std::wint_t
N/A
N/A
N/A
N/A
N/A
s
Schreibt einen
Zeichenstring
.
Das Argument muss ein Zeiger auf das erste Element eines Zeichenarrays sein.
Precision
spezifiziert die maximale Anzahl an zu schreibenden Bytes. Wenn
Precision
nicht angegeben ist, werden alle Bytes bis zum ersten Nullterminator (ausschließlich) geschrieben.
Wenn der
l
-Spezifizierer verwendet wird, muss das Argument ein Zeiger auf das erste Element eines Arrays von
wchar_t
sein, welcher wie durch einen Aufruf von
std::wcrtomb
mit einem null-initialisierten Konvertierungszustand in ein char-Array konvertiert wird.
N/A
N/A
char
*
wchar_t
*
N/A
N/A
N/A
N/A
N/A
d
i
Wandelt eine
vorzeichenbehaftete Ganzzahl
in die Dezimaldarstellung
[-]dddd
um.
Präzision
gibt die Mindestanzahl der anzuzeigenden Ziffern an. Die Standardpräzision ist
1
.
Wenn sowohl der konvertierte Wert als auch die Präzision
0
sind, ergibt die Konvertierung keine Zeichen.
Für den
z
-Modifikator ist der erwartete Argumenttyp die vorzeichenbehaftete Version von
std::size_t
.
Wandelt eine
vorzeichenlose Ganzzahl
in die Oktaldarstellung
oooo
um.
Präzision
gibt die Mindestanzahl der anzuzeigenden Ziffern an. Die Standardpräzision ist
1
.
Wenn sowohl der konvertierte Wert als auch die Präzision
0
sind, ergibt die Konvertierung keine Zeichen.
In der
alternativen Implementierung
wird die Präzision bei Bedarf erhöht, um eine führende Null zu schreiben. In diesem Fall wird, wenn sowohl der konvertierte Wert als auch die Präzision
0
sind, eine einzelne
0
geschrieben.
Wandelt eine
vorzeichenlose Ganzzahl
in die hexadezimale Darstellung
hhhh
um.
Für die
x
Konvertierung werden die Buchstaben
abcdef
verwendet.
Für die
X
Konvertierung werden die Buchstaben
ABCDEF
verwendet.
Präzision
gibt die Mindestanzahl der anzuzeigenden Ziffern an. Die Standardpräzision ist
1
.
Wenn sowohl der konvertierte Wert als auch die Präzision
0
sind, ergibt die Konvertierung keine Zeichen.
In der
alternativen Implementierung
wird
0x
oder
0X
nichtnull-Werten vorangestellt.
N/A
u
Wandelt eine
unsigned integer
in die Dezimaldarstellung
dddd
um.
Precision
gibt die Mindestanzahl der anzuzeigenden Ziffern an.
Die Standard-Präzision ist
1
.
Wenn sowohl der konvertierte Wert als auch die Präzision
0
sind, ergibt die Konvertierung keine Zeichen.
N/A
f
F
(C++11)
Konvertiert
Gleitkommazahlen
in die Dezimalschreibweise im Format
[-]ddd.ddd
.
Präzision
gibt die exakte Anzahl der Nachkommastellen an.
Die Standardpräzision beträgt
6
.
In der
alternativen Implementierung
wird das Dezimaltrennzeichen auch dann geschrieben, wenn keine Ziffern folgen.
Für die Konvertierung von Unendlich und NaN siehe
Anmerkungen
.
N/A
N/A
double
double
(C++11)
N/A
N/A
N/A
N/A
long
double
e
E
Wandelt eine
Gleitkommazahl
in die dezimale Exponentenschreibweise um.
Für den
e
-Konvertierungsstil wird
[-]d.ddd
e
±dd
verwendet.
Für den
E
-Konvertierungsstil wird
[-]d.ddd
E
±dd
verwendet.
Der Exponent enthält mindestens zwei Ziffern, weitere Ziffern werden nur bei Bedarf verwendet.
Wenn der Wert
0
ist, ist der Exponent ebenfalls
0
.
Präzision
gibt die exakte Anzahl der Ziffern nach dem Dezimaltrennzeichen an.
Die Standardpräzision ist
6
.
In der
alternativen Implementierung
wird das Dezimaltrennzeichen auch dann geschrieben, wenn keine Ziffern folgen.
Für die Konvertierung von Unendlich und NaN siehe
Hinweise
.
N/A
N/A
N/A
N/A
N/A
N/A
a
A
(C++11)
Konvertiert
Gleitkommazahlen
in die hexadezimale Exponentenschreibweise.
Für den
a
-Konvertierungsstil wird
[-]
0x
h.hhh
p
±d
verwendet.
Für den
A
-Konvertierungsstil wird
[-]
0X
h.hhh
P
±d
verwendet.
Die erste hexadezimale Ziffer ist nicht
0
, wenn das Argument ein normalisierter Gleitkommawert ist.
Wenn der Wert
0
ist, ist der Exponent ebenfalls
0
.
Präzision
gibt die exakte Anzahl der Ziffern nach dem hexadezimalen Punktzeichen an.
Die Standardpräzision ist ausreichend für die exakte Darstellung des Wertes.
In der
alternativen Implementierung
wird das Dezimalpunktzeichen auch dann geschrieben, wenn keine Ziffern folgen.
Für die Konvertierung von Unendlich und NaN siehe
Hinweise
.
N/A
N/A
N/A
N/A
N/A
N/A
g
G
Wandelt eine Gleitkommazahl in Dezimal- oder Exponentenschreibweise um, abhängig vom Wert und der Genauigkeit.
Für den g-Konvertierungsstil wird die Konvertierung mit Stil e oder f durchgeführt.
Für den G-Konvertierungsstil wird die Konvertierung mit Stil E oder
f
(bis C++11)
F
(seit C++11)
durchgeführt.
Sei P gleich der Genauigkeit falls ungleich null,
6
falls die Genauigkeit nicht angegeben ist, oder
1
falls die Genauigkeit
0
ist. Dann, wenn eine Konvertierung mit Stil E einen Exponenten X hätte:
Wenn P > X ≥ −4, erfolgt die Konvertierung mit Stil f
oder F
(seit C++11)
und Genauigkeit P − 1 − X.
Andernfalls erfolgt die Konvertierung mit Stil e oder E und Genauigkeit P − 1.
Sofern keine alternative Darstellung angefordert wird, werden nachgestellte Nullen entfernt, ebenso wird das Dezimaltrennzeichen entfernt, wenn kein Nachkommateil verbleibt.
Für Konvertierungen von Unendlich und NaN siehe
Hinweise
.
N/A
N/A
N/A
N/A
N/A
N/A
n
Gibt die
Anzahl der bisher geschriebenen Zeichen
durch diesen Funktionsaufruf zurück.
Das Ergebnis wird in den Wert geschrieben, auf den das Argument zeigt.
Die Spezifikation darf keine
Flags
,
Feldbreite
oder
Genauigkeit
enthalten.
Für den
z
-Modifikator ist der erwartete Argumenttyp
S
*
, wobei
S
die vorzeichenbehaftete Version von
std::
size_t
ist.
Schreibt eine implementierungsdefinierte Zeichenfolge, die einen
Zeiger
definiert.
N/A
N/A
void
*
N/A
N/A
N/A
N/A
N/A
N/A
**Übersetzungserläuterungen:**
- HTML-Tags und Attribute wurden unverändert belassen
- ``- und `
`-Inhalte wurden nicht übersetzt
- C++-spezifische Begriffe wie "pointer" wurden als "Zeiger" übersetzt (Standard-Fachbegriff in der deutschen C++-Dokumentation)
- "implementation defined character sequence" wurde als "implementierungsdefinierte Zeichenfolge" übersetzt
- Die Übersetzung bewahrt die technische Präzision und den professionellen Ton der Originaldokumentation
Hinweise
Die Gleitkomma-Konvertierungsfunktionen konvertieren Unendlich zu
inf
oder
infinity
. Welches verwendet wird, ist implementierungsdefiniert.
Keine-Zahl wird zu
nan
oder
nan(
char_sequence
)
konvertiert. Welches verwendet wird, ist implementierungsdefiniert.
Die Konvertierungen
F
,
E
,
G
,
A
geben stattdessen
INF
,
INFINITY
,
NAN
aus.
Der Konvertierungsspezifizierer zum Ausgeben von
char
,
unsigned
char
,
signed
char
,
short
und
unsigned
short
erwartet gepromotete Typen von
Standardargument-Promotions
, aber vor der Ausgabe wird sein Wert zu
char
,
unsigned
char
,
signed
char
,
short
und
unsigned
short
konvertiert. Es ist sicher, Werte dieser Typen zu übergeben, aufgrund der Promotion, die beim Aufruf einer variadischen Funktion stattfindet.
Die korrekten Konvertierungsspezifikationen für die festbreiten Zeichentypen (
std::int8_t
usw.) sind im Header
<cinttypes>
definiert (obwohl
PRIdMAX
,
PRIuMAX
usw. synonym mit
%jd
,
%ju
usw. sind).
Der speicher-schreibende Konvertierungsspezifizierer
%n
ist ein häufiges Ziel von Sicherheitsangriffen, bei denen Formatstrings von Benutzereingaben abhängen.
Es gibt einen
Sequenzpunkt
nach der Aktion jedes Konvertierungsspezifizierers; dies ermöglicht das Speichern mehrerer
%n
-Ergebnisse in derselben Variable oder, als Randfall, das Ausgeben einer Zeichenkette, die durch einen früheren
%n
innerhalb desselben Aufrufs modifiziert wurde.
Wenn eine Konvertierungsspezifikation ungültig ist, ist das Verhalten undefiniert.
Rückgabewert
1,2)
Anzahl der geschriebenen Zeichen bei Erfolg oder ein negativer Wert bei einem Fehler.
3)
Anzahl der geschriebenen Zeichen bei Erfolg (ohne das abschließende Nullzeichen) oder ein negativer Wert bei einem Fehler.
4)
Anzahl der Zeichen, die für einen ausreichend großen Puffer geschrieben worden wären, wenn erfolgreich (ohne das abschließende Nullzeichen), oder ein negativer Wert, wenn ein Fehler aufgetreten ist. Somit wurde die (nullterminierte) Ausgabe vollständig geschrieben, genau dann wenn der zurückgegebene Wert nichtnegativ und kleiner als
buf_size
ist.
Hinweise
POSIX legt fest, dass errno bei einem Fehler gesetzt wird. Es spezifiziert außerdem zusätzliche Konvertierungsspezifikationen, insbesondere die Unterstützung für Argumentumordnung (n$ unmittelbar nach % gibt das nte Argument an).
Der Aufruf von std::snprintf mit null buf_size und Nullzeiger für buffer ist nützlich (wenn der Overhead des Doppelaufrufs akzeptabel ist), um die erforderliche Puffergröße für die Ausgabe zu bestimmen:
autofmt="sqrt(2) = %f";intsz=std::snprintf(nullptr,0,fmt,std::sqrt(2));std::vector<char>buf(sz+1);// note +1 for null terminatorstd::sprintf(buf.data(),fmt,std::sqrt(2));// certain to fit