Aus eine Formatzeichenkette und der Argumentliste wird eine neue Zeichenkette erzeugt. Die Regeln der Umwandlung sind ähnlich mit denen der C-Funktion vprintf() und dessen Varianten. Jedoch gibt es einige Erweiterungen.

Die Argumente werden automatisch an den durch format geforderten Typ angepasst bzw. umgewandelt. Si wird z.B. eine Zeichenkette gescanned, wenn sie als Ganzzahl ausgegeben werden soll.

2. Die Formatzeichenkette

Die Formatzeichenkette format ist eine einfache Zeichenkette mit Null oder mehr Direktiven. Einfache Zeichen (nicht '%') werden einfach 1:1 kopiert.

Direktiven beginnen mit einem Prozentzeichen '%' und enden mit einem Umwandlungszeichen. Sie benötigen Null oder mehr Argumente und erzeugen eine textuelle Darstellung der Argumente. Zwischen Prozent- und Umwandlungszeichen stehen jeweils optional, aber in dieser Reichenfolge, ein Index, Flags, eine minimale Feldweite, eine zweite Feldweite, eine Genauigkeit und eine Längenangabe:

'%' [index ':'] [flags] [fw1] [':' fw2] ['.' prec] conv_char

Die Argumente müssen passend zu den Direktiven sein.

2.1 Parameter-Index

Optional kann ein Index angegeben werden. Dieser Index beginnt direkt hinter dem Prozentzeichen mit einer Ziffer aus dem Bereich 1 bis 9 gefolgt von weiteren Ziffern gefolgt von einem Doppelpunkt.

Dieser Index, ist 1-basiert und gibt an, auf den wievielten Parameter sich die nächste Umwandlung bezieht. Die weiteren Umwandlungen nutzen anschließend die Parameter ab index+1.

2.2 Flags

Die Flags, die direkt dem Prozentzeichen folgen, bestehen aus Null oder mehr der folgenden Zeichen in beliebiger Reichenfolge:

