Numerische Funktionen ermöglichen mathematische Berechnungen und Formatierungen direkt in Ihren Vorlagen. Diese Funktionen sind besonders für Abrechnungen, Preiskalkulationen und statistische Auswertungen unverzichtbar.

Übersicht

Die grundlegenden mathematischen Funktionen helfen bei der Verarbeitung numerischer Werte in Vorlagen.

Funktion	Beschreibung	Beispiel
`abs(zahl)`	Absolutwert einer Zahl	`abs(-15.5)` → 15.5
`round(zahl, [stellen])`	Rundung auf Nachkommastellen	`round(12.456, 2)` → 12.46
`ceil(zahl)`	Aufrundung zur nächsten ganzen Zahl	`ceil(12.1)` → 13.0
`floor(zahl)`	Abrundung zur nächsten ganzen Zahl	`floor(12.9)` → 12.0

Mathematische Operatoren: Für grundlegende arithmetische Operationen wie Addition, Subtraktion, Multiplikation und Division verwenden Sie mathematische Operatoren in Ausdrücken.

Beachten sie auch wie komplexe Ausdrücke in Vorlagen mit Variable verwendet werden können: Ausdrücke und Funktionen.

Rundungsfunktionen

Originalwert: <<{stromverbrauch}>> kWh
Gerundet (0 Stellen): <<{round(stromverbrauch)}>> kWh
Gerundet (2 Stellen): <<{round(stromverbrauch, 2)}>> kWh
Aufgerundet: <<{ceil(stromverbrauch)}>> kWh
Abgerundet: <<{floor(stromverbrauch)}>> kWh
Absolutwert: <<{abs(temperaturdifferenz)}>> °C

Rundungsverhalten: Die round()-Funktion verwendet die mathematische Rundung (0.5 wird aufgerundet). Bei Finanzberechnungen sollten die Werte bereits in den JSON-Daten korrekt gerundet sein.

Vergleichsfunktionen

Min/Max-Berechnungen

Zählerstände im Vergleich:
Zählerstand Vorjahr: <<{zaehlerstand_vorjahr}>> kWh
Zählerstand aktuell: <<{zaehlerstand_aktuell}>> kWh

Niedrigster Wert: <<{min(zaehlerstand_vorjahr, zaehlerstand_aktuell)}>> kWh
Höchster Wert: <<{max(zaehlerstand_vorjahr, zaehlerstand_aktuell)}>> kWh
Verbrauch: <<{{zaehlerstand_aktuell - zaehlerstand_vorjahr}}>> kWh

Mehrere Werte vergleichen: Für den Vergleich von mehr als zwei Werten verwenden Sie verschachtelte Aufrufe: max(max(wert1, wert2), wert3) oder bereiten Sie die Daten entsprechend in JSON vor.

Zahlenformatierung

Formatierung mit numFormat

Die numFormat()-Funktion ist die mächtigste numerische Funktion für die Darstellung von Zahlen, Währungen und Prozentsätzen.

Rechnungsbetrag: <<{numFormat(betrag_netto, '#,##0.00')}>> €
Mit Währungssymbol: <<{numFormat(betrag_netto, '¤#,##0.00', 'DE')}>> 
Prozentsatz: <<{numFormat(effizienz_prozent, '0.0')}>>%
Wissenschaftlich: <<{numFormat(verbrauch_total, '0.0E0')}>> kWh
Mit Vorlaufnullen: <<{numFormat(kundennummer, '000000')}>>

Was sind Locales?

Locales bestimmen die Sprache und regionale Formatierung (z.B. 'DE' für Deutschland, 'US' für USA, 'FR' für Frankreich). Sie steuern Währungssymbole und Zahlenformatierung.

Alle Infos zu Locales finden Sie in der Locale-Dokumentation.

Erweiterte Zahlenformatierung

<<cs_rechnungsdetails>>
Rechnung Nr.: <<{numFormat(rechnungsnummer, '00000')}>>
--------------------------------------------
Grundpreis:     <<{numFormat(grundpreis, '#,##0.00')}>> €
Arbeitspreis:   <<{numFormat(arbeitspreis, '#,##0.00')}>> €
--------------------------------------------
Zwischensumme:  <<{numFormat(zwischensumme, '#,##0.00')}>> €
MwSt (19%):     <<{numFormat(mwst_betrag, '#,##0.00')}>> €
--------------------------------------------
Gesamtbetrag:   <<{numFormat(gesamtbetrag, '#,##0.00')}>> €
<<es_>>

Formatierungs-Tipp: Verwenden Sie das ¤-Symbol in der Formatzeichenkette für automatische Währungssymbole abhängig vom Locale. '¤#,##0.00' zeigt € für 'DE' und $ für 'US'.

Erweiterte mathematische Funktionen

Potenz- und Wurzelfunktionen

Energieverbrauch Berechnungen:
Grundlast: <<{grundlast}>> kW
Spitzenlast: <<{spitzenlast}>> kW

Quadrat der Grundlast: <<{pow(grundlast, 2)}>> kW²
Wurzel der Spitzenlast: <<{round(sqrt(spitzenlast), 2)}>> √kW
Zufallsfaktor (0-1): <<{round(random(), 3)}>>

Validierung numerischer Werte

Datenvalidierung:
Zählerstand: <<{zaehlerstand_input}>>
Ist numerisch: <<{map(isNumber(zaehlerstand_input), true, 'Ja', 'Nein')}>>

<<cs_isNumber(zaehlerstand_input)>>
Validierter Zählerstand: <<{numFormat(zaehlerstand_input, '#,##0.0')}>> kWh
<<else>>
Fehler: Ungültiger Zählerstand eingegeben
<<es_>>

