Date::Calc
Handbuch-Seite

NAME
VORWORT
ÜBERSICHT
WICHTIGE HINWEISE
BESCHREIBUNG
BEISPIELE
SIEHE AUCH
EINSCHRÄNKUNGEN
VERSION
AUTOR
URHEBERRECHTE
ÜBERSETZUNG
LIZENZ
HAFTUNGSAUSSCHLUSS

NAME

Date::Calc - Datumsberechnungen nach dem Gregorianischen Kalender

VORWORT

Dieses Paket besteht aus einer C-Bibliothek und einem Perl-Modul (das die C-Bibliothek intern nutzt). Damit können, basierend auf dem Gregorianischen Kalender (der heutzutage in allen westlichen Ländern verwendet wird), alle Arten von Datumsberechnungen durchgeführt werden. Alle relevanten Normen und Standards werden dabei berücksichtigt: ISO/R 2015-1971, DIN 1355 und, bis zu einem gewissen Grad, ISO 8601 (wo anwendbar).

(Sie finden einen Teil des "DIN 1355"-Dokuments (auf Deutsch) unter der URL http://sb.fluomedia.org/download/Date-Calc/DIN1355/.)

Das Modul kann natürlich auch Jahreszahlen von 2000 und danach korrekt verarbeiten ("Year 2000"- oder "Y2K"-Compliance) - tatsächlich können alle Jahreszahlen von 1 bis zum größten ganzzahligen, auf Ihrem System noch darstellbaren positiven Wert (also mindestens bis 32767) verarbeitet werden.

Beachten Sie, daß dieses Paket den Gregorianischen Kalender bis ins Jahr 1 n. Chr. EXTRAPOLIERT, obwohl der Gregorianische Kalender erst 1582 von den meisten (nicht allen) europäischen Ländern übernommen wurde, dem Dekret von Papst Gregor I. aus diesem Jahr entsprechend.

Einige (hauptsächlich protestantische) Länder haben den (bis dahin geltenden) Julianischen Kalender weiterverwendet, zum Teil sogar bis zum Beginn des 20. Jahrhunderts.

Beachten Sie schließlich auch, daß dieses Paket nicht dazu gedacht ist, alle nur vorstellbaren Aufgaben automatisch für Sie zu übernehmen. Es ist vielmehr als Werkzeugkasten (in bester UNIX-Tradition) gedacht, die Sie überall hinbringt, wo Sie hin wollen.

Wenn es Ihnen dennoch nicht gelingen sollte, ein bestimmtes Problem zu lösen, lassen Sie es mich wissen! (Die E-Mail-Adresse finden Sie am Ende dieses Dokuments.)

ÜBERSICHT

  use Date::Calc qw(
      Days_in_Year
      Days_in_Month
      Weeks_in_Year
      leap_year
      check_date
      check_business_date
      Day_of_Year
      Date_to_Days
      Day_of_Week
      Week_Number
      Week_of_Year
      Monday_of_Week
      Nth_Weekday_of_Month_Year
      Standard_to_Business
      Business_to_Standard
      Delta_Days
      Delta_DHMS
      Add_Delta_Days
      Add_Delta_DHMS
      Add_Delta_YMD
      System_Clock
      Today
      Now
      Today_and_Now
      Easter_Sunday
      Decode_Month
      Decode_Day_of_Week
      Decode_Language
      Decode_Date_EU
      Decode_Date_US
      Compress
      Uncompress
      check_compressed
      Compressed_to_Text
      Date_to_Text
      Date_to_Text_Long
      Calendar
      Month_to_Text
      Day_of_Week_to_Text
      Day_of_Week_Abbreviation
      Language_to_Text
      Language
      Languages
      Decode_Date_EU2
      Decode_Date_US2
      Parse_Date
  );

  use Date::Calc qw(:all);

  Days_in_Year
      $days = Days_in_Year($year,$month);

  Days_in_Month
      $days = Days_in_Month($year,$month);

  Weeks_in_Year
      $weeks = Weeks_in_Year($year);

  leap_year
      if (leap_year($year))

  check_date
      if (check_date($year,$month,$day))

  check_business_date
      if (check_business_date($year,$week,$dow))

  Day_of_Year
      $doy = Day_of_Year($year,$month,$day);

  Date_to_Days
      $days = Date_to_Days($year,$month,$day);

  Day_of_Week
      $dow = Day_of_Week($year,$month,$day);

  Week_Number
      $week = Week_Number($year,$month,$day);

  Week_of_Year
      ($week,$year) = Week_of_Year($year,$month,$day);

  Monday_of_Week
      ($year,$month,$day) = Monday_of_Week($week,$year);

  Nth_Weekday_of_Month_Year
      if (($year,$month,$day) =
      Nth_Weekday_of_Month_Year($year,$month,$dow,$n))

  Standard_to_Business
      ($year,$week,$dow) =
      Standard_to_Business($year,$month,$day);

  Business_to_Standard
      ($year,$month,$day) =
      Business_to_Standard($year,$week,$dow);

  Delta_Days
      $Dd = Delta_Days($year1,$month1,$day1,
                       $year2,$month2,$day2);

  Delta_DHMS
      ($Dd,$Dh,$Dm,$Ds) =
      Delta_DHMS($year1,$month1,$day1, $hour1,$min1,$sec1,
                 $year2,$month2,$day2, $hour2,$min2,$sec2);

  Add_Delta_Days
      ($year,$month,$day) =
      Add_Delta_Days($year,$month,$day, $Dd);

  Add_Delta_DHMS
      ($year,$month,$day, $hour,$min,$sec) =
      Add_Delta_DHMS($year,$month,$day, $hour,$min,$sec,
                     $Dd,$Dh,$Dm,$Ds);

  Add_Delta_YMD
      ($year,$month,$day) =
      Add_Delta_YMD($year,$month,$day,
                    $Dy,$Dm,$Dd);

  System_Clock
      ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) =
      System_Clock();

  Today
      ($year,$month,$day) = Today();

  Now
      ($hour,$min,$sec) = Now();

  Today_and_Now
      ($year,$month,$day, $hour,$min,$sec) = Today_and_Now();

  Easter_Sunday
      ($year,$month,$day) = Easter_Sunday($year);

  Decode_Month
      if ($month = Decode_Month($string))

  Decode_Day_of_Week
      if ($dow = Decode_Day_of_Week($string))

  Decode_Language
      if ($lang = Decode_Language($string))

  Decode_Date_EU
      if (($year,$month,$day) = Decode_Date_EU($string))

  Decode_Date_US
      if (($year,$month,$day) = Decode_Date_US($string))

  Compress
      $date = Compress($year,$month,$day);

  Uncompress
      if (($century,$year,$month,$day) = Uncompress($date))

  check_compressed
      if (check_compressed($date))

  Compressed_to_Text
      $string = Compressed_to_Text($date);

  Date_to_Text
      $string = Date_to_Text($year,$month,$day);

  Date_to_Text_Long
      $string = Date_to_Text_Long($year,$month,$day);

  Calendar
      $string = Calendar($year,$month);

  Month_to_Text
      $string = Month_to_Text($month);

  Day_of_Week_to_Text
      $string = Day_of_Week_to_Text($dow);

  Day_of_Week_Abbreviation
      $string = Day_of_Week_Abbreviation($dow);

  Language_to_Text
      $string = Language_to_Text($lang);

  Language
      $lang = Language();
      Language($lang);
      $oldlang = Language($newlang);

  Languages
      $max_lang = Languages();

  Decode_Date_EU2
      if (($year,$month,$day) = Decode_Date_EU2($string))

  Decode_Date_US2
      if (($year,$month,$day) = Decode_Date_US2($string))

  Parse_Date
      if (($year,$month,$day) = Parse_Date($string))

  Version
      $string = Date::Calc::Version();

WICHTIGE HINWEISE