#
Dieses Flag besagt, dass eine alternative Darstellungsform verwendet werden soll.
- d,i,m,u: Bei Verwendung einer Zahlenbasis>10 werden normalerweise zuerst die 26 Kleinbuschstaben und danach bei Bedarf die 26 Großbuchstaben als zusätzliche Ziffern mit der Wertigkeit 10 bis 61 genutzt. Durch das Flag werden aber zuerst die Großbuchstaben verwendet.
- b: Eine binäre Zahl wird mit dem Prefix 0b ausgeben.
- o: Eine oktale Zahl wird zwingend mit den Prefix 0 (Null) ausgeben.
- x,X,p: Eine hexadezimale Zahl bzw. ein Zeiger wird mit dem Prefix 0x (bzw. 0X für 'X') ausgeben.
- Z: Die Ausgabe basiert auf Vielfache von 1024 anstatt von 1000.
- R: Die römische Zahl wird in Großbuchstaben ausgegeben.
- a,A,e,E,f,F,g,G (Fließkommazahlen): Ein Dezimalpunkt wird erzwungen. Für g,G werden Nullen am Ende nicht unterdrückt.
- s,T: Die Zeichenkette wird mittels dcString::PrintString() umgewandelt.
- V: Objekte der Klasse dcValue werden technisch akurat (mittels ::PrintValue()) anstatt menschlich lesbar (mittels ::PrintValueHuman()) ausgegeben.
- [H: Es wird die reale Adresse anstatt Null als Basisadresse für den HexDump verwendet.
Für andere Umwandlungen ist das Verhalten undefiniert, wobei das Flag meist einfach ignoriert wird.
0 (Null)
Die Ausgabe einer Nummer (b,d,i,o,u,x,X, p, a,A,e,E,f,F,g,G) soll auf der linken Seite mit 0 aufgefüllt werden. Bei Kombination mit einer Genauigkeit mit b,d,i,o,u,x,X wird und auch bei der Verwendung des Flags - wird das Flag 0 ignoriert.
Bei Ausgabe eines Bitfeldes mit B wird die Ausgabe von < und > auch bei dem Wert 0 erzwungen.
Bei Ausgabe einer Zeichenkette in alternativer Form mittels dcString::PrintString() (bei %#s und bei %#T) wird auf die Anführungszeichen verzichtet.
-
Die Erzeugte Ausgabe wird nach links anstatt nach rechts ausgerichtet.
' ' (SPACE)
Positive Zeichen werden von einem Leerzeichen angeführt.
Normalerweise wird für negative Zahlen das Minusszeichen vorangestellt und bei positiven Zahlen kein Zeichen.
+
Positive Zahlen werden von einem Pluszeichen (+) angeführt. Dieses Flag hat Vorrang vor ' ' (SPACE).
Normalerweise wird für negative Zahlen das Minusszeichen vorangestellt und bei positiven Zahlen kein Zeichen.
>
Bei Ganzzahlen wird Vorzeichen (Minus, Plus, Leerzeichen) recht hinter der Ziffernfolge und hinter einem evtl. vorhandenen 'q' anstatt links vor der Ziffernfolge gesetzt.
Bei der V-Umwandlung (dcValue) wird der Full-Modus aktiviert. Im Full-Modus werden viele Dinge ausführlich und nicht in einer Kurzform dargestellt.
'
Dieses aktiviert das grouping bzw. die Verwendung von ' für's Quoting:
- d,i,u: Der Punkt wird als Tausendertrennzeichen eingestzt (Beispiel: 12.345)
- b,o,x,X,p: Der Doppelpunkt wird als Trennzeichen für die Gruppierung von 4 Ziffern eingestzt (Beispiel: 41a2:4b23)
- s,T: Die Zeichenkette wird mittels dcString::PrintString() und dem Hochkommata ' als Quotingzeichen umgewandelt.
- h,H,y,Y: Zeichenketten werden mit Hochkommata (') anstatt mit Anführungszeichen (") eingeschlossen.
.
Aus Kompatibilitätsgründen ist das Flag . eine obsolete Alternative zu ', die nicht mehr genutzt werden sollte. Und dieses bedeutet, dass Genauigkeiten von einer Feldweite >0 angeführt werden sollten um Mehdeutigkeiten vermeiden.
q und Q
Hinter der letzten Ziffer einer 64-Bit Ganzzahl wird ein 'q' bzw. ein 'Q' eingefügt. Für alle anderen Datentypen werden diese beiden Flags ignoriert.

2.3 Feldweite

Nach den optionalen Flags folgt die optionale Angabe einer (minimalen) Feldweite. Die Feldweite wird als Dezmalzahl ohne führende Null angegeben.

Soweit nicht anders beschrieben gilt: Falls der umgewandelte Wert weniger Zeichen hat als die Feldweite angibt, dann wird die Zeichenkette links (oder rechts, wenn Flags - angegeben wurde) mit Leerzeichen (oder evtl. Nullen, wenn Flag 0 angegeben wurde) auf die angegebene Feldweite erweitert.

Wird ein Stern (*) anstatt einer Dezimalzahl angegeben, dann wird als nächstes Argument eine Ganzzahl vom Typ int erwartet um die Feldweite festzulegen. Bei negative Werten wird das --Flag gesetzt und der Absolutwert verwendet.

Bei einigen Umwandlungen wird die Feldweite auf einen Wert >1000 begrenzt, um Puffer-Überläufe effektiv zu vermeiden.

Die Feldweite führt auf keinem Fall zu einem Abschneiden des umgewandelten Wertes.

2.4 2. Feldweite (für Folgezeilen)

Die Umwandlung mittels V (dcValue) benötigt eine zweite Feldweite. Diese optionale Angabe wird durch einen Doppelpunkt gefolgt von einer optionalen Dezimalzahl (:number) angegeben.

Diese zweite Zahl wird auch für die Umwandlungen 'N' und '[H' verwendet.

Bei den Umwandlungen 'd', 'i', 'm' und 'u' wird diese 2. Feldweite als Angabe der Zahlenbasis verwendet, wenn der Wert >=2 und <=62 ist.

2.5 Genauigkeit

Die Optionale Genauigkeit wird durch einen Punkt gefolgt von einer optionalen Dezimalzahl (.number) angegeben.

Wird ein Stern (*) anstatt einer Dezimalzahl angegeben, dann wird als nächstes Argument eine Ganzzahl vom Typ int erwartet um die Genauigkeit festzulegen.

Besteht die Genauigkeit aus nur einem Punkt oder ist sie negativ, dann wird Wert Null verwendet.

Die Bedeutung ist abhängig von der Umwandlung:

b,d,i,o,u,x,X: Bei den Ganzzahl-Umwandlungen wird die minimale Anzahl der auszugebenen Ziffern angegeben.
a,A,e,E,f,F: Bei den Fließkommazahl-Umwandlungen wird die Anzahl der auszugebenen Ziffern nach dem Dezimalpunkt angegeben.
g,G: Bei diesen Fließkommazahl-Umwandlungen wird die Anzahl der auszugebenen signifikanten Ziffern angegeben.
s,T,h,H,y,Y: Hiermit dier die Anzahl der maximal auszugebenen Zeichen festgelegt.

2.6 Umwandlungszeichen

Das Umwandlungszeichen beendet die Direktive und löst die eigentliche Umwandlung aus. Es existieren die folgenden Umwandlungszeichen:

a..z

10..35

A..Z

36..61

'#'

u
Die Zahl wird nach den selben Regeln wie %i ausgegeben, jedoch als vorzeichenlose Zahl.
b,o,x,X
Das Ganzzahl-Argument wird als vorzeichenlose Ganzzahl im Binärformat (b, Ziffern 0-1), im Oktalformat (o, Ziffern 0-7), im Hexadezimalformat (x,X, Ziffern 0-9 und a-f bzw. A-F) ausgegeben.
B
Das Argument wird mittels printBitField() als Bitfeld dargestellt. Die folgenden Flags werden ausgewertet:
- #:
  Bereiche werden unterbunden (Bit _BF_RANGES gelöscht).
- ':
  Das Bitfeld wird mit spitzen Klammern eingeschlossen (Bit _BF_BRACKETS gesetzt), wenn der auszugebene Wert nicht Null ist.
- 0:
  Das Bitfeld wird unabhängig vom Wert immer mit spitzen Klammern eingeschlossen (Bit _BF_FORCE_BRACKETS gesetzt).
z,Z
Das Ganzzahl-Argument wird als vorzeichenlose Zahl in einem kompakten Format mit einem SI-Präfix dargestellt. Durch das Flag '#' verändert sich die Zahlenbasis von 1000 auf 1024.
Das Format wird durch die Genauigkeit festgelegt. Werte <3 führen zu einer leeren Ausgabe. Die Werte 3, 4 und 5 legen das Ausgabeformat fest. Werte >5 werden als 5 interpretiert.
Sollte keine Genauigkeit angegeben worden sein, dann wird die angegebene Feldweite oder ersatzweise der Wert 5 genutzt.
R
Das Ganzzahl-Argument wird mittels printRoman() als vorzeichenbehaftete (Bit _ROMAN_SIGNED gesetzt) römische Zahl ausgegeben. Dabei werden maximal die unteren 32 Bits des Argumentes verwendet. Die folgenden Flags werden ausgewertet:
- #:
  Für die auszugebene Zahl werden Großbuchstaben verwendet (Bit _ROMAN_UPPER gesetzt).
- ':
  Anstatt der Kurzform (z.B. IC für 99) wird die Langform (XCIX für 99) verwendet (Bit _ROMAN_SHORT gelöscht).
- 0:
  Der Wert Null wird durch "0" anstatt durch eine leere Zeichenenkette dargestellt (Bit _ROMAN_ZERO gesetzt).
M
Das 64-Bit-Ganzzahl-Argument wird mittels printInterval() als Zeitintervall ausgegeben. Wenn Flag '#' verwendet wird, dann erfolgt die Ausgabe im kompakten Format.
Für die Ausgabe mittels printInterval() wird die Format-Zeichenkette "%?-%.*T" verwendet. Das Sternchen ('*') ist dabei die angegebene Genauigkeit begrenzt auf das Intervall [0..9].
Für die Ausgabe im kompakten Format werden Feldweite und Genauigkeit direkt übernommen. Die Standardfeldweite ist jedoch 5 und Werte <3 werden auf 3 gesetzt.
N
Das Ganzzahl-Argument wird mittels als alhpa numerische Zahl ausgegeben. Das folgende Flag wird ausgewertet:
- #:
  Es werden auch Kleinbuchstaben für die Bildung der alhpa numerischen Zahl verwendet.
Die 2. Feldweite wird für die minimale Anzahl der Buchstaben verwendet. Die Voreinstellung ist 1. Für die Anzahl der Ziffern wird die Genauigkeit verwendet. Die Voreinstellung ist 2.
a,A,e,E,f,F,g,G
Eine Fließkommazahl wird ausgegeben. Die Umwandlung geschieht mittels der System-Funktion snprintf(), deren Dokumentation für weitere Details verwendet werden sollte.
Die beiden Varianten A und F werden nicht von allen Systemen unterstützt, so z.B. nicht von Windows und dem MS-Visual-Studio.
c,C
Die Ganzzahl wird als Zeichen ausgegeben. Ist die Quelle kein char, dann wird das Zeichen zu einem Multi-Word-Wert gewandelt.
s,S,T
Das Argument wird in eine Zeichenkette gewandelt und ausgegeben. Sollte eine Genauigkeit angegeben worden sein, dann werden maximal die als Genauigkeit angegebenen Zeichen in die Ausgabe übernommen.
Das Ausgabeformat kann durch die drei Flags "#", "'" und "0" beeinflusst werden. Durch die Verwendung von "#" oder "'" wird der String vor der Ausgabe in eine lesbare Zeichenkette ("..." oder '...') gewandelt. Bei "'" werden Hochkommata und anderenfalls Anführungszeichen als Eingrenzer verwendet. Durch das Flag "0" werden keine Eingrenzer verwendet.
h,H,y,Y
Der Inhalt des Argumentes wird in Abhängigkeit seines Types ausgegeben. Liste und Maps werden dabei rekursiv ausgegeben. Die Ausgabe erfolgt in einem menschenlesbaren Format oder, falls das Flag '#' gesetzt ist, in einem maschienenlesbaren Format. Dieses maschinenlesbare Format ist so, dass der Originalwert wieder mittels scan() eingelesen werden kann.
Die beiden Feldweiten werden als Feldweiten für die erste Zeile (fw1) und für weitere Zeilen (fw2) verwendet. Ein Umbruch findet aber nur statt, wenn einer der bedien Werte >0 ist. Die Genauigkeit wird in der menschenlesbaren Form als maximale Anzahl der auszugebenen Zeichen verwendet.
Mit dem Flag '>' wird der Full-Modus aktiviert: Im Full-Modus werden viele Dinge ausführlich und nicht in einer Kurzform dargestellt.
In der Umwandlung H ist implizit das Flag '>' (Full-Modus) gesetzt. In der Umwandlung y ist implizit das Flag '#' (maschienenlesbar) gesetzt. In der Umwandlung X sind implizit die beiden Flags '#' und '>' gesetzt.
[ oder {
Alle Zeichen bis zum nächsten ']' bzw. '}' oder Null-Terminator werden als Sub-Zeichenkette erkannt.
Beim Einlesen dieser Zeichenkette haben Backslashes ('\') eine besondere Bedeutung: Der Backslash wird ignoriert und das nächste Zeichen gehört zur Sub-Zeichenkette, auch wenn es z.B. ein ']', '}' oder '\' ist.
Das erste dieser Zeichen dieser Sub-Zeichenkette legt die Umwandlung fest und die restlichen Zeichen werden als Format-Zeichenkette für die Umwandlung verwendet.
- [n (strftime(now))
  Die aktuelle Zeit wird mittels strftime() ausgegeben.
  Hinweis: Unter Windows existieren die GNU-Erweiterungen für strftime wie z.B. '%T' oder '%F' nicht.
- [t (strftime(time))
  Es wird ein Argument vom Typ int64 erwartet, der mittels strftime() ausgegeben wird.
- [N (dcTime(now))
  Die aktuelle Zeit wird mittels printTime() ausgegeben.
- [T (dcTime(time))
  Das zugehörige Argument wird mittels printTime() ausgegeben.
- [D (dcTime(date))
  Das zugehörige Argument wird mittels printTime() ausgegeben.
- [M (dcTimer)
  Es wird ein Argument wird mittels printInterval() ausgegeben.
- [H (HexDump)
  Das Argument wird in eine Zeichenkette gewandelt und als Hexdump ausgegeben. Wurde eine Genauigkeit angegeben, dann werden maximal die angegeben Anzahl von Bytes in dem HexDump ausgegeben. Die Formatzeichenkette wird aus Optionen gescannt.
  Als Basisadresse für die Ausgabe wird der Wert Null verwendet. Ist Flag # gesetzt, dann wird stattdessen die reale Adresse verwendet.
  Die 1. Feldweite wird als Feldweite für die Adressausgabe verwendet. Ist die 2. Feldweite >0, dann wird der HexDump um die angegebene Anzahl mittels indent() eingerückt.
%
Es wird ein Prozentzeichen (%) in die Ausgabe geschrieben. Argumente werden nicht gelesen und alle anderen Angaben wie Flags, Feldweite, oder Genauigkeit werden ignoriert.

Alle anderen Umwandlungszeichen sind verboten und werden ignoriert.

Funktionsergebnis: STRING

Als Funktionsergebnis wird die erzeugte Zeichenkette geliefert.

Siehe auch:
scan() printTime() printInterval() printBitField()

Weitere ähnliche Funktionen:

Formatierte Ausgabe
Funktion	Kurzinfo
hexDump()	Eine Zeichenkette als Hex-Dump ausgeben.
Print()	Einen formatierten Text erzeugen.
printBitField()	Ein Bitfeld in eine textuelle Darstellung überführen.
printFileName()	—
printInterval()	textausgabe eines Zeitintervalles
printRoman()	Ganzzahl in römischer Schreibweise ausgeben.
printTime()	Formatierte Ausgabe einer Datums- und Zeitangabe.
string()	—