cvs: phpdoc-de /reference/strings/functions sprintf.xml

From: Date: Thu, 10 Jul 2008 14:12:50 +0000
Subject: cvs: phpdoc-de /reference/strings/functions sprintf.xml
Groups: php.doc.de 
Request: Send a blank email to doc-de+get-2719@lists.php.net to get a copy of this message
sammywg Thu Jul 10 14:12:50 2008 UTC Modified files: /phpdoc-de/reference/strings/functions sprintf.xml Log: sync to en

http://cvs.php.net/viewvc.cgi/phpdoc-de/reference/strings/functions/sprintf.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc-de/reference/strings/functions/sprintf.xml diff -u phpdoc-de/reference/strings/functions/sprintf.xml:1.6 phpdoc-de/reference/strings/functions/sprintf.xml:1.7 --- phpdoc-de/reference/strings/functions/sprintf.xml:1.6 Wed Jun 18 00:11:20 2008 +++ phpdoc-de/reference/strings/functions/sprintf.xml Thu Jul 10 14:12:50 2008 @@ -1,210 +1,406 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> -<!-- EN-Revision: 1.5 Maintainer: nobody Status: ready --> -<!-- CREDITS: tschuer --> - <refentry xml:id="function.sprintf" xmlns="http://docbook.org/ns/docbook"> - <refnamediv> - <refname>sprintf</refname> - <refpurpose>Gibt einen formatierten String zurück</refpurpose> - </refnamediv> - <refsect1> - <title>Beschreibung:</title> - <methodsynopsis> - <type>string</type><methodname>sprintf</methodname> - <methodparam><type>string</type><parameter>format</parameter></methodparam> - <methodparam choice="opt"><type>mixed</type><parameter>args</parameter></methodparam> - </methodsynopsis> - <simpara> - Gibt einen an Hand des Formatierungs-Strings - <parameter>format</parameter> gebildeten String zurück. - </simpara> - <simpara> - Der Formatierungs-String wird aus keiner oder mehreren Anweisungen - gebildet: Gewöhnliche Zeichen (ausser <literal>%</literal>), die - direkt in das Ergebnis übertragen werden und - <emphasis>Umsetzungs-Anweisungen</emphasis>. Jede dieser - Anweisungen holt sich als Resultat ihre eigenen Parameter. Diese - Anweisungen gelten sowohl für die <function>sprintf</function>- - als auch für die <function>printf</function>-Funktion. - </simpara> - <para> - Jede der Formatierugs-Anweisungen besteht aus einem - Prozent-Zeichen (<literal>%</literal>), gefolgt von einem oder mehrereren - der folgenden Elemente: - <orderedlist> - <listitem> - <simpara> - Einem optionalen <emphasis>Füll-Zeichen</emphasis>, das den - String bis rechts auffüllt. Dies kann ein Leerzeichen oder eine - <literal>0</literal> (das Null-Zeichen) sein. Standardmäßig wird - mit dem Leerzeichen gefüllt. Andere Füllzeichen können durch - Voranstellen eines einfachen Anführungszeichens (<literal>'</literal>) - definiert werden. Beachten Sie die nachstehenden Beispiele. - </simpara> - </listitem> - <listitem> - <simpara> - Einer optionalen Angabe der <emphasis>Ausrichtung</emphasis>, - ob die Ausgabe nach links oder nach rechts (default) ausgerichtet - werden soll. Standardmäßig ist die Ausrichtung rechtsbündig. - Um den Text linksbündig auszurichten müssen Sie das Zeichen - <literal>-</literal> angeben. - </simpara> - </listitem> - <listitem> - <simpara> - Einer optionalen Zahl für die <emphasis>Längen-Angabe</emphasis>, - welche die mindestens zurückzugebende Anzahl Zeichen spezifiziert. - </simpara> - </listitem> - <listitem> - <simpara> - Einem optionalen Wert für die Anzahl der auszugebenden - <emphasis>Dezimalstellen</emphasis> für Fließkommazahlen. Dieser - Wert hat nur Einfluss auf Werte vom Typ <type>float</type> (eine - weitere hilfreiche Funktion zur Formatierung von Zahlen ist - <function>number_format</function>). - </simpara> - </listitem> - <listitem> - <para> - Einer <emphasis>Typ-Angabe</emphasis> welche den Typ enthält, - als der das Argument angesehen werden soll. Mögliche Angaben - sind: - <simplelist> - <member> - <literal>%</literal> - ein Prozent-Zeichen ("%"). Es ist kein - Argument erforderlich. - </member> - <member> - <literal>b</literal> - das Argument wird als Integer - angesehen und als Binär-Wert ausgegeben. - </member> - <member> - <literal>c</literal> - das Argument wird als Integer - angesehen und das entsprechende ASCII-Zeichen wird - ausgegeben. - </member> - <member> - <literal>d</literal> - das Argument wird als Integer - angesehen und ein Dezimalwert (signed) ausgegeben. - </member> - <member> - <literal>u</literal> - das Argument wird als Integer - angesehen und ein Dezimalwert (unsigned) ausgegeben. - </member> - <member> - <literal>f</literal> - das Argument wird als <type>float</type> - angesehen und eine Fließkomma-Zahl ausgegeben. - </member> - <member> - <literal>o</literal> - das Argument wird als Integer - angesehen und und als Oktalzahl ausgegeben. - </member> - <member> - <literal>s</literal> - das Argument wird als String angesehen - und auch als solcher ausgegeben. - </member> - <member> - <literal>x</literal> - das Argument wird als Integer - angesehen und als Hexadezimal-Wert ausgegeben (mit - Kleinbuchstaben). - </member> - <member> - <literal>X</literal> - das Argument wird als Integer - angesehen und als Hexadezimal-Wert ausgegeben (mit - Großbuchstaben). - </member> - </simplelist> - </para> - </listitem> - </orderedlist> - </para> - <para> - Seit PHP 4.0.6 unterstützt der Formatstring auch Argumente zu - numerieren/tauschen. Hier ein Beispiel: - <example> - <title>Argumente tauschen</title> - <programlisting role="php"> -<![CDATA[ -$format = "There are %d monkeys in the %s"; -printf($format,$num,$location); -]]> - </programlisting> - </example> - Dies könnte "There are 5 monkeys in the tree" 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: - <example> - <title>Argumente tauschen</title> - <programlisting role="php"> -<![CDATA[ -$format = "The %s contains %d monkeys"; -printf($format,$num,$location); -]]> - </programlisting> - </example> - Nun haben wir ein Problem. Die Reihenfolge der Platzhalter des - Formatstrings entspricht nicht mehr der Reihenfolge der Argumente im - Code. Wir würden gerne den Code belassen wie er ist, und einfach im - Formatstring angeben, welchen Argumenten die Platzhalter entsprechen. - Wir würden dann den Formatstring wie folt schreiben: - <example> - <title>Argumente tauschen</title> - <programlisting role="php"> -<![CDATA[ -$format = "The %2\$s contains %1\$d monkeys"; -printf($format,$num,$location); -]]> - </programlisting> - </example> - Ein weiterer Vorteil ist, dass wir nun die Platzhalter wiederholen - können, ohne mehr Argumente im Code hinzufügen zu müssen. Zum Beispiel: - <example> - <title>Argumente tauschen</title> - <programlisting role="php"> +<?xml version="1.0" encoding="utf-8"?> +<!-- $Revision: 1.7 $ --> +<!-- EN-Revision: 1.20 Maintainer: sammywg Status: ready --> + +<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sprintf"> + <refnamediv> + <refname>sprintf</refname> + <refpurpose>Gibt einen formatierten String zurück</refpurpose> + </refnamediv> + + <refsect1 role="description"> + &reftitle.description; + <methodsynopsis> + <type>string</type><methodname>sprintf</methodname> + <methodparam><type>string</type><parameter>format</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter>args</parameter></methodparam> + <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam> + </methodsynopsis> + <para> + Gibt eine an Hand des Formatierungs-Strings <parameter>format</parameter> + gebildete Zeichenkette zurück. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>format</parameter></term> + <listitem> + <para> + Der Formatierungs-String wird aus null oder mehreren Anweisungen + gebildet: Gewöhnliche Zeichen (außer <literal>%</literal>), die direkt in + das Ergebnis übertragen werden, und + <emphasis>Umsetzungs-Anweisungen</emphasis>. Jede dieser Anweisungen holt + sich als Resultat ihre eigenen Parameter. Diese Anweisungen gelten sowohl + für die <function>sprintf</function>- als auch für die + <function>printf</function>-Funktion. + </para> + <para> + Jede der Formatierugs-Anweisungen besteht aus einem + Prozent-Zeichen (<literal>%</literal>), gefolgt von einem oder mehrereren + der folgenden Elemente: + <orderedlist> + <listitem> + <simpara> + Eine optionale <emphasis>Vorzeichenangabe</emphasis>, 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, und wurde mit PHP 4.3.0 eingeführt. + </simpara> + </listitem> + <listitem> + <simpara> + Ein optionales <emphasis>Füllzeichen</emphasis>, das festlegt, mit + welchem Zeichen ein String bis zum Erreichen einer bestimmten Länge + aufgefüllt wird. Dies kann ein Leerzeichen oder eine + <literal>0</literal> (das Null-Zeichen) sein. Standardmäßig wird + mit dem Leerzeichen gefüllt. Andere Füllzeichen können durch + Voranstellen eines einfachen Anführungszeichens (<literal>'</literal>) + definiert werden. Beachten Sie die nachstehenden Beispiele. + </simpara> + </listitem> + <listitem> + <simpara> + Eine optionale Angabe der <emphasis>Ausrichtung</emphasis>, die + bestimmt, ob das Ergebnis rechts- oder linksbündig ausgerichtet werden + soll. Das Standardverhalten ist rechtsbündige Ausrichtung, ein + <literal>-</literal>-Zeichen an dieser Stelle lässt den Text + linksbündig erscheinen. + </simpara> + </listitem> + <listitem> + <simpara> + Eine optionale Zahl für die <emphasis>Längenangabe</emphasis>, + welche die mindestens zurückzugebende Anzahl Zeichen spezifiziert. + </simpara> + </listitem> + <listitem> + <simpara> + Ein optionaler Wert für die Anzahl der auszugebenden + <emphasis>Dezimalstellen</emphasis> für Fließkommazahlen. Wenn diese + Anweisung auf einen String angewendet wird, gibt sie die Länge an, + die der resultierende String maximal erreichen kann. Darüber + hinausgehendes wird abgeschnitten. + </simpara> + </listitem> + <listitem> + <para> + Eine <emphasis>Typangabe</emphasis>, welche den Typ enthält, + als der das jeweils übergebene Argument angesehen werden soll. + Mögliche Angaben sind: + <simplelist> + <member> + <literal>%</literal> - ein Prozentzeichen. Es ist kein + Argument erforderlich. + </member> + <member> + <literal>b</literal> - das Argument wird als Integer + angesehen und als Binär-Wert ausgegeben. + </member> + <member> + <literal>c</literal> - das Argument wird als Integer + angesehen, und das entsprechende ASCII-Zeichen wird + ausgegeben. + </member> + <member> + <literal>d</literal> - das Argument wird als Integer + angesehen und als vorzeichenbehafteter Dezimalwert + (signed integer) ausgegeben. + </member> + <member> + <literal>e</literal> - 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). + </member> + <member> + <literal>u</literal> - das Argument wird als Integer + angesehen und ein positiver vorzeichenloser Dezimalwert (unsigned + integer) ausgegeben. + </member> + <member> + <literal>f</literal> - das Argument wird als float angesehen und + entsprechend der Einstellungen in den locales als Fließkommazahl + ausgegeben. + </member> + <member> + <literal>F</literal> - das Argument wird als float angesehen und + unabhängig von den Einstellungen in den locales als Fließkommazahl + ausgegeben. + Verfügbar ab PHP 4.3.10 und PHP 5.0.3. + </member> + <member> + <literal>o</literal> - das Argument wird als Integer + angesehen und als Oktalzahl ausgegeben. + </member> + <member> + <literal>s</literal> - das Argument wird als String angesehen + und auch als solcher ausgegeben. + </member> + <member> + <literal>x</literal> - das Argument wird als Integer + angesehen und als Hexadezimalwert ausgegeben (mit + Kleinbuchstaben). + </member> + <member> + <literal>X</literal> - das Argument wird als Integer + angesehen und als Hexadezimalwert ausgegeben (mit + Großbuchstaben). + </member> + </simplelist> + </para> + </listitem> + </orderedlist> + </para> + <para> + Der Formatstring unterstützt nummerierte Argumente und kann daher auch + ihre Position bestimmen (argument numbering/swapping). Hier ein Beispiel: + <example> + <title>Argumente tauschen</title> + <programlisting role="php"> +<![CDATA[ +<?php +$format = 'There are %d monkeys in the %s'; +printf($format, $num, $location); +?> +]]> + </programlisting> + </example> + Dies könnte "There are 5 monkeys in the tree" 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: + <example> + <title>Argumente tauschen</title> + <programlisting role="php"> +<![CDATA[ +<?php +$format = 'The %s contains %d monkeys'; +printf($format, $num, $location); +?> +]]> + </programlisting> + </example> + 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: + <example> + <title>Argumente tauschen</title> + <programlisting role="php"> <![CDATA[ -$format = "The %2\$s contains %1\$d monkeys. - That's a nice %2\$s full of %1\$d monkeys."; +<?php +$format = 'The %2$s contains %1$d monkeys'; printf($format, $num, $location); +?> +]]> + </programlisting> + </example> + Ein weiterer Vorteil ist, dass wir nun die Platzhalter wiederholen + können, ohne mehr Argumente im Code hinzufügen zu müssen. Zum Beispiel: + <example> + <title>Argumente tauschen</title> + <programlisting role="php"> +<![CDATA[ +<?php +$format = 'The %2$s contains %1$d monkeys. + That\'s a nice %2$s full of %1$d monkeys.'; +printf($format, $num, $location); +?> +]]> + </programlisting> + </example> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>args</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Gibt eine an Hand des Formatierungs-Strings <parameter>format</parameter> + gebildete Zeichenkette zurück. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.0.6</entry> + <entry> + Unterstützung für Argument numbering/swapping hinzugefügt. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><function>printf</function>: Verschiedene Beispiele</title> + <programlisting role="php"> +<![CDATA[ +<?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 +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +%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' +]]> + </screen> + </example> + <example> + <title><function>printf</function>: Stringformatierung</title> + <programlisting role="php"> +<![CDATA[ +<?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 +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +[monkey] +[ monkey] +[monkey ] +[0000monkey] +[####monkey] +[many monke] ]]> - </programlisting> - </example> - </para> - <simpara> - Siehe auch: <function>printf</function>, - <function>sscanf</function>, <function>fscanf</function> und - <function>number_format</function>. - </simpara> - </refsect1> - <refsect1> - <title>Beispiele:</title> - <para> - <example> - <title><function>sprintf</function>: Null-gefüllte Integer-Werte</title> - <programlisting role="php"> -<![CDATA[ -$isodatum = sprintf ("%04d-%02d-%02d", $jahr, $monat, $tag); -]]> - </programlisting> - </example> - <example> - <title><function>sprintf</function>: Währung formatieren</title> - <programlisting role="php"> + </screen> + </example> + <example> + <title><function>sprintf</function>: Mit Nullen aufgefüllte Integer</title> + <programlisting role="php"> <![CDATA[ +<?php +$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day); +?> +]]> + </programlisting> + </example> + <example> + <title><function>sprintf</function>: Währungsformatierung</title> + <programlisting role="php"> +<![CDATA[ +<?php $money1 = 68.75; $money2 = 54.35; $money = $money1 + $money2; -// echo $money wird ausgeben "123.1"; +// echo $money gibt "123.1" aus $formatted = sprintf("%01.2f", $money); -// echo $formatted wird ausgeben "123.10" +// echo $formatted gibt "123.10" aus +?> +]]> + </programlisting> + </example> + <example> + <title><function>sprintf</function>: Wissenschaftliche Notation</title> + <programlisting role="php"> +<![CDATA[ +<?php +$number = 362525200; + +echo sprintf("%.3e", $number); // Ausgabe 3.625e+8 +?> ]]> - </programlisting> - </example> - </para> - </refsect1> - </refentry> + </programlisting> + </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>printf</function></member> + <member><function>sscanf</function></member> + <member><function>fscanf</function></member> + <member><function>vsprintf</function></member> + <member><function>number_format</function></member> + </simplelist> + </para> + </refsect1> + +</refentry> + <!-- Keep this comment at the end of the file Local variables:
« previous php.doc.de (#2719) next »