"Year 2000"- ("Y2K"-) Compliance
Bei diesem Modul wird die oberste Grenze für eine Jahreszahl nur durch den größten ganzzahligen positiven Wert festgelegt, der auf Ihrem System in einer C-Variablen vom Typ "int" abgelegt werden kann. Dem ANSI C-Standard entsprechend beträgt dieser Wert mindestens 32767. (Ausnahmen von dieser Regel siehe weiter unten.)
Um die Berechnungen zu vereinfachen, EXTRAPOLIERT dieses Modul den Gregorianischen Kalender bis ins Jahr 1 n. Chr. zurück, d.h. bis VOR das Jahr 1582, in dem dieser Kalender von Papst Gregor I. eingeführt wurde!
Daher müssen Sie IMMER "1998" ANGEBEN, WENN SIE "1998" MEINEN, und NICHT EINFACH NUR "98", weil dies eine auf dem Jahr "98" n. Chr. und NICHT auf "1998" basierende Rechnung durchführen würde!
Die einzigen Ausnahmen von dieser Regel sind die Funktionen, deren Namen das Wort "compress" enthalten. Diese Funktionen behandeln nur die Jahre zwischen 1970 und 2069 und erlauben auch die Abkürzungen "00" bis "99". Auch Funktionen, die den Text "decode_date" in ihren Namen enthalten, bilden eine Ausnahme: Sie fügen dem Jahr den Wert "1900" hinzu, wenn der angegebene Wert unter 100 liegt.
Gültige Wertebereiche für Nummern
ALLE Nummern in diesem Modul beginnen mit der Zählung bei "1", NICHT bei "0"!
Das bedeutet, daß der Tag des Monats, der Wochentag, der Tag des Jahres, der Monat, die Woche des Jahres, die erste gültige Jahreszahl und die Wahl der Sprache ALLE bei eins beginnen und NICHT bei null!
Die einzige Ausnahme ist die Funktion "Week_Number()": Sie kann tatsächlich "0" zurückgeben, wenn das angegebene Datum in der LETZTEN Woche des VORANGEGANGENEN Jahres liegt.
Konventionen für Funktionsnamen
Vollständig kleingeschriebene Funktionsnamen deuten Boolesche Rückgabewerte an.
Boolesche Werte
Die Booleschen Werte dieses Moduls sind immer numerisch Null ("0") für "falsch" und numerisch Eins ("1") für "wahr".
Ausnahmebehandlung
Die Funktionen dieses Moduls brechen üblicherweise mittels "die" (und einer entsprechenden Fehlermeldung) ab, wenn die Eingabeparameter, Zwischenergebnisse oder Ausgabewerte außerhalb ihres gültigen Wertebereichs liegen.
Die folgenden Funktionen handhaben Fehler auf andere Art und Weise:
```
  -  check_date()
  -  check_business_date()
  -  check_compressed()
```
(Diese liefern "falsch" zurück, wenn die Eingabe kein gültiges Datum darstellt.)
```
  -  Nth_Weekday_of_Month_Year()
```
(Diese liefert eine leere Liste zurück, falls der gesuchte fünfte Wochentag nicht existiert.)
```
  -  Decode_Month()
  -  Decode_Day_of_Week()
  -  Decode_Language()
  -  Compress()
```
(Diese liefern "0" bei einem Fehler oder einer ungültigen Eingabe zurück.)
```
  -  Decode_Date_EU()
  -  Decode_Date_US()
  -  Decode_Date_EU2()
  -  Decode_Date_US2()
  -  Parse_Date()
  -  Uncompress()
```
(Diese liefern eine leere Liste bei einem Fehler oder einer ungültigen Eingabe zurück.)
Von den Funktionen dieses Moduls verursachte Ausnahmen können abgefangen und selbst behandelt werden, indem der Funktionsaufruf innerhalb geschweifter Klammern an "eval" übergeben und die Spezialvariable "$@" abgefragt wird (Details hierzu finden Sie in perlfunc(1)).

BESCHREIBUNG

