sprintf

(PHP 4, PHP 5, PHP 7)

sprintf — Gibt einen formatierten String zurück

Beschreibung

sprintf ( string $format [, mixed $... ] ) : string

Gibt eine anhand des Formatierungs-Strings format gebildete Zeichenkette zurück.

Parameter-Liste

format

Der Formatierungs-String wird aus null oder mehreren Anweisungen gebildet: Gewöhnliche Zeichen (außer %), die direkt in das Ergebnis übertragen werden, und Umsetzungs-Anweisungen. Jede dieser Anweisungen holt sich als Resultat ihre eigenen Parameter. Diese Anweisungen gelten sowohl für die sprintf()- als auch für die printf()-Funktion.

Jede der Formatierungs-Anweisungen besteht aus einem Prozent-Zeichen (%), gefolgt von einem oder mehrereren der folgenden Elemente:

  1. Eine optionale Vorzeichenangabe, die die Verwendung eines Vorzeichens (- oder +) vor einer Zahl erzwingt. Standardmäßig wird nur das - Zeichen vor negativen Zahlen verwendet. Die Vorzeichenangabe erzwingt, dass positive Zahlen ein + Zeichen vorangestellt bekommen.
  2. Ein optionales Füllzeichen, das festlegt, mit welchem Zeichen ein String bis zum Erreichen einer bestimmten Länge aufgefüllt wird. Dies kann ein Leerzeichen oder eine 0 (das Null-Zeichen) sein. Standardmäßig wird mit dem Leerzeichen gefüllt. Andere Füllzeichen können durch Voranstellen eines einfachen Anführungszeichens (') definiert werden. Beachten Sie die nachstehenden Beispiele.
  3. Eine optionale Angabe der Ausrichtung, die bestimmt, ob das Ergebnis rechts- oder linksbündig ausgerichtet werden soll. Das Standardverhalten ist rechtsbündige Ausrichtung, ein --Zeichen an dieser Stelle lässt den Text linksbündig erscheinen.
  4. Eine optionale Zahl für die Längenangabe, welche die mindestens zurückzugebende Anzahl Zeichen spezifiziert.
  5. Eine optionale Genauigkeitsangabe in der Form eines Punktes (.) gefolgt von einem optionalen Dezimalstring. Dieser drückt aus, wieviele Dezimalstellen für Fließkommazahlen ausgegeben werden sollten. Wenn Sie diese Angabe auf einen String anwenden, fungiert sie als Grenzpunkt, der die maximale Zeichenzahl der ausgegebenen Zeichenkette bestimmt. Zusätzlich kann optional das Zeichen, das zum Auffüllen einer Zahl verwendet werden soll, zwischen dem Punkt und der Ziffer angegeben werden.

  6. Eine Typangabe, welche den Typ enthält, als der das jeweils übergebene Argument angesehen werden soll. Mögliche Angaben sind:

    • % - ein Prozentzeichen. Es ist kein Argument erforderlich.
    • b - das Argument wird als Integer angesehen und als Binär-Wert ausgegeben.
    • c - das Argument wird als Integer angesehen, und das entsprechende ASCII-Zeichen wird ausgegeben.
    • d - das Argument wird als Integer angesehen und als vorzeichenbehafteter Dezimalwert (signed integer) ausgegeben.
    • e - das Argument wird als wissenschaftliche Notation betrachtet (z.B. 1.2e+2). Die Genauigkeitsangabe steht seit PHP 5.2.1 für die Anzahl der Dezimalstellen. In früheren PHP-Versionen wurde sie als signifikante Stelle betrachtet (eine Stelle weniger).
    • E - wie %e, mit dem Unterschied, dass ein großes E verwendet wird (z.B. 1.2E+2).
    • f - das Argument wird als float angesehen und entsprechend der Einstellungen in den locales als Fließkommazahl ausgegeben.
    • F - das Argument wird als float angesehen und unabhängig von den Einstellungen in den locales als Fließkommazahl ausgegeben. Verfügbar ab PHP 5.0.3.
    • g - das Kürzere von %e und %f.
    • G - das Kürzere von %E und %F.
    • o - das Argument wird als Integer angesehen und als Oktalzahl ausgegeben.
    • s - das Argument wird als String angesehen und auch als solcher ausgegeben.
    • u - das Argument wird als Integer angesehen und ein positiver vorzeichenloser Dezimalwert (unsigned integer) ausgegeben.
    • x - das Argument wird als Integer angesehen und als Hexadezimalwert ausgegeben (mit Kleinbuchstaben).
    • X - das Argument wird als Integer angesehen und als Hexadezimalwert ausgegeben (mit Großbuchstaben).

Variablen werden in einen für die Typangabe passenden Typ konvertiert:

Typ-Behandlung
Typ Typangaben
string s
integer d, u, c, o, x, X, b
double g, G, e, E, f, F

Warnung

Der Versuch der Verwendung einer Kombination von Stringtyp- und Längenangaben bei Zeichensätzen, die mehr als ein Byte pro Zeichen benötigen, kann zu unerwarteten Ergebnissen führen

Der Formatstring unterstützt nummerierte Argumente und kann daher auch ihre Position bestimmen (argument numbering/swapping). Hier ein Beispiel:

Beispiel #1 Argumente tauschen

<?php
$anzahl = 5;
$ort    = 'Baum';

$format = 'Es sind %d Affen auf dem %s';
echo sprintf($format, $anzahl, $ort);
?>
Dies wird "Es sind 5 Affen auf dem Baum" ausgeben. Aber nehmen wir einmal an, dass wir den Formatstring in einer separaten Datei erstellen, da wir ihn internationalisieren wollen und deshalb wie folgt umschreiben:

Beispiel #2 Argumente tauschen

<?php
$format = 'Der %s enthält %d Affen';
echo sprintf($format, $anzahl, $ort);
?>
Nun haben wir ein Problem. Die Reihenfolge der Platzhalter im Formatstrings entspricht nicht mehr der Reihenfolge der Argumente im Code. Wir würden gern den Code belassen wie er ist und einfach im Formatstring angeben, welche Argumenten welchen Platzhaltern entsprechen. Wir würden dann den Formatstring wie folgt schreiben:

Beispiel #3 Argumente tauschen

<?php
$format = 'Der %2$s enthält %1$d Affen';
echo sprintf($format, $anzahl, $ort);
?>
Ein weiterer Vorteil ist, dass wir nun die Platzhalter wiederholen können, ohne mehr Argumente im Code hinzufügen zu müssen. Zum Beispiel:

Beispiel #4 Argumente tauschen

<?php
$format = 'Der %2$s enthält %1$d Affen.
           %1$d Affen sind ziemlich viel für einen %2$s.';
echo sprintf($format, $anzahl, $ort);
?>
Wenn Argumenttausch verwendet wird muss die n$ Positionsangabe direkt nach dem Prozentzeichen (%) folgen, vor jeglichen anderen Angaben, wie im Beispiel unten zu sehen ist.

Beispiel #5 Angabe von Füllzeichen

<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

......123
000000123

Beispiel #6 Positionstausch mit weiteren Spezifikatoren

<?php
$format= 'Der %2$s enthält %1$04d Affen';
echo sprintf($format, $anzahl, $ort);
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

Der Baum enthält 0005 Affen.

Hinweis:

Der Versuch der Verwendung einer Positionsangabe, die größer als PHP_INT_MAX ist, hat zur Folge, dass sprintf() Warnungen erzeugt.

Warnung

Die c-Typangabe ignoriert Füllzeichen und Längenangabe

...

Rückgabewerte

Gibt eine an Hand des Formatierungs-Strings format gebildete Zeichenkette zurück. Im Fehlerfall wird FALSE zurückgegeben.

Beispiele

Beispiel #7 printf(): Verschiedene Beispiele

<?php
$n =  43951789;
$u = -43951789;
$c = 65; // ASCII 65 is 'A'

// Beachten Sie das doppelte %%, dies gibt ein '%'-Zeichen aus
printf("%%b = '%b'\n", $n); // Binärdarstellung
printf("%%c = '%c'\n", $c); // print the ascii character, same as chr() function
printf("%%d = '%d'\n", $n); // Standard-Integerdarstellung
printf("%%e = '%e'\n", $n); // Wissenschaftliche Notation
printf("%%u = '%u'\n", $n); // vorzeichenlose Integerdarstellung einer positiven Zahl
printf("%%u = '%u'\n", $u); // vorzeichenlose Integerdarstellung einer negativen Zahl
printf("%%f = '%f'\n", $n); // Fließkommazahldarstellung
printf("%%o = '%o'\n", $n); // Oktaldarstellung
printf("%%s = '%s'\n", $n); // Stringdarstellung
printf("%%x = '%x'\n", $n); // Hexadezimaldarstellung (Kleinbuchstaben)
printf("%%X = '%X'\n", $n); // Hexadezimaldarstellung (Großbuchstaben)

printf("%%+d = '%+d'\n", $n); // Vorzeichenangabe für positive Integerzahlen
printf("%%+d = '%+d'\n", $u); // Vorzeichenangabe für negative Integerzahlen
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

%b = '10100111101010011010101101'
%c = 'A'
%d = '43951789'
%e = '4.39518e+7'
%u = '43951789'
%u = '4251015507'
%f = '43951789.000000'
%o = '247523255'
%s = '43951789'
%x = '29ea6ad'
%X = '29EA6AD'
%+d = '+43951789'
%+d = '-43951789'

Beispiel #8 printf(): Stringformatierung

<?php
$s = 'monkey';
$t = 'many monkeys';

printf("[%s]\n",      $s); // normale rechtsbündige Ausgabe
printf("[%10s]\n",    $s); // rechtsbündige Ausgabe, mit Leerzeichen aufgefüllt
printf("[%-10s]\n",   $s); // linksbündige Ausgabe, mit Leerzeichen aufgefüllt
printf("[%010s]\n",   $s); // auffüllen mit Nullen funktioniert auch bei Strings
printf("[%'#10s]\n",  $s); // Verwendung des benutzerdefinierten Auffüllzeichens '#'
printf("[%10.10s]\n", $t); // linksbündige Ausgabe mit abschneiden überflüssiger
                           // Buchstaben nach der zehnten Stelle
?>

Das oben gezeigte Beispiel erzeugt folgende Ausgabe:

[monkey]
[    monkey]
[monkey    ]
[0000monkey]
[####monkey]
[many monke]

Beispiel #9 sprintf(): Mit Nullen aufgefüllte Integer

<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>

Beispiel #10 sprintf(): Währungsformatierung

<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// echo $money gibt "123.1" aus
$formatted = sprintf("%01.2f", $money);
// echo $formatted gibt "123.10" aus
?>

Beispiel #11 sprintf(): Wissenschaftliche Notation

<?php
$number = 362525200;

echo sprintf("%.3e", $number); // Ausgabe 3.625e+8
?>

Siehe auch

  • printf() - Gibt einen formatierten String aus
  • sscanf() - Überträgt einen String in ein angegebenes Format
  • fscanf() - Interpretiert den Input einer Datei entsprechend einem angegebenen Format
  • vsprintf() - Gibt einen formatierten String zurück
  • number_format() - Formatiert eine Zahl mit Tausender-Trennzeichen
  • date() - Formatiert ein(e) angegebene(s) Ortszeit/Datum