1. Einleitung
Die Funktionen rund um printf dienen dazu, in bereits definierten Strings an bestimmten Stellen Variablen in vorgegebener Formatierung einzufügen. So könnte im String „Hallo, %s” das %s durch "Max Musteruser" ersetzt werden. Im Rahmen der Formatierung kann beispielsweise festgelegt werden, wie viele Nachkommastellen von einem Float angezeigt werden sollen. Ein besonderes Feature ist es, die Mindestlänge nach links und rechts hin festzulegen. Ist der String-/Float-/Integer-Wert dann zu kurz, wird der Rest durch ein beliebig definierbares Zeichen aufgefüllt.
2. Die verschiedenen printf-Funktionen in der Übersicht
Die printf-Funktionen in PHP sind printf(), sprintf(), vprintf() und vsprintf(). Am gebräuchlichsten ist sprintf(). Die Funktionen vprintf und vsprintf werden eher selten verwendet. Die nachfolgende Tabelle zeigt eine Übersicht über alle vier, einschließlich Parametern und Rückgaben.
| Rückgabe | Funktionsname | Parameter | Beschreibung |
|---|---|---|---|
| int | printf | string $format, mixed $args... | Nimmt 0 bis n Variablen ($args) entgegen, formatiert diese entsprechend der Anweisungen in $format und gibt das Ergebnis aus. Rückgabe ist die Länge des erzeugten Strings. |
| string | sprintf | string $format, mixed $args... | Nimmt 0 bis n Variablen ($args) entgegen, formatiert diese entsprechend der Anweisungen in $format und gibt das Ergebnis als String zurück. |
| int | fprintf | resource $handle, string $format, mixed $args... | Nimmt 0 bis n Variablen ($args) entgegen, formatiert diese entsprechend der Anweisungen in $format und schreibt das Ergebnis in $handle (typischerweise eine geöffnete Datei). Gibt die Länge des geschriebenen Strings zurück. |
| int | vprintf | string $format, array $args | Identisch zu printf, nur dürfen die Variablen $args als Array übergeben werden. |
| int | vsprintf | string $format, array $args | Identisch zu sprintf, nur dürfen die Variablen $args als Array übergeben werden. |
| int | vfprintf | resource $handle, string $format, array $args | Identisch zu vfprintf, nur dürfen die Variablen $args als Array übergeben werden. |
Das nächste Beispiel zeigt alle vier Funktionen, jeweils ein mal ausgeführt:
<?php
$format = 'Willkommen, %s!';
$user = 'Musteruser';
printf($format, $user); echo("\n");
var_dump( sprintf($format, $user) );
vprintf($format, array($user)); echo("\n");
var_dump( vsprintf($format, array($user)) );
?>
Willkommen, Musteruser! string(23) "Willkommen, Musteruser!" Willkommen, Musteruser! string(23) "Willkommen, Musteruser!"
Es folgen einige Beispiele, welche die Anwendung der printf-Funktionen und deren Fähigkeiten genauer illustrieren. Die Darstellung erfolgt jeweils auf Basis von sprintf(), jedoch lassen sich die Beispiele nahtlos auf die anderen drei Funktionen übertragen.
3. String in sprintf()
In diesem Beispiel wird der String „Hallo <Benutzername>, willkommen auf <Seitenname>!” definiert. In diesem werden <Benutzername> und <Seitenname> durch den Namen des Benutzers bzw. der Seite ersetzt.
<?php
$user = 'Musteruser';
$seite = 'Beispielseite';
var_dump( sprintf('Hallo %s, willkommen auf %s!', $user, $seite) );
?>
string(47) "Hallo Musteruser, willkommen auf Beispielseite!"
Für einzusetzende Strings entsprechend der zuvor vorgestellten Methode lässt sich eine Maximallänge vorgeben. Statt „%s” schreibt man dann „%.Ns”, wobei N ein beliebiger positiver Integerwert ist. (Punkt vor dem N beachten!) Überschreitet der String die vorgegebene Maximallänge, dann wird alles nach dem N-ten Zeichen abgeschnitten.
<?php
$str = 'Dies ist ein langer String';
var_dump( sprintf('%.12s', $str) );
?>
string(12) "Dies ist ein"
Neben der Maximallänge lässt sich auch eine Minimallänge definieren. Die Schreibweise dafür ist der vorherigen vergleichbar, es gibt aber drei Varianten:
- %Ms: Der String soll mindestens M Zeichen lang sein. Fehlende Zeichen werden am Anfang mit Leerzeichen aufgefüllt.
- %0Ms: Der String soll mindestens M Zeichen lang sein. Fehlende Zeichen werden am Anfang mit Nullen aufgefüllt.
- %'XMs: Der String soll mindestens M Zeichen lang sein. Fehlende Zeichen werden am Anfang mit dem über X definierten Zeichen aufgefüllt. (X kann ein beliebiges Zeichen sein, Apostroph vor dem X beachten!)
Das nachfolgende Beispiel zeigt die Verwendung der letzten Variante. Über %'.26s wird eine Mindestlänge von 26 Zeichen vorgeschrieben. Fehlende Zeichen werden mit Punkten aufgefüllt (aufgrund des '.).
<?php
$str1 = 'abc';
$str2 = 'abcdef';
$str3 = 'abcdefghi';
$str4 = 'abcdefghijkl';
var_dump(
sprintf("%'.26s", $str1),
sprintf("%'.26s", $str2),
sprintf("%'.26s", $str3),
sprintf("%'.26s", $str4)
);
?>
string(26) ".......................abc" string(26) "....................abcdef" string(26) ".................abcdefghi" string(26) "..............abcdefghijkl"
In diesem Beispiel werden die drei Varianten gegenübergestellt:
<?php
$str = 'abcdef';
var_dump(sprintf("%10s", $str));
var_dump(sprintf("%010s", $str));
var_dump(sprintf("%'x10s", $str));
?>
string(10) " abcdef" string(10) "0000abcdef" string(10) "xxxxabcdef"
Die Mindestlänge kann auch „nach rechts hin” umgesetzt werden. Die Zeichen zum Auffüllen des Strings werden dann am Ende statt am Anfang platziert. Um dies zu erreichen, muss ein Minus entweder vor der Längenangabe (M) oder vor dem Auffüllzeichen eingefügt werden. Entsprechend würden die vorherigen Varianten dann wie folgt lauten:
- %-Ms: Mit Leerzeichen auffüllen.
- %0-Ms oder %-0Ms: Mit Nullen auffüllen.
- %'X-Ms oder %-'XMs: Mit Zeichen X auffüllen.
Beispiel (aufgefüllt wird wieder mit Punkten):
<?php
$str1 = 'abc';
$str2 = 'abcdef';
$str3 = 'abcdefghi';
$str4 = 'abcdefghijkl';
var_dump(
sprintf("%'.-26s", $str1),
sprintf("%'.-26s", $str2),
sprintf("%'.-26s", $str3),
sprintf("%'.-26s", $str4)
);
?>
string(26) "abc......................." string(26) "abcdef...................." string(26) "abcdefghi................." string(26) "abcdefghijkl.............."
4. Integer formatieren
Um einen Integerwert über sprintf() zu formatieren, muss das Zeichen „d” verwendet werden. Ohne jegliche Formatierung wird die Stelle im Formatierungsstring an der die Variable eingefügt werden soll demnach mit „%d” markiert. Wie bei Strings kann eine Minimallänge über %Md (mit Leerzeichen auffüllen), %0Md (mit Nullen auffüllen) oder %'XMd (mit Zeichen X auffüllen) definiert werden. Standardmäßig wird nach links hin aufgefüllt. Für das Auffüllen nach rechts (am Ende des Strings) muss %-Md, %0-Md oder %'X-Md geschrieben werden. Es kann zudem das Anzeigen des Vorzeichens erzwungen werden. Dafür ist ein „+” direkt nach dem Prozentzeichen einzufügen (%+d).
<?php
$x = 1;
// Integer direkt ausgeben
var_dump( sprintf('%d', $x) ); // Ergebnis: "1"
// Integer immer mit Vorzeichen ausgeben
var_dump( sprintf('%+d', $x) ); // Ergebnis: "+1"
// Integer ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen
var_dump( sprintf('%09d', $x) ); // Ergebnis: "000000001"
// Integer ausgeben, immer mit mind. 9 Stellen, am Ende mit "X" auffüllen
var_dump( sprintf('%\'X-9d', $x) ); // Ergebnis: "1XXXXXXXX"
// Integer ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen,
// ".4" ist die Präzision (Nachkommastellen), welche bei Integer keinen Effekt hat
var_dump( sprintf('%09.4d', $x) ); // Ergebnis: "000000001"
?>
string(1) "1" string(2) "+1" string(9) "000000001" string(9) "1 " string(9) "1XXXXXXXX" string(9) "000000001"
5. Float formatieren
Die Formatierung von Floats gleicht der Formatierung von Integern. Statt dem Zeichen „d” wird ein „F” als Markierung verwendet. (Auch „f” ist möglich. Bei Verwendung von „f” wird entsprechend der locale-Einstellungen formatiert — das Trennzeichen für den Nachkommabereich kann dann ein Komma sein, statt dem üblichen Punkt.) Im Rahmen der Float-Formatierung ist die Festlegung der Anzahl der Nachkommastellen möglich. Dazu muss vor dem „F” ein „.M” eingefügt werden, wobei M der Anzahl der Nachkommastellen entspricht. (Ähnlich der Maximallänge bei Strings bzw. %s.)
<?php
$x = 1.1;
// Float direkt ausgeben
var_dump( sprintf('%F', $x) ); // Ergegnis: 1.100000
// Float mit Vorzeichen ausgeben
var_dump( sprintf('%+F', $x) ); // Ergebnis: +1.100000
// Float ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen
var_dump( sprintf('%09F', $x) ); // Ergebnis: 01.100000
// Float ausgeben, immer mit mind. 9 Stellen, am Ende mit "X" auffüllen
var_dump( sprintf('%\'X-9F', $x) ); // Ergebnis: 1.100000X
// Float ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen,
// ".4" ist die Präzision (4 Nachkommastellen)
var_dump( sprintf('%09.4F', $x) ); // Ergebnis: 0001.1000
?>
string(8) "1.100000" string(9) "+1.100000" string(9) "01.100000" string(9) "1.100000X" string(9) "0001.1000"
Weitere Beispiele mit Minimal- und Maximallängen:
<?php
$x = 123456.123456;
var_dump( sprintf('%02F', $x) );
var_dump( sprintf('%.02F', $x) );
var_dump( sprintf('%02.02F', $x) );
var_dump( sprintf('%019F', $x) );
?>
string(13) "123456.123456" string(9) "123456.12" string(9) "123456.12" string(19) "000000123456.123456"
6. Float/Integer zu formatierter Exponentenschreibweise
Floats und Integer können durch Verwendung von %e in die Exponentenschreibweise umgewandelt werden. Die Rückgabe der Formatierung entspricht dem String „FeM”, wobei F ein Float und M ein Integer ist (e ist nicht variabel und signalisiert die Exponentenschreibweise). FeM repräsentiert F*(10^M) (Float F mal 10 hoch M). (Verwendet wird die Exponentenschreibweise fast nie.)
<?php
$x = 13.43;
// Exponentenschreibweise direkt ausgeben
var_dump( sprintf('%e', $x) ); // Ergebnis: 1.343000e+1
// Exponentenschreibweise mit Vorzeichen ausgeben
var_dump( sprintf('%+e', $x) ); // Ergebnis: +1.343000e+1
// Exponentenschreibweise ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen
var_dump( sprintf('%09e', $x) ); // Ergebnis: 1.343000e+1
// Exponentenschreibweise ausgeben, immer mit mind. 9 Stellen, am Ende mit "X" auffüllen
var_dump( sprintf('%\'X-9e', $x) ); // Ergebnis: 1.343000e+1
// Exponentenschreibweise ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen,
// ".2" ist die Präzision (2 Nachkommastellen)
var_dump( sprintf('%09.2e', $x) ); // Ergebnis: 001.34e+1
?>
string(11) "1.343000e+1" string(12) "+1.343000e+1" string(11) "1.343000e+1" string(11) "1.343000e+1" string(9) "001.34e+1"
7. Integer zu formatierter Binärzahl
Über sprintf() können auch Integer zu Binärzahlen umgewandelt werden, ähnlich der Funktion decbin($dezimalwert) (wandelt $dezimalwert in passende Binärzahl als String um). Die Formatierung über sprintf() bietet das Auffüllen nach links und rechts hin (Mindestlänge). Verwendet wird %b als Markierung.
<?php
$x = 125;
// Binärzahl direkt ausgeben
var_dump( sprintf('%b', $x) ); // Ergebnis: 1111101
// Binärzahl mit Vorzeichen ausgeben, hier ohne Auswirkungen
var_dump( sprintf('%+b', $x) ); // Ergebnis: 1111101
// Binärzahl ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen
var_dump( sprintf('%09b', $x) ); // Ergebnis: 001111101
// Binärzahl ausgeben, immer mit mind. 9 Stellen, am Ende mit "0" auffüllen
var_dump( sprintf('%0-9b', $x) ); // Ergebnis: 111110100
// Binärzahl ausgeben, immer mit mind. 9 Stellen, am Ende mit "X" auffüllen
var_dump( sprintf('%\'X-9b', $x) ); // Ergebnis: 1111101XX
// Binärzahl ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen,
// ".4" ist die Präzision (4 Nachkommastellen) und sorgt hier dafür, dass die Binärzahl
// nur noch aus Nullen besteht
var_dump( sprintf('%09.4b', $x) ); // Ergebnis: 000000000
?>
string(7) "1111101" string(7) "1111101" string(9) "001111101" string(9) "111110100" string(9) "1111101XX" string(9) "000000000"
8. Integer zu formatiertem Hex-String
Genauso wie die Formatierung von Integer zu Binärzahl ist auch der Weg von Integer zu Hexadezimalwert möglich. Verwendet wird dann %x (Buchstaben des Hexadezimalwerts klein geschrieben) oder %X (Buchstaben des Hexadezimalwerts groß geschrieben). Wieder steht das Auffüllen nach links oder rechts hin mit Füllzeichen (Mindestlänge) zur Verfügung. Eine weitestgehend ähnliche PHP-Funktion ist dechex($dezimalwert) (wandelt den Integer $dezimalwert in einen Hexadezimalwert als String um).
<?php
$x = 125;
// Hex-Wert direkt ausgeben
var_dump( sprintf('%x', $x) ); // Ergebnis: 7d
// Hex-Wert mit Vorzeichen ausgeben, hier ohne Auswirkungen
var_dump( sprintf('%+x', $x) ); // Ergebnis: 7d
// Hex-Wert ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen
var_dump( sprintf('%09x', $x) ); // Ergebnis: 00000007d
// Hex-Wert ausgeben, immer mit mind. 9 Stellen, am Ende mit "0" auffüllen
var_dump( sprintf('%0-9x', $x) ); // Ergebnis: 7d0000000
// Hex-Wert ausgeben, immer mit mind. 9 Stellen, am Ende mit "X" auffüllen
var_dump( sprintf('%\'X-9x', $x) ); // Ergebnis: 7dXXXXXXX
// Hex-Wert ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen,
// ".4" ist die Präzision (4 Nachkommastellen) und sorgt hier dafür, dass der Hex-Wert
// nur noch aus Nullen besteht
var_dump( sprintf('%09.4x', $x) ); // Ergebnis: 000000000
?>
string(2) "7d" string(2) "7d" string(9) "00000007d" string(9) "7d0000000" string(9) "7dXXXXXXX" string(9) "000000000"
9. Integer zu formatierter Oktalzahl
Analog zur Umwandlung von Integer zu Binärzahl (%b) und Integer zu Hexadezimalwert (%x) erfolgt die Konvertierung von Integer zu Oktalzahl per sprintf(). Verwendet wird dazu %o. Wieder steht die Mindestlänge zur Verfügung (Auffüllen nach links/rechts hin).
<?php
$x = 252;
// Oktalzahl direkt ausgeben
var_dump( sprintf('%o', $x) ); // Ergebnis: 374
// Oktalzahl mit Vorzeichen ausgeben, hier ohne Auswirkungen
var_dump( sprintf('%+o', $x) ); // Ergebnis: 374
// Oktalzahl ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen
var_dump( sprintf('%09o', $x) ); // Ergebnis: 000000374
// Oktalzahl ausgeben, immer mit mind. 9 Stellen, am Ende mit "0" auffüllen
var_dump( sprintf('%0-9o', $x) ); // Ergebnis: 374000000
// Oktalzahl ausgeben, immer mit mind. 9 Stellen, am Ende mit "X" auffüllen
var_dump( sprintf('%\'X-9o', $x) ); // Ergebnis: 374XXXXXX
// Oktalzahl ausgeben, immer mit mind. 9 Stellen, am Anfang mit Nullen auffüllen,
// ".4" ist die Präzision (4 Nachkommastellen) und sorgt hier dafür, dass der Hex-Wert
// nur noch aus Nullen besteht
var_dump( sprintf('%09.4o', $x) ); // Ergebnis: 000000000
?>
string(3) "374" string(3) "374" string(9) "000000374" string(9) "374000000" string(9) "374XXXXXX" string(9) "000000000"
10. Argument Swapping
Parameter bzw. Argumente können mehrmals oder in anderer Reihenfolge verwendet werden indem auf das sogenannte „Argument Swapping” zurückgegriffen wird. Nach dem Prozentzeichen muss dazu die Nummer des Parameters gefolgt von einem Dollarzeichen eingefügt werden. Aus sprintf("%3$s %2$s %1$s", "a", "b", "c") würde daher die Rückgabe „c b a” statt — wie gewohnt — „a b c” ergeben.
<?php // Korrekter Aufbau mit Argument Swapping $format1 = 'Hallo, %1$s! Wie geht es dir, %1$s? %1$s, du hast %2$d neue Nachrichten.'; // Hier wird bei %d am Ende das 2$ vergessen (müsste lauten: %2$d) $format2 = 'Hallo, %1$s! Wie geht es dir, %1$s? %1$s, du hast %d neue Nachrichten.'; // Ganz ohne Argument Swapping: Erzeugt eine Warnung wegen zu wenig uebergebenen Argumenten $format3 = 'Hallo, %s! Wie geht es dir, %s? %s, du hast %d neue Nachrichten.'; $user = 'Testuser'; $count = 12; var_dump( sprintf($format1, $user, $count) ); var_dump( sprintf($format2, $user, $count) ); var_dump( sprintf($format3, $user, $count) ); // Erzeugt eine Warnung, da mehr Parameter abgefragt werden als uebergeben wurden ?>
string(82) "Hallo, Testuser! Wie geht es dir, Testuser? Testuser, du hast 12 neue Nachrichten." string(81) "Hallo, Testuser! Wie geht es dir, Testuser? Testuser, du hast 0 neue Nachrichten." <br /> <b>Warning</b>: sprintf() [<a href='function.sprintf'>function.sprintf</a>]: Too few arguments in <b>...\test.php</b> on line <b>13</b><br /> bool(false)