use Date::Calc qw( Days_in_Year Days_in_Month ... );
use Date::Calc qw(:all);
Sie können die Funktionen, die Sie zu importieren wünschen, explizit angeben, indem Sie sie in den Klammern des "qw()"-Operators einzeln aufführen. Mit dem Tag ":all" können Sie ALLE vorhandenen Funktionen importieren.
$days = Days_in_Year($year,$month);
Diese Funktion gibt die Summe der Tage zurück, die die Monate des jeweiligen Jahres "$year" zusammen besitzen. Dabei beginnt die Zählung beim Januar und geht bis einschließlich "$month".
"Days_in_Year(1998,1)" liefert "31", "Days_in_Year(1998,2)" liefert "59", "Days_in_Year(1998,3)" liefert "90" und so weiter.
Beachten Sie, daß "Days_in_Year($year,12)" die Anzahl der Tage des jeweiligen Jahres "$year", also entweder "365" oder "366", zurückliefert.
$days = Days_in_Month($year,$month);
Diese Funktion gibt die Anzahl der Tage des Monats "$month" im Jahr "$year" zurück.
Das Jahr muß immer angegeben werden. Eigentlich wird es aber nur für den Monat Februar benötigt, um bestimmen zu können, ob es sich um ein Schaltjahr handelt oder nicht.
"Days_in_Month(1998,1)" liefert "31", "Days_in_Month(1998,2)" liefert "28", "Days_in_Month(2000,2)" liefert "29", "Days_in_Month(1998,3)" liefert "31" und so weiter.
$weeks = Weeks_in_Year($year);
Diese Funktion gibt die Anzahl der Wochen des Jahres "$year" zurück, also entweder "52" oder "53".
if (leap_year($year))
Diese Funktion gibt "wahr" ("1") zurück, wenn das angegebene Jahr "$year" ein Schaltjahr ist. Anderenfalls wird "falsch" ("0") zurückgegeben.
if (check_date($year,$month,$day))
Diese Funktion gibt "wahr" ("1") zurück, wenn die drei übergebenen Werte "$year", "$month" und "$day" ein gültiges Datum darstellen. Anderenfalls wird "falsch" ("0") zurückgegeben.
if (check_business_date($year,$week,$dow))
Diese Funktion gibt "wahr" ("1") zurück, wenn die drei übergebenen Werte "$year", "$week" und der Wochentag "$dow" ein gültiges Datum darstellen. Anderenfalls wird "falsch" ("0") zurückgegeben.
$doy = Day_of_Year($year,$month,$day);
Diese Funktion gibt die (relative) Zahl des Tages des angegebenen Datums im jeweiligen Jahr zurück.
"Day_of_Year($year,1,1)" liefert "1", "Day_of_Year($year,2,1)" liefert "32", und "Day_of_Year($year,12,31)" liefert entweder "365" oder "366".
$days = Date_to_Days($year,$month,$day);
Diese Funktion gibt die (absolute) Zahl des Tages des angegebenen Datums zurück. Die Zählung beginnt mit dem 1. Januar des Jahres 1 n. Chr.
"Date_to_Days(1,1,1)" liefert "1", "Date_to_Days(1,12,31)" liefert "365", "Date_to_Days(2,1,1)" liefert "366", "Date_to_Days(1998,5,1)" liefert "729510" und so weiter.
$dow = Day_of_Week($year,$month,$day);
Diese Funktion gibt die Zahl des Wochentages des angegebenen Datums zurück.
Die Funktion liefert "1" für Montag, "2" für Dienstag usw. bis zu "7" für den Sonntag zurück.
Beachten Sie, daß beim hebräischen Kalender (auf dem der christliche und somit der Gregorianische Kalender basiert) die Woche mit dem Sonntag beginnt und mit dem Sabbat oder Samstag endet (an dem der Herr ruhte, wie in der Bibel steht).
Im Mittelalter haben Päpste dann den Sonntag zum offiziellen kirchlichen Ruhetag erklärt, um den christlichen vom hebräischen Glauben abzugrenzen.
Heutzutage werden üblicherweise SOWOHL der Sonntag ALS AUCH der Samstag als Ruhetage betrachtet (und auch als solche genutzt) und allgemein als "Wochenende" bezeichnet.
Dieser Praxis entsprechend definieren die aktuellen Normen und Standards (wie z.B. ISO/R 2015-1971, DIN 1355 und ISO 8601) den Montag als den ersten Wochentag.
$week = Week_Number($year,$month,$day);
Die Funktion gibt die Nummer der Woche zurück, in der das angegebene Datum liegt.
Liegt das Datum in der LETZTEN Woche des VORANGEGANGENEN Jahres, wird "0" zurückgegeben.
Liegt das Datum in der ERSTEN Woche des NÄCHSTEN Jahres, wird "Weeks_in_Year($year) + 1" zurückgegeben.
($week,$year) = Week_of_Year($year,$month,$day);
Diese Funktion gibt die Nummer der Woche und das Jahr zurück, in der/dem ein gegebenes Datum liegt.
Liegt das angegebene Datum in der LETZTEN Woche des VORANGEGANGENEN Jahres, wird "(Weeks_in_Year($year-1), $year-1)" zurückgegeben.
Liegt das angegebene Datum hingegen in der ERSTEN Woche des NÄCHSTEN Jahres, wird "(1, $year+1)" zurückgegeben.
In allen anderen Fällen wird "(Week_Number($year,$month,$day), $year)" zurückgegeben.
($year,$month,$day) = Monday_of_Week($week,$year);
Diese Funktion gibt das Datum des ersten Wochentages, d.h. des Montags, der angegebenen Woche zurück.
"$year" muß größer oder gleich "1" sein, und "$week" muß im Bereich "1" bis "Weeks_in_Year($year)" liegen.
Sie können übrigens auch "($year,$month,$day) = Monday_of_Week(Week_of_Year($year,$month,$day));" verwenden, um das Datum des Montags derjenigen Woche zu ermitteln, in der das angegebene Datum liegt.
if (($year,$month,$day) = Nth_Weekday_of_Month_Year($year,$month,$dow,$n))
Diese Funktion berechnet das Datum des "$n"ten Wochentages "$dow" im Monat "$month" im Jahr "$year"; also beispielsweise den dritten Donnerstag im angegebenen Monat und Jahr.
Das kann zum Beispiel verwendet werden, um Benachrichtigungen an die Mitglieder einer Gruppe zu verschicken, die sich regelmäßig an jedem dritten Donnerstag eines Monats treffen.
(Im Abschnitt "BEISPIELE" am Ende dieses Dokuments finden Sie ein Codefragment welches genau dies tut.)
"$year" muß größer oder gleich "1" sein, "$month" muß im Bereich von "1" bis "12" liegen, "$dow" muß im Bereich von "1" bis "7" liegen, und "$n" muß im Bereich von "1" bis "5" liegen. Anderenfalls kommt es zu einem fatalen Fehler (mit einer entsprechenden Fehlermeldung).
Die Funktion gibt eine leere Liste zurück, falls der gesuchte fünfte Wochentag im angegebenen Monat und Jahr nicht existiert.
($year,$week,$dow) = Standard_to_Business($year,$month,$day);
Diese Funktion wandelt ein gegebenes Datum in Standardnotation (Jahr, Monat, Tag des Monats) in Geschäftsnotation (Jahr, Woche, Wochentag) um.
($year,$month,$day) = Business_to_Standard($year,$week,$dow);
Diese Funktion wandelt ein gegebenes Datum in Geschäftsnotation (Jahr, Woche, Wochentag) in Standardnotation (Jahr, Monat, Tag des Monats) um.
$Dd = Delta_Days($year1,$month1,$day1, $year2,$month2,$day2);
Diese Funktion berechnet die Differenz in Tagen zwischen den beiden angegebenen Daten.
Das Ergebnis ist positiv, wenn die beiden Datumsangaben in chronologischer Reihenfolge vorliegen, d.h., wenn Datum 1 chronologisch VOR Datum 2 liegt. Ist die Reihenfolge der beiden Datumsangaben vertauscht, wird ein negativer Wert zurückgegeben.
Sind beide Daten identisch, wird null zurückgegeben.
($Dd,$Dh,$Dm,$Ds) = Delta_DHMS($year1,$month1,$day1, $hour1,$min1,$sec1, $year2,$month2,$day2, $hour2,$min2,$sec2);
Diese Funktion rechnet die Differenz zwischen den beiden angegebenen Daten in Tagen, Stunden, Minuten und Sekunden aus.
Alle vier zurückgegebenen Werte sind positiv, wenn die beiden Datumsangaben in chronologischer Reihenfolge angegeben wurden, d.h., wenn Datum 1 chronologisch VOR Datum 2 liegt. Das Ergebnis ist (für alle vier Rückgabewerte) negativ, wenn die Reihenfolge der beiden Daten vertauscht ist.
Auf diese Weise sind die beiden Funktionen "Delta_DHMS()" und "Add_Delta_DHMS()" (die Beschreibung finden Sie weiter unten) zueinander komplementär:
```
  Add_Delta_DHMS(@date1,@time1, Delta_DHMS(@date1,@time1, @date2,@time2))
```
ergibt wieder "(@date2,@time2)", während
```
  Add_Delta_DHMS(@date2,@time2,
      map(-$_, Delta_DHMS(@date1,@time1, @date2,@time2)))
```
"(@date1,@time1)" ergibt und
```
  Delta_DHMS(@date1,@time1, Add_Delta_DHMS(@date1,@time1, @delta))
```
wieder "@delta" liefert.
Das Ergebnis ist null (für alle vier Rückgabewerte), wenn die beiden Datumsangaben und Zeiten identisch sind.
($year,$month,$day) = Add_Delta_Days($year,$month,$day, $Dd);
Für diese Funktion gibt es zwei wesentliche Anwendungen:
Zum einen kann sie verwendet werden, um ein neues Datum zu berechnen, wenn ein Anfangsdatum und ein Offset (positiv oder negativ) in Tagen bekannt ist. Damit können Fragen beantwortet werden wie z.B. "Auf welches Datum fällt heute plus 90 Tage?".
(Um mit Wochen-Offsets arbeiten zu können, multiplizieren Sie den Wochen-Offset einfach mit "7" und verwenden diesen Wert als den Tages-Offset.)
Zweitens können Sie damit die kanonische Darstellung eines Datums, d.h. die Anzahl der Tage (gezählt ab dem 1. Januar im Jahre 1 n. Chr.), wieder in ein aus Jahr, Monat und Tag bestehendes Datum zurückverwandeln.
Weil jedoch die Zählung bei "1" beginnt, müssen Sie dazu eine "1" vom kanonischen Datum abziehen, um wieder auf das ursprüngliche Datum zu kommen:
```
  $canonical = Date_to_Days($year,$month,$day);

  ($year,$month,$day) = Add_Delta_Days(1,1,1, $canonical - 1);
```
Diese Funktion bildet das Gegenstück zur Funktion "Delta_Days()":
```
  Add_Delta_Days(@date1, Delta_Days(@date1, @date2))
```
ergibt wieder "@date2", während
```
  Add_Delta_Days(@date2, -Delta_Days(@date1, @date2))
```
"@date1" liefert und
```
  Delta_Days(@date1, Add_Delta_Days(@date1, $delta))
```
wieder zu "$delta" führt.
($year,$month,$day, $hour,$min,$sec) = Add_Delta_DHMS($year,$month,$day, $hour,$min,$sec, $Dd,$Dh,$Dm,$Ds);
Mit dieser Funktion können Sie zu einem Datum und einer Uhrzeit Tages-, Stunden-, Minuten- und Sekunden-Offsets hinzuaddieren. Auf diese Weise können Sie Fragen beantworten wie "Welches Datum und welche Uhrzeit haben wir heute in 7 Tagen, wenn wir 5 Stunden abziehen und dann 30 Minuten hinzuaddieren?".
```
  ($y,$m,$d,$H,$M,$S) = Add_Delta_DHMS(Today_and_Now(), +7,-5,+30,0);
```
($year,$month,$day) = Add_Delta_YMD($year,$month,$day, $Dy,$Dm,$Dd);
Mit dieser Funktion können Sie Jahr-, Monat- und Tag-Offsets zu einem Datum hinzuaddieren.
(Um mit Wochen-Offsets arbeiten zu können, multiplizieren Sie den Wochen-Offset einfach mit "7" und addieren diese Zahl zu Ihrem Tag-Offset.)
Beachten Sie, daß die drei Offsets für Jahr, Monat und Tag unabhängig voneinander addiert werden (deshalb können diese Offsets auch unterschiedliche Vorzeichen haben), und zwar in umgekehrter Reihenfolge.
Mit anderen Worten: Es wird zuerst der Tages-Offset aufaddiert (wobei intern die Funktion "Add_Delta_Days()" benutzt wird), danach der Monats- und schließlich der Jahres-Offset.
Fällt das resultierende Datum auf einen Tag, der hinter dem Ende des berechneten Monats liegt, beispielsweise der 31. April oder der 29. Februar (wenn kein Schaltjahr vorliegt), dann wird der Tag durch den letzten gültigen Tag dieses Monats in diesem Jahr ersetzt (z.B. der 30. April oder der 28. Februar).
BEACHTEN SIE, daß sich dieses Verhalten von dem früherer Versionen dieses Moduls unterscheidet!
Früher wurde nur der 29. Februar bei Nicht-Schaltjahren geprüft und, im Gegensatz zur aktuellen Version, durch den 1. März ersetzt. Weitere möglicherweise ungültige Werte wurden nicht überprüft (und fälschlicherweise zurückgegeben), was einen schweren Fehler in den früheren Versionen darstellt.
BEACHTEN SIE auch, daß aufgrund dieser Ersetzung, aber mehr noch aufgrund der Tatsache, daß Jahres- und Tages-Offsets nicht mit einer festen Anzahl von Tagen gleichzusetzen sind, die von dieser Funktion durchgeführte Transformation NICHT UMKEHRBAR ist!
Dies steht im Gegensatz zu den Funktionen "Add_Delta_Days()" und "Add_Delta_DHMS()", die über je eine Umkehrfunktion (nämlich "Delta_Days()" und "Delta_DHMS()") verfügen, während es für diese Funktion keine Umkehrfunktion gibt.
Beachten Sie, daß aus demselben Grund selbst
```
  @date = Add_Delta_YMD(
          Add_Delta_YMD(@date, $Dy,$Dm,$Dd), -$Dy,-$Dm,-$Dd);
```
im allgemeinen NICHT das ursprüngliche Datum "@date" zurückliefert!
(in einigen Fällen kann dies jedoch auch funktionieren.)
Beachten Sie, daß es sich hierbei NICHT um einen Programmfehler handelt, sondern UNVERMEIDLICH ist aufgrund der unterschiedlichen Länge von Jahren und Monaten!
($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) = System_Clock();
Wenn Ihr Betriebssystem die Systemaufrufe "time()" und "localtime()" unterstützt, liefert diese Funktion die von Ihrer Systemuhr bereitgestellten Informationen zurück. Hierzu gehören das aktuelle Datum und die aktuelle Uhrzeit, der Tag des Jahres, der Wochentag sowie ein Flag, welches das Vorliegen der Sommerzeit anzeigt.
Die Bereiche der zurückgelieferten Werte (und deren Bedeutung) sind wie folgt:
```
                $year   :   das Jahr, sollte mindestens den Bereich 1900..2038 abdecken
                $month  :   Monat,   1..12
                $day    :   Tag,     1..31
                $hour   :   Stunde,  0..23
                $min    :   Minute,  0..59
                $sec    :   Sekunde, 0..59 (bei manchen Systemen 0..61)
                $doy    :   Tag des Jahres, 1..366
                $dow    :   Wochentag, 1..7
                $dst    :   Sommerzeit ("daylight savings time") -1..1
```
Der Wochentag ("$dow") hat den Wert "1" für Montag, "2" für Dienstag usw. bis "7" für Sonntag.
Das Sommerzeit-Flag ("$dst") hat den Wert "-1", wenn diese Information auf Ihrem System nicht verfügbar ist, "0" wenn gerade keine Sommerzeit ist (sondern normale Zeit), und "1", wenn gerade Sommerzeit vorliegt.
Wenn Ihr Betriebssystem die notwendigen Systemaufrufe nicht unterstützt, führt der Aufruf dieser Funktion zu einem Fehler ("not available on this system").
Wenn Sie diese Ausnahme abfangen und selbst behandeln wollen, können Sie dies mit Hilfe von "eval" wie folgt tun:
```
  eval { ($year,$month,$day, $hour,$min,$sec, $doy,$dow,$dst) =
    System_Clock(); };

  if ($@)
  {
      # Fehler "fehlende Systemuhr" behandeln.
      # (Beispielsweise vom Benutzer eine manuelle Eingabe des Datums verlangen.)
  }
```
Beachten Sie, daß hier geschweifte Klammern ("{" und "}") verwendet werden, um die zu "eval"uierende Anweisung zu umschließen (auf diese Weise werden in Perl Ausnahmen abgefangen). Es werden also keine Anführungszeichen benutzt (was in Perl zur Auswertung von Perl-Ausdrücken zur Laufzeit dient).
($year,$month,$day) = Today();
Diese Funktion gibt eine Teilmenge (nämlich das aktuelle Jahr, den Monat und den Tag) der durch die Funktion "System_Clock()" (siehe oben) gelieferten Werte zurück.
Auch hier tritt ein fataler Fehler auf, wenn die entsprechenden Systemaufrufe von Ihrem Betriebssystem nicht unterstützt werden.
($hour,$min,$sec) = Now();
Diese Funktion gibt eine Teilmenge (nämlich die aktuelle Zeit in Stunden, Minuten und Sekunden) der durch die Funktion "System_Clock()" (siehe oben) gelieferten Werte zurück.
Auch hier tritt ein fataler Fehler auf, wenn die entsprechenden Systemaufrufe von Ihrem Betriebssystem nicht unterstützt werden.
($year,$month,$day, $hour,$min,$sec) = Today_and_Now();
Diese Funktion gibt eine Teilmenge (nämlich das aktuelle Datum in Form von Jahr, Tag und Monat sowie die aktuelle Zeit in Form von Stunden, Minuten und Sekunden) der durch die Funktion "System_Clock()" (siehe oben) gelieferten Werte zurück.
Es tritt ein fataler Fehler auf, wenn die entsprechenden Systemaufrufe von Ihrem Betriebssystem nicht unterstützt werden.

