Wikipedia:Lua/Modul/FormatNum/de

Vorlagenprogrammierung	Diskussionen	Lua			Test	Unterseiten
		Modul	Deutsch	English		Modul:	Dokumentation

A Weidaloatung mocha

FormatNum – zum Runden und Formatieren von Zahlen. Es stehen verschiedene Rundungs- und Formatierungsvarianten zur Verfügung.

Funktionen für Vorlagen

format

Diese Funktion formatiert eine Zahl entsprechend dem angegebenen Format. Zur Eingabe sind alle Zahlen geeignet, die als Dezimaltrennzeichen den Punkt verwenden, keine Tausendertrennzeichen haben und nicht in Exponentialschreibweise vorliegen sowie nur ASCII-Zeichen enthalten. Siehe #Formatierungsoptionen.

Parameter

1

Bisher unformatierte (aber ggf. gerundete) Gleitkomma- oder Ganzzahl.

Pflichtparameter.

2

Eine der zur Verfügung stehenden Formatierungsoptionen. Momentan sind das at, ch, ch_currency, comma, de, dewiki, de_currency, en, iso31_0, iso31_0_point and pc.

Optional; Vorgabe: dewiki

Rückgabewert

Formatierte Zahl. Sollte ein ungültiges Argument für 2 angegeben werden oder es sich bei 1 nicht um eine gültige Zahl handeln, so wird 1 unverändert zurückgegeben.

minus

Ein vorhandenes Unicode-Minuszeichen U+2212 = 8722₁₀ wird durch einen ASCII-Bindestrich U+002D ersetzt; oder umgekehrt.

Parameter

1

Zahl.

Pflichtparameter.

2

Umwandlung in U+002D .

Optional; Vorgabe: 0 = →ASCII (boolesch)

Rückgabewert

Zahl mit ASCII-Bindestrich statt Minuszeichen; oder umgekehrt.

padding

Links- oder rechtsbündiges Auffüllen mit nicht-kopierbarem Weißraum. Die Zahl wird links oder rechts bis zum Dezimaltrennzeichen so aufgefüllt, dass alle Zahlen untereinander das Dezimaltrennzeichen an der gleichen Position haben, falls die Ausdehnung des Weißraums geeignet gewählt wurde.

Parameter

1

Zahl.

Pflichtparameter.

2

Ausdehnung des Weißraums. Zahlen größer Null geben die erwarteten Nachkommastellen an. Sind weniger signifikante Stellen vorhanden, wird rechts mit entsprechend breitem Weißraum aufgefüllt. Bei einer Ausdehnung kleiner Null werden Zahlen, die weniger Zeichen vor dem Dezimaltrennzeichen haben, links mit Weißraum aufgefüllt; die Angabe muss also betragsmäßig zur größten erwarteten Zahl passen.

Pflichtparameter.

3

Dezimaltrennzeichen.

Pflichtparameter.

Rückgabewert

Ggf. adjustierte Zahl.

roman2number

Römische Zahl in numerische Ganzzahl wandeln.

Parameter

1

Römische Zahl.

Pflichtparameter.

2

Lua-pattern für erlaubten Suffix.

Typischerweise etwas wie %.$ – fordert einen Ordinalpunkt nach der römischen Zahl; oder %.?$ (optional).

Rückgabewert

Positive Ganzzahl, wenn erfolgreich.

leer, wenn nicht interpretierbar.

round

Diese Funktion wird zum Runden von Zahlen verwendet. Die Ausgabe ist eine Zeichenkette mit der entsprechenden Anzahl signifikanter Stellen. Zur Eingabe sind alle Zahlen geeignet, die sich mit der Lua-Methode tonumber() parsen lassen.

Parameter

1

Zu rundende Gleitkomma- oder Ganzzahl. Die Zahl muss im PC-lesbaren Format (Punkt als Dezimaltrennzeichen, keine Tausendertrennzeichen, ASCII-Minuszeichen) angegeben sein, so dass sie mittels tonumber() umwandelbar ist.

Pflichtparameter.

2

Ganze Zahl (wird mittels tonumber() umgewandelt), die die Anzahl signifikanter Stellen angibt. Ist diese Zahl nicht-negativ, so handelt es sich um die Nachkommastellen. Sollte diese Zahl negativ sein, so wird der ganzzahlige Anteil der Zahl ebenfalls gerundet (-1 entspricht Rundung auf volle Zehner, -2 auf volle Hunderter, …).

Pflichtparameter.

method

Zahl, welche die zu verwendende Rundungsmethode beschreibt.

• 0 – Rundung nach IEEE 754 (round half to even).
• 1 – Kaufmännisches Runden inklusive Eliminierung von "-0"-Ergebnissen.

Optional; Vorgabe: 0

format

Formatierung mittels format integriert auslösen.

Der Wert ist die Formatierungsmethode.

Die Zuweisung eines leeren Werts verwendet die Standardmethode (dewiki).

padding

Formatierung mittels format und padding integriert auslösen.

Der Wert ist die Ausdehnung des Weißraums. Die Formatierungsmethode ist die Standardmethode, falls nicht mit format= spezifiziert. Das Dezimaltrennzeichen ergibt sich aus der Formatierungsmethode.

