bcsub — Funktion · PHP-Referenz

Signatur

bcsub(string $num1, string $num2, ?int $scale = null): string

Beschreibung

bcsub gehört zur BCMath-Erweiterung (Binary Calculator) und ermöglicht die genaue Subtraktion von Zahlen beliebiger Größe und Nachkommastellen. Im Gegensatz zu nativen PHP-Gleitkommazahlen (float) unterliegt das Ergebnis keinen binären Rundungsfehlern, da intern mit dezimalen Zeichenketten gerechnet wird.

Der optionale Parameter scale bestimmt, wie viele Dezimalstellen das Ergebnis haben soll. Wird er nicht übergeben, greift der global gesetzte Wert aus bcscale(), oder der Standardwert 0 bei nicht gesetztem Wert. Nachkommastellen des Ergebnisses werden abgeschnitten, nicht gerundet.

Typische Einsatzgebiete sind Finanzsoftware (Berechnung von Beträgen, Steuern, Wechselgeld), wissenschaftliche Berechnungen mit hoher Präzision sowie der Umgang mit sehr großen Ganzzahlen, die den Wertebereich von PHP-int und float übersteigen würden.

Beide Zahlen werden als Zeichenketten übergeben, sodass auch sehr lange Zahlen verlustfrei dargestellt werden können.
Negative Ergebnisse werden mit einem führenden Minuszeichen zurückgegeben, z. B. "-1.50".

Parameter

Name	Typ	Default	Beschreibung
$num1 Pflicht	string		Der Minuend – die Zahl, von der subtrahiert wird. Wird als dezimale Zeichenkette übergeben, z. B. `"10.50"`.
$num2 Pflicht	string		Der Subtrahend – die Zahl, die von `num1` abgezogen wird. Wird als dezimale Zeichenkette übergeben, z. B. `"3.25"`.
$scale	?int	null	Anzahl der Dezimalstellen im Ergebnis. Wenn `null`, wird der Wert aus `bcscale()` verwendet; ist auch dieser nicht gesetzt, gilt `0`. Das Ergebnis wird auf diese Anzahl Stellen abgeschnitten (nicht gerundet).

Rückgabewert

Typ

string

Beschreibung

Das Ergebnis der Subtraktion als dezimale Zeichenkette mit der angegebenen Anzahl von Nachkommastellen. Negative Ergebnisse erhalten ein führendes Minuszeichen. Bei einem scale-Wert von 0 enthält die Zeichenkette keine Dezimalstellen.

Beispiele

Einfache Subtraktion mit Nachkommastellen

<?php
$ergebnis = bcsub('10.50', '3.25', 2);
echo $ergebnis; // Ausgabe: 7.25

// Ohne scale: Nachkommastellen werden abgeschnitten
$ganzzahl = bcsub('10.99', '3.01');
echo $ganzzahl; // Ausgabe: 7

7.25 7

Finanzberechnung: Wechselgeld berechnen

<?php
// Kassierer-Szenario: Kunde zahlt 50,00 EUR, Betrag ist 34,87 EUR
$bezahlt  = '50.00';
$betrag   = '34.87';
$wechselgeld = bcsub($bezahlt, $betrag, 2);
echo 'Wechselgeld: ' . $wechselgeld . ' EUR'; // Ausgabe: Wechselgeld: 15.13 EUR

Wechselgeld: 15.13 EUR

Subtraktion sehr großer Ganzzahlen (jenseits des int-Bereichs)

<?php
$a = '99999999999999999999';
$b = '11111111111111111111';
echo bcsub($a, $b, 0); // Ausgabe: 88888888888888888888

88888888888888888888

Globalen Scale mit bcscale() setzen

<?php
bcscale(4); // Ab hier gilt scale=4 als Standard

$result = bcsub('1.123456', '0.000001');
echo $result; // Ausgabe: 1.1234 (abgeschnitten auf 4 Stellen)

1.1234

// Wichtig · Fallstricke

Abschneiden statt Runden: BCMath rundet das Ergebnis nicht, sondern schneidet überschüssige Dezimalstellen einfach ab. Wer kaufmännisches Runden benötigt, muss das Ergebnis anschließend z. B. mit bcadd(..., '0.005', 2) vor dem Abschneiden korrigieren oder round() auf den String-Wert anwenden.

Ungültige Eingaben: Übergibt man eine nicht-numerische Zeichenkette, interpretiert BCMath sie als 0 und gibt keine Warnung aus (ab PHP 8.0 wird jedoch ein ValueError ausgelöst). Benutzereingaben sollten daher vorher validiert werden.

Voraussetzung: Die BCMath-Erweiterung muss aktiviert sein. In den meisten PHP-Standardinstallationen ist sie bereits enthalten. Alternativ kann --enable-bcmath beim Kompilieren gesetzt werden.

Siehe auch

bcadd bcmul bcdiv bcmod bccomp bcscale bcpow