($year,$month,$day) = Easter_Sunday($year);

Diese Funktion berechnet nach der als "Gauss'sche Regel" bekannten Methode das Datum des Ostersonntags für die Jahre 1583 bis 2299 (alle anderen Jahreszahlen führen zu einem fatalen Fehler vom Typ "year out of range").

Hier einige christliche Feiertage, die vom Datum des Ostersonntags abhängen:

  Carnival Monday / Rosenmontag / Veille du Mardi Gras   =  -48 Tage
  Mardi Gras / Karnevalsdienstag / Mardi Gras            =  -47 Tage
  Ash Wednesday / Aschermittwoch / Mercredi des Cendres  =  -46 Tage
  Palm Sunday / Palmsonntag / Dimanche des Rameaux       =   -7 Tage
  Easter Friday / Karfreitag / Vendredi Saint            =   -2 Tage
  Easter Saturday / Ostersamstag / Samedi de Paques      =   -1 Tage
  Easter Monday / Ostermontag / Lundi de Paques          =   +1 Tage
  Ascension of Christ / Christi Himmelfahrt / Ascension  =  +39 Tage
  Whitsunday / Pfingstsonntag / Dimanche de Pentecote    =  +49 Tage
  Whitmonday / Pfingstmontag / Lundi de Pentecote        =  +50 Tage
  Feast of Corpus Christi / Fronleichnam / Fete-Dieu     =  +60 Tage

Verwenden Sie die obigen Offsets, um das Datum des entsprechenden Feiertages zu berechnen:

  ($year,$month,$day) = Add_Delta_Days(Easter_Sunday($year), $offset));