Wichtiger Hinweis: String-Parameter in Funktionen müssen mit einfachen Anführungszeichen (') geschrieben werden: numFormat(wert, '#,##0.00') ist korrekt.

Komplexe Berechnungsbeispiele

Energiekostenberechnung

<<$verbrauch_kwh={{zaehlerstand_neu - zaehlerstand_alt}}>>
<<$grundpreis_jahr={{grundpreis_monat * 12}}>>
<<$arbeitskosten={{verbrauch_kwh * arbeitspreis_kwh}}>>
<<$netto_gesamt={{grundpreis_jahr + arbeitskosten}}>>
<<$mwst_betrag={{netto_gesamt * 0.19}}>>
<<$brutto_gesamt={{netto_gesamt + mwst_betrag}}>>

ENERGIEKOSTENABRECHNUNG
========================
Zählerstand alt:     <<{numFormat(zaehlerstand_alt, '#,##0')}>> kWh
Zählerstand neu:     <<{numFormat(zaehlerstand_neu, '#,##0')}>> kWh
Verbrauch:           <<{numFormat($verbrauch_kwh, '#,##0')}>> kWh

Grundpreis/Jahr:     <<{numFormat($grundpreis_jahr, '#,##0.00')}>> €
Arbeitskosten:       <<{numFormat($arbeitskosten, '#,##0.00')}>> €
                     (<<{numFormat(arbeitspreis_kwh, '0.0000')}>> €/kWh)
------------------------
Netto gesamt:        <<{numFormat($netto_gesamt, '#,##0.00')}>> €
MwSt. (19%):         <<{numFormat($mwst_betrag, '#,##0.00')}>> €
------------------------
Brutto gesamt:       <<{numFormat($brutto_gesamt, '#,##0.00')}>> €

Durchschnitt/Monat:  <<{numFormat({{$brutto_gesamt / 12}}, '#,##0.00')}>> €

Best Practice: Komplexe Berechnungen werden in Variablen zwischengespeichert und dann formatiert ausgegeben. Dies verbessert die Lesbarkeit und Performance der Vorlage.

Formatierungs-Referenz

Format-String	Eingabe	Ausgabe	Verwendung
'#,##0.00'	1234.5	1,234.50	Währungsbeträge
'0.0000'	0.289	0.2890	Preise pro kWh
'000000'	1234	001234	Kundennummern
'0.0E0'	12345.67	1.2E4	Große Zahlen
'¤#,##0.00'	1234.5	€1,234.50	Lokalisierte Währung

Text-Darstellung von Zahlen

Rechnungsbeispiel:
Betrag: <<{numFormat(betrag, '#,##0.00')}>> €
US-Format: $<<{numFormat(betrag, '#,##0.00')}>>

Text-Darstellungen:
Standard: <<{titleCase(numToText(betrag))}>> Euro
US-Dollar: <<{numToDollars(betrag)}>>
Ohne "and": <<{titleCase(numToText(betrag, 'andNone'))}>>
Mit allen "and": <<{titleCase(numToText(betrag, 'andAlways'))}>>

Ordinal-Funktionen (Kundennummer: <<{kundennummer}>>):
Standard: <<{ordinal(kundennummer)}>>
Nur Suffix: <<{kundennummer}>>>>{{ordinal(kundennummer, 'suffix')}}
Ausgeschrieben: <<{ordinal(kundennummer, 'long')}>>
Ohne "and": <<{ordinal(kundennummer, 'longNoAnds')}>>
Alle "and": <<{ordinal(kundennummer, 'longAllAnds')}>>

Position im System: <<{position}>> (<<{ordinal(position, 'long')}>>)

Jahr und römische Zahlen:
Jahr: <<{jahr}>> → <<{toUpperCase(toRoman(jahr))}>>
Kapitel: <<{toRoman(kapitel)}} (klein)

Sprachhinweis: Die Funktionen numToText(), numToDollars() und ordinal() generieren englische Texte. Für deutsche Texte müssen die Zahlen in den JSON-Daten bereits als Text bereitgestellt werden.

Zahlenbereiche: Beide Funktionen unterstützen Zahlen bis zu 9,2 Quintillionen (9.200.000.000.000.000.000).

Spezielle Anwendungsfälle

Rechnungslegung mit Textdarstellung

<<$rechnungsnummer_numerisch={{rechnungsjahr * 10000 + laufende_nummer}}>>

RECHNUNG NR. <<{numFormat($rechnungsnummer_numerisch, '00000000')}>>
================================================================

Rechnungsjahr: <<{rechnungsjahr}>> (<<{toUpperCase(toRoman(rechnungsjahr))}>>)
Laufende Nummer: <<{laufende_nummer}>> (<<{ordinal(laufende_nummer)}>> Rechnung)

Rechnungsbetrag: <<{numFormat(gesamtbetrag, '#,##0.00')}>> €
Betrag in Worten: <<{titleCase(numToText(round(gesamtbetrag, 0)))}>> Euro
                  und <<{numFormat(round({{(gesamtbetrag - floor(gesamtbetrag)) * 100}}, 0), '00')}>> Cent

Position in Kundenliste: <<{ordinal(kundenposition, 'long')}>> Kunde

Römische Zahlen für Dokumente

<<rr_abschnitte>>
<<{toUpperCase(toRoman(index))}>>. <<{titel}>>

  <<rr_unterabschnitte>>
  <<{toUpperCase(toRoman(../index))}>>.<<{index}>> <<{untertitel}>>
  <<er_>>

<<er_>>

Dokument erstellt im Jahr <<{jahr}>> (<<{toUpperCase(toRoman(jahr))}>>)

Anwendungshinweis: Römische Zahlen eignen sich besonders für Kapitel-Nummerierungen, Jahreszahlen in formellen Dokumenten und traditionelle Darstellungen in Verträgen.