Formatiert eine Zahl als Währungs-Zeichenkette

Beschreibung

money_format ( string $format , float $number ) : string

money_format() gibt eine formatierte Version von number zurück. Diese Funktion nutzt die C Funktion strfmon(), mit dem Unterschied, dass diese Implementierung jeweils nur eine Zahl auf einmal konvertiert.

Parameter-Liste

format

Die Formatangabe besteht aus folgender Sequenz:

ein % Zeichen
optionales Flag
optionale Feldbreite
optionale Links-Genauigkeit
optionale Rechts-Genauigkeit
ein erforderliches Umwandlungszeichen

Flags

Eines oder mehrere der folgenden optionalen Flags können benutzt werden:

=f: Das Zeichen = , gefolgt von einem (single byte) Zeichen f wird als numerisches Füllzeichen benutzt. Das Standard-Füllzeichen ist das Leerzeichen.
^: Deaktiviert die Verwendung von Gruppierungszeichen (wie in der aktuellen locale-Einstellung definiert).
+ or (: Gibt den Formatierungsstil für positive und negative Zahlen an. Wird + benutzt, wird das locale Äquivalent für + und - benutzt. Wird ( benutzt, werden negative Beträge von Klammern umschlossen. Ist kein Formatierungsstil angegeben, wird der Standardwert + benutzt.
!: Unterdrückt das Währungssymbol aus dem Ausgabestring.
-: Falls vorhanden, werden alle Felder linksbündig angeordnet, im Gegensatz zum Standardverhalten, welches die Felder rechtsbündig anordnet.

Feldbreite

w: Eine aus dezimalen Ziffern bestehende Zeichenkette, die die Mindestfeldbreite angibt. Das Feld wird rechtbündig ausgerichtet, es sei denn, das Flag - wird verwendet. Der Standardwert ist 0 (Null).

Links-Genauigkeit

#n

Die Höchstanzahl von Ziffern (n), die links vom Dezimaltrenner (z.B. dem Dezimalkomma) erwartet werden. Dies wird üblicherweise verwendet, um die formatierten Ausgabe an derselben Spalte auszurichten, wobei das Füllzeichen verwendet wird, wenn die Ziffernanzahl kleiner ist als n. Ist die Anzahl der tatsächlichen Ziffern größer als n, dann wird diese Angabe ignoriert.

Wurde die Gruppierung durch Verwendung des ^ Flags nicht unterdrückt, werden die Gruppentrennzeichen eingefügt, bevor die Füllzeichen (falls es welche gibt) ergänzt werden. Gruppentrenner werden nicht auf die Füllzeichen angewandt, auch wenn das Füllzeichen eine Ziffer sein sollte.

Um die Ausrichtung zu gewährleisten, werden jegliche Zeichen vor oder nach der Zahl in der formatierten Ausgabe, wie etwa Währungs- oder Vorzeichen, mit Leerzeichen aufgefüllt, so dass die positiven und negativen Formate die gleiche Länge haben.

Rechts-Genauigkeit

.p: Ein Punkt, gefolgt von der Ziffernanzahl (p) nach dem Dezimaltrenner. Ist der Wert von p gleich 0 (Null), wird der Dezimaltrenner und die Ziffern rechts davon ausgelassen. Ist keine Rechts-Genauigkeit angegeben, wird der Standardwert durch das aktuelle Locale bestimmt. Der zu formatierende Betrag wird vor der Formatierung auf die angegebene Ziffernanzahl gerundet.

Umwandlungszeichen

i: Die Zahl wird gemäß des internationalen Währungsformats des Locale formatiert (z.B. für das USA Locale: USD 1,234.56).
n: Die Zahl wird gemäß des nationalen Währungsformats des Locale formatiert (z.B. für das de_DE Locale: EU1.234,56).
%: Gibt das %-Zeichen zurück.

number

Die zu formatierende Zahl.

Rückgabewerte

Gibt die formatierte Zeichenkette zurück. Zeichen vor und nach der Formatzeichenkette werden unverändert zurückgegeben. Eine nicht-numerische number führt zur Rückgabe von NULL, und dem Erzeugen eines E_WARNING.

Anmerkungen

Hinweis:
Die Funktion money_format() ist nur definiert, wenn das System strfmon unterstützt. Beispielsweise ist dies unter Windows nicht so, so dass money_format() unter Windows nicht definiert ist.

Hinweis:
Die Kategorie LC_MONETARY der Locale-Einstellungen hat Einfluss auf das Verhalten dieser Funktion. setlocal() ist zu verwenden, um das gewünschte Locale einzustellen bevor diese Funktion verwendet wird.

Beispiele

Beispiel #1 money_format() Beispiel

Wir verwenden unterschiedliche Locales und Formatangaben, um die Verwendung dieser Funktion zu verdeutlichen.


<?php

$number = 1234.56;

// wir geben das internationale Format für das  en_US Locale aus
setlocale(LC_MONETARY, 'en_US');
echo money_format('%i', $number) . "\n";
// USD 1,234.56

// das italienische nationale Format mit 2 Dezimalstellen
setlocale(LC_MONETARY, 'it_IT');
echo money_format('%.2n', $number) . "\n";
// Eu 1.234,56

// Verwendung einer negativen Zahl
$number = -1234.5672;

// das national US Format, unter Verwendung von () für negative Zahlen
// und 10 Ziffern für die Links-Genauigkeit
setlocale(LC_MONETARY, 'en_US');
echo money_format('%(#10n', $number) . "\n";
// ($        1,234.57)

// ein ähnliches Format wie zuvor, aber mit zusätzlich 2 Ziffern
// Rechts-Genauigkeit und '*' al Füllzeichen
echo money_format('%=*(#10.2n', $number) . "\n";
// ($********1,234.57)

// wir richten linksbündig aus, mit 14 Zeichen Breite, 8 Ziffern
// Links-Genauigkeit, 2 Rechts-Genauigkeit, ohne Gruppentrenner
// und unter Verwendung des internationalen Formats für das de_DE Locale.
setlocale(LC_MONETARY, 'de_DE');
echo money_format('%=*^-14#8.2i', 1234.56) . "\n";
// Eu 1234,56****

// wir ergänzen etwas Text vor und nach der Formatangabe
setlocale(LC_MONETARY, 'en_GB');
$fmt = 'Der Endwert ist %i (mit 10%% Nachlass)';
echo money_format($fmt, 1234.56) . "\n";
// Der Endwert ist  GBP 1,234.56 (mit 10% Nachlass)

?>

Siehe auch

setlocale() - Legt regionale (locale) Einstellungen fest
sscanf() - Überträgt einen String in ein angegebenes Format
sprintf() - Gibt einen formatierten String zurück
printf() - Gibt einen formatierten String aus
number_format() - Formatiert eine Zahl mit Tausender-Trennzeichen