if ($month = Decode_Month($string))
Diese Funktion verlangt als Argument einen String, der den Namen eines Monats IN DER GERADE GEWÄHLTEN SPRACHE (Details zu der von diesem Paket unterstützten Mehrsprachigkeit finden Sie weiter unten) oder eine eindeutige Abkürzung eines Monatsnamens (d.h. die ersten paar Buchstaben) angibt. Bei Erfolg wird die entsprechende Zahl (1..12) zurückgegeben, anderenfalls "0" (auf diese Weise kann der Rückgabewert auch als Bedingungsausdruck in einer "if"-Anweisung verwendet werden).
Beachten Sie, daß der übergebene String keinerlei Zeichen enthalten darf, die nicht zum Monatsnamen gehören. Das gilt auch (und besonders) für führende und nachfolgende Leerzeichen.
Beachten Sie auch, daß die Groß-/Kleinschreibung bei dieser Mustererkennung ignoriert wird (was aber wiederum von den "locale"-Einstellungen Ihres Systems abhängen kann!).
Mit "English" als der gerade gewählten Sprache (was der Voreinstellung entspricht) liefern die folgenden Beispiele immer den Wert "9" zurück:
```
  $month = Decode_Month("s");
  $month = Decode_Month("Sep");
  $month = Decode_Month("septemb");
  $month = Decode_Month("September");
```
if ($dow = Decode_Day_of_Week($string))
Diese Funktion verlangt als Argument einen String, der den Namen eines Wochentages IN DER GERADE GEWÄHLTEN SPRACHE (Details zu der von diesem Paket unterstützten Mehrsprachigkeit finden Sie weiter unten) oder eine eindeutige Abkürzung eines Wochentages (d.h. die ersten paar Buchstaben) angibt. Bei Erfolg wird die entsprechende Zahl (1..7) zurückgegeben, anderenfalls "0" (auf diese Weise kann der Rückgabewert auch als Bedingungsausdruck in einer "if"-Anweisung verwendet werden).
Beachten Sie, daß der übergebene String keinerlei Zeichen enthalten darf, die nicht zum Wochentag gehören. Das gilt auch (und besonders) für führende und nachfolgende Leerzeichen.
Beachten Sie auch, daß die Groß-/Kleinschreibung bei dieser Mustererkennung ignoriert wird (was aber wiederum von den "locale"-Einstellungen Ihres Systems abhängen kann!).
Mit "English" als der gerade gewählten Sprache (was der Voreinstellung entspricht) liefern die folgenden Beispiele immer den Wert "3" zurück:
```
  $dow = Decode_Day_of_Week("w");
  $dow = Decode_Day_of_Week("Wed");
  $dow = Decode_Day_of_Week("wednes");
  $dow = Decode_Day_of_Week("Wednesday");
```
if ($lang = Decode_Language($string))
Diese Funktion verlangt als Argument einen String, der den Namen einer der von diesem Paket unterstützten Sprachen (UND ZWAR IN DIESER SPRACHE SELBST) oder eine eindeutige Abkürzung der Sprache (d.h. die ersten paar Buchstaben) angibt. Bei Erfolg wird die entsprechende interne Zahl (1..6 in der Originaldistribution) zurückgegeben, anderenfalls "0" (auf diese Weise kann der Rückgabewert auch als Bedingungsausdruck in einer "if"-Anweisung verwendet werden).
Beachten Sie, daß der übergebene String keinerlei Zeichen enthalten darf, die nicht zum Namen der Sprache gehören. Das gilt auch (und besonders) für führende und nachfolgende Leerzeichen.
Beachten Sie auch, daß die Groß-/Kleinschreibung bei dieser Mustererkennung ignoriert wird (was aber wiederum von den "locale"-Einstellungen Ihres Systems abhängen kann!).
Die Originaldistribution unterstützt die folgenden sechs Sprachen:
```
          English     (Englisch)       ==>   1    (Voreinstellung)
          Français    (Französisch)    ==>   2
          Deutsch                      ==>   3
          Español     (Spanisch)       ==>   4
          Português   (Portugiesisch)  ==>   5
          Nederlands  (Niederländisch) ==>   6
```
Im Abschnitt "How to install additional languages" in der Datei "INSTALL.txt" in dieser Distribution finden Sie Erläuterungen dazu, wie man weitere Sprachen in dieses Paket einbinden kann.
Mit der Originaldistribution (ohne zusätzlich installierte Sprachen) liefern die folgenden Beispiele den Wert "3" zurück:
```
  $lang = Decode_Language("d");
  $lang = Decode_Language("de");
  $lang = Decode_Language("Deutsch");
```
Beachten Sie, daß Sie möglicherweise nicht in der Lage sind, die in einigen Sprachnamen enthaltenen internationalen Zeichen direkt über die Tastatur Ihres Systems einzugeben.
Das sollte allerdings kein Problem sein: Geben Sie einfach eine Abkürzung des Sprachnamens ein, die aus den ersten paar Buchstaben des Namens bis zum ersten internationalen Zeichen besteht (jedoch ohne dieses).
if (($year,$month,$day) = Decode_Date_EU($string))
Diese Funktion untersucht den übergebenen String und versucht, ein eventuell eingebettetes Datum herauszufiltern.
Die Funktion gibt eine leere Liste zurück, wenn aus dem String kein gültiges Datum herausgefiltert werden konnte. Anderenfalls wird das gefundene Datum zurückgegeben.
Die Funktion akzeptiert nahezu jedes Format, solange das Datum in der europäischen Reihenfolge "Tag-Monat-Jahr" angegeben ist (daher auch der Name dieser Funktion).
Dabei können null oder mehr NICHT-NUMERISCHE Zeichen VOR dem Tag und HINTER dem Jahr stehen.
Außerdem können null oder mehr NICHT-ALPHANUMERISCHE Zeichen ZWISCHEN den drei Elementen (d.h. zwischen Tag und Monat und zwischen Monat und Jahr) stehen.
Der Monat kann wahlweise entweder numerisch (d.h. als Zahl zwischen "1" und "12") oder alphanumerisch, also als Monatsname IN DER GERADE GEWÄHLTEN SPRACHE bzw. in Form einer eindeutigen Abkürzung angegeben werden.
(Weitere Details zur Mehrsprachigkeit dieses Pakets finden Sie weiter unten!)
Besteht das Jahr aus nur ein oder zwei Ziffern (d.h., ist der Wert für das Jahr kleiner als 100), wird "1900" hinzuaddiert.
Liegen Tag, Monat und Jahr in rein numerischer Form, aber OHNE irgendwelche Trennzeichen vor, wird dieser Ziffern-String wie folgt auf Tag, Monat und Jahr abgebildet:
```
                Länge:        Abbildung:
                  3              tmj
                  4              tmjj
                  5              tmmjj
                  6              ttmmjj
                  7              tmmjjjj
                  8              ttmmjjjj
```
(Dabei steht "t" für "Tag", "m" für "Monat" und "j" für "Jahr".)
Alle anderen nur aus Ziffern bestehenden Strings (ohne irgendwelche dazwischenliegenden Trennzeichen) werden abgelehnt, d.h. nicht erkannt.
Beispiele:
```
  "3.1.64"
  "3 1 64"
  "03.01.64"
  "03/01/64"
  "3. Jan 1964"
  "Birthday: 3. Jan '64 in Backnang/Germany"
  "03-Jan-64"
  "3.Jan1964"
  "3Jan64"
  "030164"
  "3ja64"
  "3164"
```
Experimentieren Sie! (Verwenden Sie hierzu auch die entsprechenden Beispielanwendungen im Unterverzeichnis "examples" der Distribution.)
if (($year,$month,$day) = Decode_Date_US($string))
Diese Funktion untersucht den übergebenen String und versucht, ein eventuell eingebettetes Datum herauszufiltern.
Die Funktion gibt eine leere Liste zurück, wenn aus dem String kein gültiges Datum herausgefiltert werden konnte. Anderenfalls wird das gefundene Datum zurückgegeben.
Die Funktion akzeptiert nahezu jedes Format, solange das Datum in der amerikanischen Reihenfolge "Monat-Tag-Jahr" angegeben ist (daher auch der Name dieser Funktion).
Dabei können null oder mehr NICHT-ALPHANUMERISCHE Zeichen VOR und HINTER dem Monat stehen (d.h. vor dem Monat stehen und/oder ihn vom darauffolgenden Tag trennen).
Außerdem können null oder mehr NICHT-NUMERISCHE Zeichen ZWISCHEN Tag und Jahr sowie HINTER dem Jahr stehen.
Der Monat kann wahlweise entweder numerisch (d.h. als Zahl zwischen "1" und "12") oder alphanumerisch, also als Monatsname IN DER GERADE GEWÄHLTEN SPRACHE bzw. in Form einer eindeutigen Abkürzung angegeben werden.
(Weitere Details zur Mehrsprachigkeit dieses Pakets finden Sie weiter unten!)
Besteht das Jahr aus nur ein oder zwei Ziffern (d.h., ist der Wert für das Jahr kleiner als 100), wird "1900" hinzuaddiert.
Liegen Monat, Tag und Jahr in rein numerischer Form, aber OHNE irgendwelche Trennzeichen vor, wird dieser Ziffern-String wie folgt auf Monat, Tag und Jahr abgebildet:
```
                Länge:        Abbildung:
                  3              mtj
                  4              mtjj
                  5              mttjj
                  6              mmttjj
                  7              mttjjjj
                  8              mmttjjjj
```
(Dabei steht "m" für "Monat", "t" für "Tag" und "j" für "Jahr".)
Alle anderen nur aus Ziffern bestehenden Strings (ohne irgendwelche dazwischenliegenden Trennzeichen) werden abgelehnt, d.h. nicht erkannt.
Bilden nur der Tag und das Jahr einen zusammenhängenden Ziffern-String, werden sie wie folgt getrennt:
```
                Länge:        Abbildung:
                  2              tj
                  3              tjj
                  4              ttjj
                  5              tjjjj
                  6              ttjjjj
```
(Dabei steht "t" für "Tag" und "j" für "Jahr".)
Beispiele:
```
  "1 3 64"
  "01/03/64"
  "Jan 3 '64"
  "Jan 3 1964"
  "===> January 3rd 1964 (birthday)"
  "Jan31964"
  "Jan364"
  "ja364"
  "1364"
```
Experimentieren Sie! (Verwenden Sie hierzu auch die entsprechenden Beispielanwendungen im Unterverzeichnis "examples" der Distribution.)
$date = Compress($year,$month,$day);
Diese Funktion codiert ein Datum in 16-Bit und gibt diesen Wert zurück.
Das Codierungsschema ist dabei wie folgt:
```
            Bit Nr.:    FEDCBA9 8765 43210
            Inhalt:     jjjjjjj mmmm ttttt
```
(Dabei enthält "jjjjjjj" das Jahr, "mmmm" den Monat und "ttttt" den Tag.)
Die Funktion gibt "0" zurück, wenn die Eingabe kein gültiges Datum darstellt. Daher kann der Rückgabewert dieser Funktion auch in einem Bedingungsausdruck einer "if"-Anweisung stehen, mit der geprüft werden kann, ob die Eingabe ein gültiges Datum enthielt.
Aufgrund dieses besonderen Codierungsschemas ist es möglich, komprimierte Datumsangaben auf Gleichheit und Ordnung (größer/kleiner) zu vergleichen, OHNE sie vorher Dekodieren zu müssen!
Allerdings haben fortlaufende Datumsangaben NICHT notwendigerweise auch fortlaufende komprimierte Darstellungen!
Das bedeutet, daß die Inkrementierung der komprimierten Form des Datums zu einem neuen gültigen Datum FÜHREN KANN, ABER NICHT MUSS!
Beachten Sie auch, daß diese Funktion nur Datumswerte innerhalb eines Jahrhunderts verarbeiten kann.
Dieses Jahrhundert kann beliebig gewählt werden, indem man ein Basis-Jahrhundert und ein Basis-Jahr wählt (die sogenannte "Epoche"). In der Originaldistribution dieses Pakets ist das Basis-Jahrhundert mit "1900" und das Basis-Jahr mit "70" festgelegt (was dem Standard für UNIX-Systeme entspricht).
Damit kann diese Funktion Datumsangaben von "1970" bis "2069" verarbeiten.
Geben Sie also beispielsweise "95" an, geht das Paket automatisch von "1995" aus. Geben Sie hingegen eine Jahreszahl an, die KLEINER als 70 ist, etwa "64", geht das Paket davon aus, daß Sie "2064" meinen.
Sie sind aber nicht auf abgekürzte (aus zwei Ziffern bestehende) Jahresangaben beschränkt.
Die Funktion akzeptiert auch "lange" Jahreszahlen, solange sie im unterstützten Bereich liegen (bei der Originalkonfiguration dieses Pakets also im Bereich von "1970" bis "2069").
Bitte beachten Sie, daß diese Funktion in diesem Paket hauptsächlich aus Gründen der Rückwärtskompatibilität beibehalten wurde. Von ihrer Verwendung wird abgeraten.
if (($century,$year,$month,$day) = Uncompress($date))
Diese Funktion decodiert Datumsangaben, die vorher über die Funktion "Compress()" codiert wurden.
Zurückgegeben wird das Jahrhundert, das Jahr, der Monat und der Tag des in "$date" codierten Datums, wenn "$date" ein gültiges Datum repräsentiert. Anderenfalls wird eine leere Liste zurückgegeben.
Das in "$year" zurückgegebene Jahr besteht nur aus zwei Ziffern (d.h. die Jahreszahl modulo 100). Nur der Ausdruck "$century + $year" ergibt die "lange" Jahreszahl (z.B. 1900 + 95 = 1995).
Bitte beachten Sie, daß diese Funktion in diesem Paket hauptsächlich aus Gründen der Rückwärtskompatibilität beibehalten wurde. Von ihrer Verwendung wird abgeraten.
if (check_compressed($date))
Diese Funktion liefert "wahr" ("1") zurück, wenn der übergebene Wert ein gültiges komprimiertes Datum enthält. Anderenfalls wird "falsch" ("0") zurückgegeben.
Bitte beachten Sie, daß diese Funktion in diesem Paket hauptsächlich aus Gründen der Rückwärtskompatibilität beibehalten wurde. Von ihrer Verwendung wird abgeraten.
$string = Compressed_to_Text($date);
Diese Funktion liefert einen String fester Länge (immer 9 Zeichen) zurück, der die Textdarstellung des in "$date" enthaltenen komprimierten Datums enthält.
Dieser String hat die Form "tt-Mmm-jj", wobei "tt" für die zweistellige Tageszahl, "Mmm" für die ersten drei Buchstaben des Monats in der gerade gewählten Sprache (Informationen zur Mehrsprachigkeit dieses Pakets finden Sie weiter unten) und "jj" für die zweistellige Jahreszahl (d.h. die Jahreszahl modulo 100) steht.
Falls "$date" kein gültiges Datum darstellt, wird statt dessen der String "??-???-??" zurückgegeben.
Bitte beachten Sie, daß diese Funktion in diesem Paket hauptsächlich aus Gründen der Rückwärtskompatibilität beibehalten wurde. Von ihrer Verwendung wird abgeraten.
$string = Date_to_Text($year,$month,$day);
Diese Funktion liefert einen String zurück, der eine Textdarstellung des angegebenen Datums enthält. Der String hat das Format "www tt-Mmm-jjjj", wobei "www" die ersten drei Buchstaben des Wochentags in der gerade gewählten Sprache repräsentiert. Hier kann auch eine spezielle Abkürzung stehen, falls besondere Abkürzungen für die gewählte Sprache definiert wurden (Details zur Mehrsprachigkeit dieses Pakets finden Sie weiter unten). "tt" steht für den Tag (ein oder zwei Ziffern), "Mmm" für die ersten drei Buchstaben des Monats in der gerade gewählten Sprache und "jjjj" für das Jahr in voller Länge.
Ergeben die Eingabewerte kein gültiges Datum, kommt es zu einem fatalen Fehler ("not a valid date").
(Im Abschnitt "BEISPIELE" am Ende dieses Dokuments finden Sie ein Codefragment, das Ihnen zeigt, wie Sie Datumsangaben in jedem gewünschten Format aufbereiten können.)
$string = Date_to_Text_Long($year,$month,$day);
Diese Funktion liefert einen String zurück, der eine Textdarstellung des angegebenen Datums enthält. Der String hat das Format "wwwwww tt Mmmmmm jjjj", wobei "wwwwww" den Namen des Wochentags in der gerade gewählten Sprache repräsentiert (Details zur Mehrsprachigkeit dieses Pakets finden Sie weiter unten). "tt" steht für den Tag (ein oder zwei Ziffern), "Mmmmmm" für den Namen des Monats in der gerade gewählten Sprache und "jjjj" für das Jahr in voller Länge.
Ergeben die Eingabewerte kein gültiges Datum, kommt es zu einem fatalen Fehler ("not a valid date").
(Im Abschnitt "BEISPIELE" am Ende dieses Dokuments finden Sie ein Codefragment, das Ihnen zeigt, wie Sie Datumsangaben in jedem gewünschten Format aufbereiten können.)
$string = Calendar($year,$month);
Diese Funktion gibt (ähnlich dem UNIX-Programm "cal") einen Kalender des angegebenen Monats für das angegebene Jahr IN DER GERADE GEWÄHLTEN SPRACHE zurück (Details zur Mehrsprachigkeit dieses Pakets finden Sie weiter unten).
Beispiel:
```
  print Calendar(1998,5);
```
Dies führt zu folgender Ausgabe:
```
           May 1998
  Mon Tue Wed Thu Fri Sat Sun
                    1   2   3
    4   5   6   7   8   9  10
   11  12  13  14  15  16  17
   18  19  20  21  22  23  24
   25  26  27  28  29  30  31
```
$string = Month_to_Text($month);
Diese Funktion gibt den zugehörigen Namen zur Nummer des übergebenen Monats in der gerade gewählten Sprache zurück (Details zur Mehrsprachigkeit dieses Pakets finden Sie weiter unten).
Liegt der für den Monat übergebene Wert außerhalb des gültigen Wertebereichs von "1" bis "12", kommt es zu einem fatalen Fehler ("month out of range").
$string = Day_of_Week_to_Text($dow);
Diese Funktion gibt den zugehörigen Namen zur Nummer des übergebenen Wochentags in der gerade gewählten Sprache zurück (Details zur Mehrsprachigkeit dieses Pakets finden Sie weiter unten).
Liegt der für den Wochentag übergebene Wert außerhalb des gültigen Wertebereichs von "1" bis "7", kommt es zu einem fatalen Fehler ("day of week out of range").
$string = Day_of_Week_Abbreviation($dow);
Diese Funktion gibt eine spezielle Abkürzung des angegebenen Wochentages zurück, FALLS solche speziellen Abkürzungen für die gerade gewählte Sprache definiert wurden (Details zur Mehrsprachigkeit dieses Pakets finden Sie weiter unten).
(In der Originaldistribution dieses Pakets ist das nur bei Portugiesisch der Fall.)
Ist das nicht der Fall, werden die ersten drei Buchstaben des Wochentages in der gerade gewählten Sprache zurückgegeben.
Liegt der für den Wochentag übergebene Wert außerhalb des gültigen Wertebereichs von "1" bis "7", kommt es zu einem fatalen Fehler ("day of week out of range").
Im Augenblick wird die Tabelle der speziellen Abkürzungen intern nur von den Funktionen "Date_to_Text()" und "Calendar()" verwendet.
$string = Language_to_Text($lang);
Diese Funktion gibt den zugehörigen Namen aller durch das Paket unterstützten Sprachen zurück. Die diese Sprache repräsentierende interne Nummer wird dabei als Parameter übergeben.
Die Originaldistribution unterstützt die folgenden sechs Sprachen:
```
            1   ==>   English     (Englisch)      (Voreinstellung)
            2   ==>   Français    (Französisch)
            3   ==>   Deutsch
            4   ==>   Español     (Spanisch)
            5   ==>   Português   (Portugiesisch)
            6   ==>   Nederlands  (Niederländisch)
```
Im Abschnitt "How to install additional languages" in der Datei "INSTALL.txt" in dieser Distribution finden Sie Erläuterungen dazu, wie man weitere Sprachen in dieses Paket einbinden kann.
Die weiter unten folgende Beschreibung der Funktion "Languages()" zeigt Ihnen wie Sie bestimmen können, wieviele Sprachen in einer gegebenen Installation tatsächlich vorhanden sind.
$lang = Language();
Language($lang);
$oldlang = Language($newlang);
Mit Hilfe dieser Funktion können Sie ermitteln, welche Sprache gerade aktiv ist, und Sie können mit ihr die eingestellte Sprache wechseln.
Zu diesem Zweck besitzt jede Sprache in diesem Paket eine eindeutige interne Nummer.
Die Originaldistribution unterstützt die folgenden sechs Sprachen:
```
            1   ==>   English     (Englisch)      (Voreinstellung)
            2   ==>   Français    (Französisch)
            3   ==>   Deutsch
            4   ==>   Español     (Spanisch)
            5   ==>   Português   (Portugiesisch)
            6   ==>   Nederlands  (Niederländisch)
```
Im Abschnitt "How to install additional languages" in der Datei "INSTALL.txt" in dieser Distribution finden Sie Erläuterungen dazu, wie man weitere Sprachen in dieses Paket einbinden kann.
Die weiter unten folgende Beschreibung der Funktion "Languages()" zeigt Ihnen wie Sie bestimmen können, wieviele Sprachen in einer gegebenen Installation tatsächlich vorhanden sind.
VORSICHT: Um Ihren Programmen die Portabilität zu erhalten, dürfen Sie in diesem Paket AUF KEINEN FALL die interne Nummer einer Sprache EXPLIZIT verwenden, weil dieselbe Zahl auf verschiedenen Systemen für unterschiedliche Sprachen stehen kann (je nachdem um welche Sprachen eine bestimmte Installation erweitert wurde).
Daher müssen Sie immer mit einer Anweisung wie
```
  Language(Decode_Language("Name_der_Sprache"));
```
arbeiten, um die gewünschte Sprache zu wählen, und
```
  $language = Language_to_Text(Language());
```
oder
```
  $old_language = Language_to_Text(Language("Name_der_neuen_Sprache"));
```
verwenden, um die (vorher) gewählte Sprache zu ermitteln.
Ist die gewünschte Sprache in der aktuellen Installation nicht vorhanden, erhalten Sie so eine entsprechende Fehlermeldung, anstatt daß (ohne jeglichen Hinweis!) einfach die falsche Sprache verwendet wird (die bei der anderen Installation zufällig dieselbe interne Nummer besitzt).
Beachten Sie, daß bei der aktuellen Implementierung dieses Pakets die gewählte Sprache eine globale Einstellung ist, die für ALLE Funktionen gilt, die intern die Namen von Monaten, Wochentagen oder Sprachen verwenden. Sie ist auch für ALLE PROZESSE gültig, die gleichzeitig dieselbe Kopie der Shared-Library "Date::Calc" benutzen!
Das kann in einer Mehrbenutzerumgebung zu überraschenden Nebeneffekten führen, erst recht, wenn Perl in einer zukünftigen Version Multithreading unterstützen wird.
$max_lang = Languages();
Diese Funktion gibt die (maximale) Anzahl der Sprachen zurück, die Ihre Installation augenblicklich unterstützt.
(Dieser Wert kann von Installation zu Installation unterschiedlich sein.)
Im Abschnitt "How to install additional languages" in der Datei "INSTALL.txt" in dieser Distribution finden Sie Erläuterungen dazu, wie man weitere Sprachen in dieses Paket einbinden kann.
In der Originaldistribution dieses Pakets sind sechs Sprachen verfügbar. Der von dieser Installation zurückgelieferte Wert ist also "6", solange die jeweilige Installation noch nicht um zusätzliche Sprachen erweitert wurde.
if (($year,$month,$day) = Decode_Date_EU2($string))
Diese Funktion ist das Perl-Äquivalent zu der in C implementierten Funktion "Decode_Date_EU()". Sie wurde hier lediglich als Beispiel dafür mit aufgenommen, wie einfach es ist, mit Hilfe regulärer Ausdrücke eigene Routinen in Perl zu entwickeln, die an Ihre speziellen Wünsche angepaßt sind. Sie dient daher primär als Ausgangsbasis für Ihre eigenen Entwicklungen (sollte jemals die Notwendigkeit dafür entstehen).
In einem bestimmten Fall ist die Perl-Version allerdings etwas toleranter als die C-Variante, nämlich wenn es um die Klasse der erlaubten Trennzeichen geht.
(Können Sie den subtilen, nahezu unbedeutenden Unterschied herausfinden, indem Sie sich den Code ansehen? Oder durch ein Experiment? Hinweis: Probieren Sie beide Funktionen mit dem String "a3b1c64d" als Argument.)
if (($year,$month,$day) = Decode_Date_US2($string))
Diese Funktion ist das Perl-Äquivalent zu der in C implementierten Funktion "Decode_Date_US()". Sie wurde hier lediglich als Beispiel dafür mit aufgenommen, wie einfach es ist, mit Hilfe regulärer Ausdrücke eigene Routinen in Perl zu entwickeln, die an Ihre speziellen Wünsche angepaßt sind. Sie dient daher primär als Ausgangsbasis für Ihre eigenen Entwicklungen (sollte jemals die Notwendigkeit dafür entstehen).
In einem bestimmten Fall ist die Perl-Version allerdings etwas toleranter als die C-Variante.
(Hinweis: Das ist der gleiche Unterschied wie beim Funktionspaar "Decode_Date_EU()" und "Decode_Date_EU2()".)
In einem anderen Fall ist dagegen die C-Version etwas toleranter als die Perl-Variante.
(Können Sie den Unterschied feststellen, indem Sie sich den Code ansehen? Oder durch ein Experiment? Hinweis: Probieren Sie beide Funktionen mit dem String "(1/364)" als Argument.)
if (($year,$month,$day) = Parse_Date($string))
Diese Funktion ist nützlich, um Datumsangaben zu filtern (Parsing), wie sie vom UNIX-Befehl "date" geliefert werden oder auch in E-Mail-Headern vorkommen. (Auf diese Weise können Sie zum Beispiel bestimmen, wann eine E-Mail gesendet oder empfangen wurde.)
Beispiel 1:
```
  ($year,$month,$day) = Parse_Date(`/bin/date`);
```
Beispiel 2:
```
  while (<MAIL>)
  {
      if (/^From \S/)
      {
          ($year,$month,$day) = Parse_Date($_);
          ...
      }
      ...
  }
```
Die Funktion gibt eine leere Liste zurück, wenn kein gültiges Datum aus dem Eingabe-String herausgefiltert werden konnte.
$string = Date::Calc::Version();
Diese Funktion gibt einen String mit der (numerischen) Versionsnummer der C-Bibliothek ("DateCalc.c") zurück, die den Kern dieses Moduls bildet. (Diese Versionsnummer wird automatisch auch in die Datei "Calc.xs" übernommen.)
Beachten Sie, daß diese Versionsnummer unter normalen Bedingungen mit der Versionsnummer in der Perl-Variablen "$Date::Calc::VERSION" (in der Datei "Calc.pm") identisch sein sollte.
Weil diese Funktion nicht exportiert wird, muß sie immer explizit als "Date::Calc::Version()" qualifiziert werden. Auf diese Weise werden mögliche Konflikte mit Versionsfunktionen anderer Module vermieden.

