Quöntext voh da Seiten Wikipedia:Lua/Modul/DateTime/de auhschauh

{{LuaModuleDoc}}
<onlyinclude>'''<code>DateTime</code>''' – Modul mit Funktionen für die Interpretation von Datums- und Zeitangaben, sowie ihre Berechnung und Vergleich, schließlich die Darstellung.

Das Modul ist für solche Aufgaben vorgesehen, die die Leistungsfähigkeit der [[Hilfe:Vorlagenprogrammierung#Funktion time|Parserfunktionen]] <code>#time</code> und <code>#timel</code> übersteigen.

Alle zweifelsfreien Datumsformate für den deutsch- und englischsprachigen Raum werden bei der Eingabe unterstützt.

<noinclude>__TOC__</noinclude>
== {{Anker|Vorlage}} Funktionen für Vorlagen ==

=== format ===
Formatiere eine Datums-/Zeitangabe.

''Parameter (alle optional; umgebender Whitespace wird ignoriert):''
; 1
: Angabe von Datum oder Uhrzeit
: <code>now</code> – ''jetzt'' (Vorgabe)
: Interpretierbares Format; Beispiele siehe [[Wikipedia:Lua/Modul/DateTime/Test|Testseite]].
: Führendes <code>#</code> gibt die Anzahl der Sekunden seit 1. Januar 1970 (UTC) an (Unix-Zeit).
: <code>&amp;nbsp;</code> usw. werden als Leerzeichen behandelt.
; 2 {{Anker|format-2}}
: Formatspezifikation
:* wie für [[Hilfe:Vorlagenprogrammierung#Funktion time|<tt>#time</tt>]]
:* gemäß [[#formatspec|besonderer Vereinbarung]]
; lang {{Anker|format-lang}}
: Besondere Sprachbezeichnung (Kürzel gemäß [[ISO 639]])
:* Mögliche Werte: <code>de</code> (Vorgabe); <code>de-AT</code> sowie wohl [[Wikipedia:Sprachen|alle Sprachen, in denen eine Wikipedia existiert]]. Bei unbekannter Sprachvariante wird auf die Basissprache zurückgefallen. Groß- und Kleinschreibung wird ignoriert.
; shift {{Anker|format-shift}}
: Verschiebung
: wie für [[Hilfe:Vorlagenprogrammierung#Funktion time|<tt>#time</tt>]] (2.&nbsp;Parameter)
:* Mögliche Werte: <code>1 day</code> oder <code style="white-space:nowrap">2 years ago</code> sowie <code style="white-space:nowrap">-5 months</code> usw.
:* Die Angaben <code>tomorrow</code> oder <code>yesterday</code> wie auch <code style="white-space:nowrap">next Friday</code> sind nur möglich, wenn sich '''1''' auf <code>now</code> bezieht.
:* Anders als bei <tt>#time</tt> ist ansonsten auch die Angabe eines Basiszeitpunkts möglich.
:* Eine einzelne Zahl ohne Maßeinheit wird als Anzahl von Sekunden interpretiert, positiv/negativ, muss nicht ganzzahlig sein (Dezimalpunkt).
:* Wie bei <tt>#time</tt> kann es bei Überschreitung von Monats- oder Jahresgrenzen durch andere als glatte Intervalle zu unvorhergesehenen Ergebnissen kommen; was der 31.&nbsp;Mai plus 1&nbsp;Monat sein soll, bleibt ohnehin unklar.
; noerror {{Anker|format-noerror}}
: Fehlermeldung unterdrücken
:* Mögliche Werte: nichts oder <code>0</code> (Vorgabe); <code>1</code> sonst
:* Standardmäßig wird eine mit <code>class="error"</code> markierte Meldung gezeigt.
:* Wenn sich bei <code>noerror=1</code> ein leerer Wert ergibt, war der Eingabewert ungültig.
''Ergebnis:'' Formatierte Angabe.
* Anders als bei der Parserfunktion führen fehlende Angaben in der Eingabe jedoch nicht dazu, dass es zu Fehlern oder unerwünschten Ergänzungen kommt; sondern der Ausgabewert wird möglichst auf die Elemente beschränkt, die auch angegeben wurden.
; errCat {{Anker|format-errCat}}
: Ein oder mehrere Titel von Wartungskategorien.
: Die Titel sind durch Pipe-Symbol (per <code>&#123;{!}&#125;</code>) zu trennen.
: Beispiel: <code>errCat=[[:Kategorie:Wikipedia:Vorlagenfehler/Parameter:Datum|Wikipedia:Vorlagenfehler/Parameter:Datum]]</code>

==== Standardformate ====
{| class="wikitable" id="formatspec"
|+ Zusätzliche Formatspezifikationen über <code>#time</code> hinaus (nur deutschsprachig)
|-
!rowspan="2"| Bezeichner
!rowspan="2"| Beispielausgabe
!colspan="2"| geschütztes Leerzeichen zwischen
! Monatsname bis 4&nbsp;Buchstaben nicht abkürzen
|-
! Punkt und Monatsname
! Monatsname und Jahreszahl
|-
| ''keine Angabe''
| →''ISO-T''
|-
| <code>ISO</code>
| <code>{{#invoke:DateTime|format|2=ISO}}</code>
|-
| <code>ISO-T</code>
| <code>{{#invoke:DateTime|format|now|ISO-T}}</code>
|-
| <code>timestamp</code>
| <code>{{#timel:Ymdhis}}</code>
|-
| <code style="white-space:nowrap">T._Monat JJJJ hh:mm:ss Zone</code>
| <code style="white-space:nowrap">{{#invoke:DateTime|format|2=T._Monat JJJJ hh:mm:ss Zone}}</code>
!rowspan="9"| ×
|rowspan="4"| &nbsp;
|-
| <code>dewiki</code>
| <code>{{#timel:H:i, j.&#160;M Y}}</code>
|-
| <code>T._Monat JJJJ</code>
| <code>{{#timel:j.&#160;F Y}}</code>
|-
| <code>T._Mon JJJJ</code>
| <code>{{#timel:j.&#160;M Y}}</code>
|-
| <code>T._Mon_JJJJ</code>
| <code>{{#timel:j.&#160;M&#160;Y}}</code>
! ×
|-
| <code>T._Mon4 JJJJ</code>
| <code>{{#invoke:DateTime|format|2=T._Mon4 JJJJ}}</code>
| &nbsp;
!rowspan="4"| ×
|-
| <code>T._Mon4_JJJJ</code>
| <code>{{#invoke:DateTime|format|2=T._Mon4_JJJJ}}</code>
! ×
|-
| <code>T._Mon4 JJJJ hh:mm:ss</code>
| <code>{{#invoke:DateTime|format|2=T._Mon4 JJJJ hh:mm:ss}}</code>
|rowspan="2"| &nbsp;
|-
| <code>T._Mon4 JJJJ hh:mm:ss Zone</code>
| <code>{{#invoke:DateTime|format|2=T._Mon4 JJJJ hh:mm:ss Zone}}</code>
|-
| <code>T. Mon JJJJ</code>
| <code>{{#timel:j. M Y}}</code>
|-
| <code>TT.MM.JJJJ</code>
| <code>{{#timel:d.m.Y}}</code>
|-
| <code>T.M.JJJJ</code>
| <code>{{#timel:j.n.Y}}</code>
|-
| <code>$JulianDate$</code>
| <code>{{#invoke:DateTime|format|2=$JulianDate$}}</code>
|-
| <code>$JulianDate,$</code>
| <code>{{#invoke:DateTime|format|2=$JulianDate,$}}</code>
<!-- $JulianCal$ -->
|- id="TextKonstant"
| <code>$"$</code>''Text''
| <code>Text</code>
|}

==== Mehrere Darstellungsformate ====
Es ist möglich, denselben Zeitpunkt mehrfach in unterschiedlichen Formaten und somit ggf. anderen Zeitrechnungen, Kalendern, Zeitzonen darzustellen.
* Dazu müssen die Formatangaben durch <code>|||</code> voneinander getrennt werden.
* In der Vorlagenprogrammierung wird das durch <code>&#123;{!}&#125;&#123;{!}&#125;&#123;{!}&#125;</code> erreicht.
* Die Komponenten werden nahtlos aneinandergefügt.
* Mit dem Sonderformat <code>[[#TextKonstant|$"$]]</code> können Textblöcke eingestreut werden, damit Schlüsselwörter als Formate nutzbar sind. Gleichzeitig lässt sich die Darstellung entsprechend gliedern und beschriften.
* Die Verwendung ist etwas komplizierter und zielt auf entsprechende Vorlagenprogrammierungen ab.

=== {{Anker|template.comparison}} lt le eq ne ge gt ===
Diese Funktionen vergleichen den ersten und zweiten Parameter miteinander; als Datum/Zeit in beliebigem Format (oder „jetzt“ wenn nicht angegeben).
* Funktionswert ist <code>1</code>, wenn die Bedingung erfüllt ist, sonst „nichts“.
Die Funktionen sind im Einzelnen:
* <code>lt</code> – kleiner
* <code>le</code> – kleiner oder gleich
* <code>eq</code> – gleich
* <code>ne</code> – ungleich
* <code>ge</code> – größer oder gleich
* <code>gt</code> – größer

=== failsafe ===
Diese Funktion gibt die Versionsbezeichnung des Moduls aus.
* <code><nowiki>{{#invoke:DateTime|failsafe}}</nowiki></code> ergibt <code>{{#invoke:DateTime|failsafe}}</code>
Mit Angabe eines Parameters als Datum im ISO-Format wird verglichen, ob das aktuelle Modul diese Version oder später erfüllt.
* <code><nowiki>{{#invoke:DateTime|failsafe|2001-01-01}}</nowiki></code> ergibt: »<code>{{#invoke:DateTime|failsafe|2001-01-01}}</code>«
* <code><nowiki>{{#invoke:DateTime|failsafe|2099-01-01}}</nowiki></code> ergibt: »<code>{{#invoke:DateTime|failsafe|2099-01-01}}</code>« – leer, falls Mindestversionsbezeichnung nicht erfüllt
Ist dieser Zusatzparameter das Schlüsselwort <code>wikidata</code>, so ist der Wert die auf Wikidata registrierte Versionsbezeichnung (<code>{{#invoke:DateTime|failsafe|wikidata}}</code>) oder lokal, falls dort keine gefunden.
* Ist der Zusatzparameter das Zeichen <code>~</code>, so ist das Ergebnis ''leer'', falls Übereinstimmung der lokalen mit der auf Wikidata registrierten Versionsbezeichnung besteht&nbsp;(<code>{{#invoke:DateTime|failsafe|~}}</code>).

== Beispiele (Testseiten) ==
[[Wikipedia:Lua/Modul/DateTime/Test|Testseiten]] illustrieren praktische Beispiele.
</onlyinclude>
== {{Anker|Lua}} Funktionen für Lua-Module ==

Die Bibliothek kann auch über <code>require()</code> in andere Module eingebunden werden:
<syntaxhighlight lang="lua">
local lucky, DateTime = pcall( require, "Modul:DateTime" )
if type( DateTime ) == "table" then
    DateTime = DateTime.DateTime()
else
    -- Fehlerfall; DateTime enthält Fehlermeldung
    return "<span class=\"error\">" .. DateTime .. "</span>"
end
</syntaxhighlight>
Danach steht das [[#Bibliotheksobjekt|Bibliotheksobjekt]] <code>DateTime</code> zur Verfügung.

=== Bibliotheksobjekt ===
Dieses Objekt sollte immer <code>DateTime</code> genannt werden. Es steht nicht für eine konkrete Zeitangabe.

==== Felder ====
; .serial
: Versionsdatum der Implementierung; zurzeit: <code>"{{#invoke:DateTime|failsafe}}"</code>
; .suite
: Typ des Objekts; immer: <code>"{DateTime}"</code>

==== {{Anker|Konstruktor}} Konstruktorfunktion ====
Das Bibliotheksobjekt kann als Konstruktorfunktion <code>DateTime()</code> aufgerufen werden; deren Ergebnis ist ein [[#Zeitpunktobjekt|Zeitpunktobjekt]]. Bei ungültiger Anforderung wird <code>false</code> zurückgegeben; möglicherweise auch ein ''string'' mit einer feststellbaren Fehlermeldung.

Die Konstruktorfunktion hat drei optionale Parameter:
; assign
: Angabe von Datum oder Uhrzeit
:* <code>nil</code> – ''jetzt''
:* <code>false</code> – leeres Objekt
:* <code>"now"</code> – ''jetzt''
:* ''string'' – Interpretierbares Format; Beispiele siehe [[Wikipedia:Lua/Modul/DateTime/Test|Testseite]].
:* Zeitpunktobjekt
:* ''table'' – [[#Komponenten|Komponenten]]
; alien
: Besondere Sprachbezeichnung (Kürzel gemäß [[ISO 639]]) analog zum Vorlagenparameter <code>[[#format-lang|lang]]</code>.
: <code>nil</code> – <code>de</code>
; add
: Verschiebungsintervall
: <code>nil</code> – keine Verschiebung
: ''string'' – analog zum Vorlagenparameter <code>[[#format-shift|shift]]</code>
: ''number'' – Anzahl von Sekunden, positiv/negativ, muss nicht ganzzahlig sein

''Beispiel:''
<syntaxhighlight lang="lua">
local o = DateTime( "2013-12" )
</syntaxhighlight>
Es wird ein Zeitpunktobjekt <code>o</code> generiert mit den Komponenten <code>year=2013</code> und <code>month=12</code>; sowie in unserem Kontext <code>lang=de</code>.
<!-- Methoden sind in Lua 5.1 nicht möglich, da das metatable nur __index und __call kennt -->

=== Zeitpunktobjekt ===
* Jedes Zeitpunktobjekt repräsentiert einen konkreten Zeitpunkt, der allerdings auch leer sein könnte.
* Jedes Zeitpunktobjekt enthält dieselben Felder und Methoden wie das [[#Bibliotheksobjekt|Bibliotheksobjekt]] und könnte an dessen Stelle verwendet werden.

==== Felder ====
; .serial
: Versionsdatum der Implementierung; zurzeit: <code>"{{#invoke:DateTime|failsafe}}"</code>
; .suite
: Typ des Objekts; immer: <code>"DateTime"</code>

===== {{Anker|Komponenten}} Komponenten des Zeitpunkts =====
Alle Zahlen sind ganzzahlig, wodurch sich Genauigkeiten und erforderliche Ausgabefomate schnell und sicher bestimmen lassen.
{| class="wikitable"
! Komponente         !!  Typ    !! Bemerkung
|-
| <code>lang</code>  || string  || Code der Standardsprache nach [[ISO 639]] (<code>de</code>)
|-
| <code>bc</code>    || boolean || false, nil: n. Chr.
|-
| <code>year</code>  || number  || >0 [[Jahr null|(=0??)]]
|-
| <code>month</code> || number  || 1–12; auch ohne <code>year</code>
|-
| <code>dom</code>   || number  ||
|-
| <code>week</code>  || number  || Nach ISO berechnet
|-
| <code>hour</code>  || number
|-
| <code>min</code>   || number
|-
| <code>sec</code>   || number
|-
| <code>msec</code>  || number  || 0–999; volle Millisekunden
|-
| <code>mysec</code> || number  || 0–999; ohne volle Millisekunden
|-
| <code>dom2</code>
|rowspan="3"| boolean
|rowspan="3"| Einstellige Zahlen wurden zweistellig angegeben, obwohl das Eingabeformat dies nicht erzwungen hatte.
|-
| <code>month2</code>
|-
| <code>hour2</code>
|-
| <code>zone</code>  || string, number, boolean
| Code (CET,CEST,MEZ) oder Anzahl der Minuten<br />false, nil: Lokal, einschließlich Sommerzeit
|-
| <code>leap</code>  || boolean || false, nil: <code>sec<60</code> ([[Schaltsekunde]] unzulässig)
|-
| <code>jul</code>   || boolean || false, nil: Gregorianischer Kalender
|}

===== Wertzuweisung =====
Existiert ein Objekt, dann können auch einzelnen Komponenten Werte zugewiesen werden:
<syntaxhighlight lang="lua">
o.dom = 31
</syntaxhighlight>

Die Zuweisung wird nur ausgeführt, wenn sie gültig ist. Das bedeutet:
* Zahlenwerte usw. müssen im Kontext aller anderen Komponenten gültig sein.
** ''Beispiel:'' Einem Tag im Februar kann nur der Wert <code>29</code> zugewiesen werden, wenn ein angegebenes Jahr auch ein Schaltjahr ist.
* Die Abfolge der Komponenten darf nicht unterbrochen sein; das heißt, es darf kein Lücke entstehen zwischen der ersten und letzten definierten Komponente (etwa Jahr, Monat, Tag, Stunde, Minute, Sekunde).
An dieser Stelle ist keine Fehlermeldung möglich. Ob eine Zuweisung erfolgreich vorgenommen wurde, wäre in Zweifelsfällen anschließend zu überprüfen; im obigen Beispiel:
<syntaxhighlight lang="lua">
if o.dom ~= 31 then
</syntaxhighlight>

==== Konstruktorfunktion ====
Jedes Zeitpunktobjekt kann genauso wie ein [[#Bibliotheksobjekt|Bibliotheksobjekt]] als  [[#Konstruktor|Konstruktorfunktion]] aufgerufen werden (mit gleichen Parametern); deren Ergebnis ist ein neues Zeitpunktobjekt.

==== Methoden ====
Sofern die Aufrufe auch wieder ein Zeitpunktobjekt ergeben, können sie natürlich verkettet werden.

===== {{Anker|:clone()}} :clone() =====
Generiere einen Klon dieses Zeitpunktobjekts.

===== {{Anker|:fair()}} :fair( access, assign ) =====
Formale Gültigkeit eines Zeitpunktobjekts prüfen.
; access
: Einzelnes Datenelement, das geprüft werden soll
: ''string'' oder <code>nil</code>
: <code>nil</code> – ganzes Objekt (Vorgabe)
; access
: Einzelner Wert für ''access'', der geprüft werden soll
: ''string'' oder <code>nil</code>
: Nur sinnvoll, wenn ''access'' angegeben
''Ergebnis: boolean''

===== :figure( assign ) =====
Monat über Monatsnamen zuweisen.
; assign
: ''string'' – Monatsname
''Ergebnis:'' Zeitpunktobjekt

===== :first() =====
Abgekürzten Monatsnamen in der Objektsprache abfragen.
* Der Zeitpunkt muss einen Monat definiert haben.
''Ergebnis: string'' oder <code>nil</code>

===== {{Anker|:flow()}} :flow( another, assert ) =====
Vergleiche das Zeitpunktobjekt mit einem anderen Zeitpunkt.
; another
: anderer Zeitpunkt; ''table'' als Objekt oder geeignete Zeichenkette
; assert
: Optionaler Vergleichsoperator als Bedingung
: Einer von: "lt", "le", "eq", "ne", "ge", "gt", "<", "<=", "==", "~=", "<>", ">=", "=>", ">"
''Ergebnis:''
* ohne (gültiges) <code>assert</code>: <code>-1</code>, <code>0</code>, <code>1</code> für kleiner, gleich, größer
* mit <code>assert</code>: <code>true</code> oder <code>false</code>

===== {{Anker|:format()}} :format( ask, adapt ) =====
Zeitpunktobjekt darstellen.
; ask
: Formatspezifikation
:* wie für [[Hilfe:Vorlagenprogrammierung#Funktion time|<tt>#time</tt>]]
:* gemäß [[#formatspec|besonderer Vereinbarung]]
:* Vorgabe: <code>"c"</code> → ISO-T
; adapt
: Optionen; ''table'' oder <code>nil</code>
:* <code>.lang</code> – Besondere Sprachbezeichnung (Kürzel gemäß [[ISO 639]])
:* <code>.london</code> – Ausgabe in UTC; Standard ist lokal
:* <code>.lonely</code> – Stunde ohne Minute
''Ergebnis:'' Zeichenkette mit der formatierten Angabe; siehe [[#format|format]] für Vorlagen.

''Beispiele:''
<syntaxhighlight lang="lua">
o:format( "timestamp" )
DateTime():format( "dewiki" )
</syntaxhighlight>
Das erste Beispiel ergibt <code>{{REVISIONTIMESTAMP}}</code>, falls das die Angaben im Objekt waren, das zweite: <code>{{#invoke:DateTime|format|now|dewiki}}</code>.

===== :full() =====
Monatsname in der Objektsprache abfragen.
* Der Zeitpunkt muss einen Monat definiert haben.
''Ergebnis: string'' oder <code>nil</code>

===== {{Anker|:future()}} :future( add ) =====
Verschiebung um Zeitspanne.
; add
: Zeitspanne
: analog zum Vorlagenparameter <code>[[#format-shift|shift]]</code>
: Syntax wie beim zweiten Parameter von <code>#time</code>, ausgenommen: <code style="white-space: nowrap">Next Thursday</code>
''Ergebnis:'' Zeitpunktobjekt

''Beispiele:''
<syntaxhighlight lang="lua">
o:future( "tomorrow" )
o:future( "1 week 3 days" )
o:future( "1 year ago" )
o:future( "-3 years 1 day" )
</syntaxhighlight>

===== {{Anker|:tostring()}} :tostring() =====
Zeitpunktobjekt als Zeichenkette darstellen; an ISO angenähert und meist wieder einlesbar.

===== {{Anker|:valueOf()}} :valueOf() =====
Zeitpunktobjekt auf reine ''table'' der [[#Komponenten|Komponenten]] reduzieren.

===== :failsafe( atleast ) =====
[[#failsafe|Siehe oben]].
; atleast
: optionale Zeichenkette, wie dort

==== Vergleichsausdrücke ====
Ein Zeitpunktobjekt kann mit einem darauf folgenden anderen oder einer geeigneten Zeichenkette verglichen werden, indem einer der gängigen Lua-Vergleichsoperatoren dazwischengesetzt wird:
* <code>< <= == ~= >= ></code>
* Der Wert des Ausdrucks ist <code>true</code> oder <code>false</code>.
''Beispiele:''
<syntaxhighlight lang="lua">
local heute  = DateTime()
local stop   = "2021-12-21"
local termin = DateTime( stop )
if termin > heute then
if heute <= stop then
</syntaxhighlight>

==== Verschiebung ====
Der Wert eines Objekts kann geändert werden, indem eine unter [[#:future()|:future()]] angegebene Zeitspanne mittels + „addiert“ wird.

''Beispiel:''
<syntaxhighlight lang="lua">
local fristablauf = o + "1 year 2 days -1 hour"
</syntaxhighlight>
''Ergebnis:'' Zeitpunktobjekt

== Verwendung ==
Allgemeine Bibliothek; nicht eingegrenzt.
* [[Modul:Sort/cellDate]] – Anwendung für Sortierschlüssel

== Abhängigkeiten ==
* [[Modul:DateTime/local]] – sprach/projektspezifische Anpassungen

[[Kategorie:Wikipedia:Lua/Modul/Dokumentation|DateTime]]