Optional

Rückgabewert

Zeichenkette der entsprechend der Rundungsmethode auf die vorgegebene Anzahl signifikanter Stellen gerundeten Zahl (zunächst PC-kompatible Schreibweise ohne Formatierung). Diese kann mit der Funktion format weiter formatiert werden, oder das durch die Parameter format= bzw. padding= ausgelöst werden.

Sollte sich eines der übergebenen Argumente nicht parsen lassen, so wird der String des Arguments 1 unverändert zurückgegeben.

War der Eingabewert eine Gleitkommazahl (mit Dezimalpunkt), so ist das Ergebnis eine Gleitkommazahl mit Dezimalpunkt, war die Eingabe eine ganze Zahl, dann soll das Ergebnis auch eine ganze Zahl sein. Trägt die Anzahl signifikanter Stellen ein Minuszeichen (einschließlich -0), so ist das Ergebnis immer eine ganze Zahl.

failsafe

Diese Funktion gibt die Versionsbezeichnung des Moduls aus.

Die Failsafe-Schnittstelle erlaubt den damit ausgerüsteten Modulen in globaler Verteilung

• sicherzustellen, dass eine von einer Vorlage oder einem Modul benötigte Funktion in der lokalen Kopie eines Bibliotheksmoduls vorhanden ist, und ggf. auch in einer erforderlichen Mindestversion;
• die globale Aktualisierung und Verknüpfung von Modulen über Wikidata zu verwalten.

Die Failsafe-Schnittstelle liegt sowohl auf Ebene der Vorlagen wie auch in direktem Lua-Zugriff vor.

Die Funktionen sind im Einzelnen (nicht alle werden bereits überall in vollem Umfang unterstützt):

Parameter

Wert	Ergebnis	aktuell
nichts false	lokale Version	»2020-08-06«
Mindest­version	Mindestversionsbezeichnung Datum im ISO-Format Es wird verglichen, ob das aktuelle Modul diese Version oder später erfüllt. leer, falls Mindestversion nicht erfüllt	2001-01-01 → »2020-08-06« 2099-01-01 → »«
wikidata	Versionsbezeichnung der globalen Mutter Versionsbezeichnung auf Wikidata lokal, falls dort keine gefunden	»2020-08-06«
~	Übereinstimmung der lokalen mit der auf Wikidata registrierten Versionsbezeichnung leer, falls aktuell Versionsbezeichnung auf Wikidata, falls ungleich	»«
@	Ist die aktuelle (Modul-)Seite richtig mit Wikidata verknüpft? leer, falls mit dem richtigen Item verknüpft Item-ID, falls nicht	»Q15709679«
Der Rückgabewert ist in der Vorlagenprogrammierung leer und per Lua false; andernfalls die angegebene Zeichenkette.

Formatierungsoptionen

Format	Dezimal- trenn- zeichen	Tausender- trennzeichen (TTZ)	TTZ ab Länge	TTZ nur Ganzzahl- teil	Beispiele
de	,	Schmaler Weißraum	5*	nein	123,456 1 234,567 12 345,678 1 234,567 8 12 345,567 8	-123,456 -1 234,567 -12 345,678 -1 234,567 8 -12 345,567 8
de_currency dewiki	,	.	5	ja	123,456 1.234,567 12.345,678 1.234,5678 12.345,5678	-123,456 -1.234,567 -12.345,678 -1.234,5678 -12.345,5678
ch	,	'	5	ja	123,456 1234,567 12'345,678 1234,5678 12'345,5678	-123,456 -1234,567 -12'345,678 -1234,5678 -12'345,5678
ch_currency	.	'	5	ja	123.456 1234.567 12'345.678 1234.5678 12'345.5678	-123.456 -1234.567 -12'345.678 -1234.5678 -12'345.5678
en	.	,	4	ja	123.456 1,234.567 12,345.678 1,234.5678 12,345.5678	-123.456 -1,234.567 -12,345.678 -1,234.5678 -12,345.5678
iso31_0 at	,	Schmaler Weißraum	4	nein	123,456 1 234,567 12 345,678 1 234,567 8 12 345,567 8	-123,456 -1 234,567 -12 345,678 -1 234,567 8 -12 345,567 8
iso31_0_point	.	Schmaler Weißraum	4	nein	123.456 1 234.567 12 345.678 1 234.567 8 12 345.567 8	-123.456 -1 234.567 -12 345.678 -1 234.567 8 -12 345.567 8
pc	.				123.456 1234.567 12345.678 1234.5678 12345.5678	-123.456 -1234.567 -12345.678 -1234.5678 -12345.5678
comma	,				123,456 1234,567 12345,678 1234,5678 12345,5678	-123,456 -1234,567 -12345,678 -1234,5678 -12345,5678

* Da das Tausendertrennzeichen auch für den Nachkommaanteil gilt, findet die Länge 5 nur Beachtung, wenn ein Nachkommaanteil mit maximal 3 Stellen existiert. Bei 4 oder mehr Stellen Nachkommaanteil wird der Ganzzahlanteil auch mit nur 4 Stellen unterteilt.