BEISPIELE

Wie kann ich zwei Datumsangaben miteinander vergleichen?

Lösung 1:

  use Date::Calc qw( Date_to_Days );

  if (Date_to_Days($year1,$month1,$day1)  <
      Date_to_Days($year2,$month2,$day2))

  if (Date_to_Days($year1,$month1,$day1)  <=
      Date_to_Days($year2,$month2,$day2))

  if (Date_to_Days($year1,$month1,$day1)  >
      Date_to_Days($year2,$month2,$day2))

  if (Date_to_Days($year1,$month1,$day1)  >=
      Date_to_Days($year2,$month2,$day2))

  if (Date_to_Days($year1,$month1,$day1)  ==
      Date_to_Days($year2,$month2,$day2))

  if (Date_to_Days($year1,$month1,$day1)  !=
      Date_to_Days($year2,$month2,$day2))

  $cmp = (Date_to_Days($year1,$month1,$day1)  <=>
          Date_to_Days($year2,$month2,$day2));

Lösung 2:

  use Date::Calc qw( Delta_Days );

  if (Delta_Days($year1,$month1,$day1,
                 $year2,$month2,$day2) > 0)

  if (Delta_Days($year1,$month1,$day1,
                 $year2,$month2,$day2) >= 0)

  if (Delta_Days($year1,$month1,$day1,
                 $year2,$month2,$day2) < 0)

  if (Delta_Days($year1,$month1,$day1,
                 $year2,$month2,$day2) <= 0)

  if (Delta_Days($year1,$month1,$day1,
                 $year2,$month2,$day2) == 0)

  if (Delta_Days($year1,$month1,$day1,
                 $year2,$month2,$day2) != 0)

Wie kann ich prüfen, ob ein gegebenes Datum innerhalb eines bestimmten Datumsbereichs liegt?

  use Date::Calc qw( Date_to_Days );

  $lower = Date_to_Days($year1,$month1,$day1);
  $upper = Date_to_Days($year2,$month2,$day2);

  $date = Date_to_Days($year,$month,$day);

  if (($date >= $lower) && ($date <= $upper))
  {
      # OK
  }
  else
  {
      # nicht OK
  }

Wie kann ich prüfen, ob jemand ein bestimmtes Alter hat?

  use Date::Calc qw( Decode_Date_EU Today leap_year Delta_Days );

  $date = <STDIN>; # Geburtstag einlesen

  ($year1,$month1,$day1) = Decode_Date_EU($date);

  ($year2,$month2,$day2) = Today();

  if (($month1 == 2) && ($day1 == 29) && !leap_year($year2))
      { $day1--; }

  if ( (($year2 - $year1) >  18) ||
     ( (($year2 - $year1) == 18) &&
     (Delta_Days($year2,$month1,$day1, $year2,$month2,$day2) >= 0) ) )
  {
      print "Ok - Sie sind über 18.\n";
  }
  else
  {
      print "Sorry - Du bist noch keine 18!\n";
  }

Wie kann ich die Nummer der Woche innerhalb des Monats berechnen, in der das aktuelle Datum liegt?

Beispiel:

            April 1998
    Mon Tue Wed Thu Fri Sat Sun
              1   2   3   4   5  =  1. Woche
      6   7   8   9  10  11  12  =  2. Woche
     13  14  15  16  17  18  19  =  3. Woche
     20  21  22  23  24  25  26  =  4. Woche
     27  28  29  30              =  5. Woche

Lösung:

  use Date::Calc qw( Today Day_of_Week );

  ($year,$month,$day) = Today();

  $week = int(($day + Day_of_Week($year,$month,1) - 2) / 7) + 1;

Wie kann ich berechnen, ob ein bestimmtes Datum der 1., 2., 3., 4. oder 5. Wochentag innerhalb des gegebenen Monats ist?

Beispiel:

           October 2000
    Mon Tue Wed Thu Fri Sat Sun
                              1
      2   3   4   5   6   7   8
      9  10  11  12  13  14  15
     16  17  18  19  20  21  22
     23  24  25  26  27  28  29
     30  31

Ist Sonntag, der 15. Oktober 2000, der erste, zweite, dritte, vierte oder fünfte Sonntag dieses Monats?

Lösung:

  use Date::Calc qw( Delta_Days Nth_Weekday_of_Month_Year
                     Day_of_Week Day_of_Week_to_Text
                     Date_to_Text_Long Month_to_Text );

  %ordinal = ( 1 => 'st', 2 => 'nd', 3 => 'rd' );

  ($year,$month,$day) = (2000,10,15);

  $dow = Day_of_Week($year,$month,$day);

  $n = int( Delta_Days(
            Nth_Weekday_of_Month_Year($year,$month,$dow,1),
            $year,$month,$day)
            / 7) + 1;

  printf("%s is the %s %s in %s %d.\n",
      Date_to_Text_Long($year,$month,$day),
      $n . ($ordinal{$n} || 'th'),
      Day_of_Week_to_Text($dow),
      Month_to_Text($month),
      $year);

Ausgabe:

  Sunday, 15 October 2000 is the 3rd Sunday in October 2000.

Wie berechne ich das Datum des Mittwochs in derselben Woche wie das aktuelle Datum?

Lösung 1:

  use Date::Calc qw( Today Day_of_Week Add_Delta_Days );

  $searching_dow = 3; # 3 = Mittwoch

  @today = Today();

  $current_dow = Day_of_Week(@today);

  @date = Add_Delta_Days(@today, $searching_dow - $current_dow);

Lösung 2:

  use Date::Calc qw( Today Monday_of_Week
                     Week_of_Year Add_Delta_Days );

  $searching_dow = 3; # 3 = Mittwoch

  @today = Today();

  @date = Add_Delta_Days( Monday_of_Week( Week_of_Year(@today) ),
                          $searching_dow - 1 );