Funktionen für Lua-Module

Einbindung über require():

local lucky, FormatNum = pcall( require, "Module:FormatNum" )
if type( FormatNum ) == "table" then
    FormatNum = FormatNum.FormatNum()
else
    -- Fehlerfall; FormatNum enthält Fehlermeldung
    return "<span class=\"error\">" .. FormatNum .. "</span>"
end

FormatNum.format(source, spec, meet)

• source: string
• spec: optional string
• meet: optional number (Ausdehnung für internes padding)

FormatNum.minus(source, larger)

• source: string
• larger: optional boolean (Umwandlung in Unicode)

FormatNum.padding(source, meet, stop)

• source: string
• meet: number
• stop: string

FormatNum.roman2number(source, suffix)

• source: string
• suffix: optional string

FormatNum.round(source, precision, method)

• source: string
• precision: number
• method: optional number

FormatNum.format(assert)

• assert: optional string

FormatNum.failsafe(atleast)

• atleast: optional string; Minimalversion oder wikidata

Returns string or false.

FormatNum()

Liefert table mit dem Zugriff auf die Funktionen (siehe oben).

Interna

ROUND_TO_EVEN

Interne Konstante für Rundung nach IEEE 754 (0).

ROUND_AWAY_FROM_ZERO

Interne Konstante für kaufmännische Rundung (1).

FORMAT_TABLE

Diese interne Tabelle enthält die Formatierungsoptionen entsprechend obiger Aufstellung. Für jede Formatierung existieren die Einträge decimalMark (Dezimaltrennzeichen), groupMark (Tausendertrennzeichen), groupMinLength (Länge des Ganzzahlanteils, ab dem das Tausendertrennzeichen zur Anwendung kommt) und groupOnlyIntegerPart (ob nur der Ganzzahlanteil gruppiert wird).

Die Tabelle für die Formatierung pc sollte nicht definiert sein (dadurch wird ein Abbruch erreicht und die Zahl direkt unverändert zurückgegeben).

DIGIT_GROUPING_SIZE

Interne Konstante, die die Anzahl der Ziffern pro Gruppe angibt (3).

DEFAULT_FORMAT

Interne Konstante, die die Standardformatierungsmethode für diese Installation festlegt (dewiki).

DEFAULT_METHOD

Interne Konstante, die die Standardrundungsmethode für diese Installation festlegt ([[#ROUND_TO_EVEN|]]).

SPACER_SPAN

Interne Konstante, die einen schmalen Weißraum in ASCII und HTML produziert.

THIN_SPACE

Interne Konstante, die einen nicht-umbrechenden schmalen Weißraum darstellt, und auf die zurückgefallen wird, falls [[#SPACER_SPAN|]] undefiniert ist.

PADDING_SPAN

Interne Konstante, die für die padding-Methoden einen nichtkopierbaren Weißraum in ASCII und HTML produziert.

internal NumberToString()

Von round intern aufgerufene Funktion zur Rundung. Beim Aufruf sind sämtliche Parameter bereits im numerischen Format.

internal FormatNumber()

Von format intern aufgerufenen Funktion zur Formatierung. Die zu formatierende Zahl ist hier bereits auf Gültigkeit geprüft und ohne Vorzeichen (wird hinterher rekonstruiert). Statt einer allgemeinen Formatierungsoption werden hier die der Formatierung entsprechenden Einzelwerte aus FORMAT_TABLE übergeben.

Entwicklung

Dies war das erste produktiv eingesetzte Modul in der deutschsprachigen Wikipedia. In der Pionierphase war vieles im Umgang mit Lua noch unklar gewesen. Inzwischen sind die Erkenntnisse gewachsen, und eine Restrukturierung wurde erforderlich.

• Die Basisfunktionen werden jetzt auch als Bibliothek direkt für andere Lua-Module verfügbar gemacht.
• Die Basisfunktionen blieben unverändert.
• Parameterwerte erhielten Default-Werte und kürzere Namen; auch für die beiden Funktionen.

Mehr kosmetischer Natur:

• Der Präfix internal ist nicht mehr erforderlich.
  • Durch das local in der Definition wird das bereits zum Ausdruck gebracht. Globale Namen, die in Konflikt treten, gibt es nicht oder würde es langfristig nicht mehr geben; falls doch noch, würde dieses local sie zuverlässig überdecken.
• Die zwingend erforderlichen Werte als erste Parameter wurden zu unbenannten Parametern.
• Alle angegebenen Parameter von #invoke führen zu Zeichenketten; „String“ braucht nicht erwähnt zu werden. Vorlagenprogrammierer können sowieso nichts anderes unternehmen.
• Bei einzeiligen oder kurzen Kommentaren wurden die potentiell mehrzeiligen Kommentarblöcke reduziert.

Verwendung

Allgemein in beliebigen Vorlagen direkt nutzbar.

• Vorlage:FormatNum
• Vorlage:FormatZahl
• Unterstützung für Kategorie:Vorlage:Zahlenformatierung

Abhängigkeiten

Keine.