Lösung 3:

  use Date::Calc qw( Today Standard_to_Business
                           Business_to_Standard );

  @business = Standard_to_Business(Today());

  $business[2] = 3; # 3 = Mittwoch

  @date = Business_to_Standard(@business);

Wie kann ich einen Wochen-Offset zu einem Geschäftsdatum hinzuaddieren (mit korrekter Berücksichtigung von Jahresgrenzen)?

  use Date::Calc qw( Standard_to_Business Business_to_Standard );

  @temp = Business_to_Standard($year,$week,$dow);

  @temp = Add_Delta_Days(@temp, $week_offset * 7);

  ($year,$week,$dow) = Business_to_Standard(@temp);

Wie kann ich den vorhergehenden und den nächsten Samstag für ein gegebenes Datum ermitteln?

  use Date::Calc qw( Today Day_of_Week Add_Delta_Days
                     Day_of_Week_to_Text Date_to_Text );

  $searching_dow = 6; # 6 = Samstag

  @today = Today();

  $current_dow = Day_of_Week(@today);

  if ($searching_dow == $current_dow)
  {
      @prev = Add_Delta_Days(@today,-7);
      @next = Add_Delta_Days(@today,+7);
  }
  else
  {
      if ($searching_dow > $current_dow)
      {
          @next = Add_Delta_Days(@today,
                    $searching_dow - $current_dow);
          @prev = Add_Delta_Days(@next,-7);
      }
      else
      {
          @prev = Add_Delta_Days(@today,
                    $searching_dow - $current_dow);
          @next = Add_Delta_Days(@prev,+7);
      }
  }

  $dow = Day_of_Week_to_Text($searching_dow);

  print "Today is:      ", ' ' x length($dow),
                               Date_to_Text(@today), "\n";
  print "Last $dow was:     ", Date_to_Text(@prev),  "\n";
  print "Next $dow will be: ", Date_to_Text(@next),  "\n";

Ausgabe:

  Today is:              Sun 12-Apr-1998
  Last Saturday was:     Sat 11-Apr-1998
  Next Saturday will be: Sat 18-Apr-1998

Wie kann ich den letzten Werktag (Zahltag!) eines Monats bestimmen?

Lösung 1 (OHNE Berücksichtigung von Feiertagen):

  $day = Days_in_Month($year,$month);
  $dow = Day_of_Week($year,$month,$day);
  if ($dow > 5)
  {
      ($year,$month,$day) =
          Add_Delta_Days($year,$month,$day, 5-$dow);
  }

Lösung 2 (MIT Berücksichtigung von Feiertagen):

Diese Lösung verlangt ein mehrdimensionales Array "@holiday", das alle Feiertage in der Form "$holiday[$year][$month][$day] = 1;" enthält.

(Die Berechnung der beweglichen christlichen Feiertage finden Sie unter der Funktion "Easter_Sunday()" beschrieben.)

Tage, die keine Feiertage sind, sollten in diesem Array undefiniert bleiben oder den Wert null besitzen.

  $day = Days_in_Month($year,$month);
  while (1)
  {
      while ($holiday[$year][$month][$day])
      {
          ($year,$month,$day) =
              Add_Delta_Days($year,$month,$day, -1);
      }
      $dow = Day_of_Week($year,$month,$day);
      if ($dow > 5)
      {
          ($year,$month,$day) =
              Add_Delta_Days($year,$month,$day, 5-$dow);
      }
      else { last; }
  }

Wie kann ich einen "DATETIME"-Wert aus MS Visual Basic in seine Datums- und Zeitkomponenten zerlegen?

  use Date::Calc qw( Add_Delta_DHMS Date_to_Text );

  $datetime = "35883.121653";

  ($Dd,$Dh,$Dm,$Ds) = ($datetime =~ /^(\d+)\.(\d\d)(\d\d)(\d\d)$/);

  ($year,$month,$day, $hour,$min,$sec) =
      Add_Delta_DHMS(1900,1,1, 0,0,0, $Dd,$Dh,$Dm,$Ds);

  printf("The given date is %s %02d:%02d:%02d\n",
      Date_to_Text($year,$month,$day), $hour, $min, $sec);

Ausgabe:

  The given date is Tue 31-Mar-1998 12:16:53

Wie kann ich am Tag vor einem Treffen, das jeden ersten Freitag im Monat stattfindet, eine Erinnerungs-Mail an die Mitglieder der Gruppe schicken?

  use Date::Calc qw( Today Date_to_Days Add_Delta_YMD
                     Nth_Weekday_of_Month_Year );

  ($year,$month,$day) = Today();

  $tomorrow = Date_to_Days($year,$month,$day) + 1;

  $dow = 5; # 5 = Freitag
  $n   = 1; # 1 = erster Wochentag

  $meeting_this_month = Date_to_Days(
      Nth_Weekday_of_Month_Year($year,$month,$dow,$n) );

  ($year,$month,$day) = Add_Delta_YMD($year,$month,$day, 0,1,0);

  $meeting_next_month = Date_to_Days(
      Nth_Weekday_of_Month_Year($year,$month,$dow,$n) );

  if (($tomorrow == $meeting_this_month) ||
      ($tomorrow == $meeting_next_month))
  {
      # Mail an die Mitglieder der Gruppe schicken!
  }

Wie kann ich ein Datum in einem Format ausgeben, das nicht von den Funktionen "Date_to_Text()", "Date_to_Text_Long()" oder "Compressed_to_Text()" unterstützt wird?

  use Date::Calc qw( Day_of_Week Day_of_Week_to_Text
                     Month_to_Text Today );

  ($year,$month,$day) = Today();

Beispielsweise mit führenden Nullen für den Tag: "Fri 03-Jan-1964"

  printf("%.3s %02d-%.3s-%d\n",
      Day_of_Week_to_Text(Day_of_Week($year,$month,$day)),
      $day,
      Month_to_Text($month),
      $year);

Beispielsweise im US-amerikanischen Format: "April 12th, 1998"

  %ordinal = ( 1 => 'st', 2 => 'nd', 3 => 'rd' );

  sub ordinal
  {
      return( $_[0] .
          ( (substr($_[0],-2,1) ne '1') &&
            $ordinal{substr($_[0],-1)} ||
            'th' ) );
  }

  $string = sprintf("%s %s, %d",
                Month_to_Text($month),
                ordinal($day),
                $year);

(Siehe dazu auch den Eintrag über "printf()" und/oder "sprintf()" in perlfunc(1)!)

SIEHE AUCH

perl(1), perlfunc(1), perlsub(1), perlmod(1), perlxs(1), perlxstut(1), perlguts(1).

news:news.answers "Calendar FAQ, v. 1.9 (modified 25 Apr 1998) Part 1/3"

news:news.answers "Calendar FAQ, v. 1.9 (modified 25 Apr 1998) Part 2/3"

news:news.answers "Calendar FAQ, v. 1.9 (modified 25 Apr 1998) Part 3/3"

http://www.math.uio.no/faq/calendars/faq.html

http://www.pip.dknet.dk/~pip10160/calendar.html

(Alle von Claus Tondering mailto:c-t@pip.dknet.dk)

EINSCHRÄNKUNGEN

In der aktuellen Implementierung des Pakets wird die gewählte Sprache in einer globalen Variable gespeichert.

Aus diesem Grund kann es zu unerwünschten Nebeneffekten kommen, wenn das Modul "Date::Calc" in Form einer Shared-Library genutzt oder sobald Perl Multithreading unterstützen wird. (Das Problem ist, daß ein Prozeß oder Thread immer die Sprache für ALLE ANDEREN Prozesse oder Threads mit wählt.)

VERSION

Diese Manual Page dokumentiert "Date::Calc" in der Version 4.2.

AUTOR

  Steffen Beyer
  mailto:sb@fluomedia.org
  http://sb.fluomedia.org/download/

URHEBERRECHTE

ÜBERSETZUNG

(Vom Modulautor gegengelesen und überarbeitet)

Erschienen in: "Programmieren mit Perl-Modulen", O'Reilly Verlag Köln, 1999.

Verwendung hier mit freundlicher Genehmigung des O'Reilly Verlag, Köln.

LIZENZ

Dieses Paket ist Freie Software und kann unter denselben Lizenzbedingungen benutzt, modifiziert und weitergegeben werden wie Perl, d.h. es gelten die Bestimmungen der "Artistic License" oder (wahlweise) der "GNU General Public License".

Die C-Bibliothek, die den Kern dieses Perl-Moduls bildet, kann darüber hinaus auch unter den Lizenzbedingungen der "GNU Library General Public License" benutzt, modifiziert und weitergegeben werden.

Bitte beachten Sie die Dateien "Artistic.txt", "GNU_GPL.txt" und "GNU_LGPL.txt" in dieser Distribution für die entsprechenden Details!

HAFTUNGSAUSSCHLUSS

Die vorliegende Software wird so zur Verfügung gestellt wie sie ist, es werden keinerlei Garantien für ihre Eignung für welche Zwecke auch immer abgegeben, und es wird auch keine Haftung für die durch ihre Verwendung oder Nichtverwendbarkeit möglicherweise verursachten Schäden oder Ausfälle oder dergleichen übernommen, selbst wenn dem Autor solche möglichen Folgen bekannt sein oder bekannt gemacht werden sollten.

Siehe dazu auch die "GNU General Public License" für weitere Details.

Date::CalcHandbuch-Seite

Date::Calc
Handbuch-Seite