Dokumentation AppleScript Kalenderfunktionen

7 Feb 2010 - 11:31

Kalender-Grundfunktionen

© Jürgen Schell 2010
http://www.j-schell.de

To English Version

Dokumentation und Code stehen unter der Lesser GNU Public License.
http://www.gnu.org/licenses/lgpl.txt

Es wird keinerlei Garantie für das korrekte Verhalten dieser Funktionen übernommen. Betrachten Sie den Code als eine Trainings-Implementation.

Die Kalender-Grundfunktionen mögen für einige Leute nützlich sein.
Einige dieser Funktionen sind sehr trivial, andere weniger.
Beachten Sie, dass fast alle Funktionen defizite in der AppleScript-Datumsimplementation ausgleichen sollen. Das Mac OS implementiert die meisten davon (plus eine Reihe nützlicher anderer Dinge), aber die AppleScript-Entwickler waren der Meinung, das meiste davon solle nicht für die Nutzung durch Sie durchgereicht werden.

Viel Code in diesen Funktionen wurde angeregt durch das Buch "Calendrical Calculations" von Nachum Dershowitz und Edward M. Reingold, Cambridge 2008, sowie von Teilen des Quellcodes der PHP Kalendererweiterung. Die Implementation hier unterscheidet sich aber von beiden Vorlagen.

Jürgen Schell, Langenfeld. Mai 2009

Allgemeine Hinweise zu den Funktionen:

Ist ein Argument Ganzzahl, versucht der Code eine entsprechende Typwandlung. Bei einer Fließkommazahl werden dabei Nachkommastellen gerundet.

Argumente von Typ date werden auf ihre Klasse überprüft.

Hat ein Argument die falsche Klasse oder liegt außerhalb der gültigen Werte, wird der Fehler 1700 ausgelöst. Die Fehlermeldung ist detaillierter.

Funktionen mit dem wort "date" im Namen verlangen entweder ein AppleScript-Datumsobjekt als Argument oder liefern eins ab. Funktionen mit "cdn" im Namen erwarten als Argument eine chronologische julianische Tagesnummer oder liefern eine zurück.

Liste der Funktionen:

newDate( Jahr, Monat, Tag )

Resultat: AS Datumsobjekt
Zweck: Lokaleunabhängige Erzeugung von Datumsobjekten

Jahr, Monat und Tag sind Ganzzahlen, bei Fließkommazahlen werden Nachkommastellen gerundet.
Gültige Bereiche:
1 <= Jahr
1 <= Monat <= 12
1 <= Tag <= 127

Ein Fehler wird ausgelöst, wenn ein Argument außerhalb seines Bereichs liegt.

Erzeugt ein Datum entsprechend der Eigenschaften. Die Zeit wird auf Mitternacht gesetzt. Beachten Sie den Hinweis "Bereiche in newDate / newDateTime ("Überlauf") am Ende.

Sollen unzulässige Daten verhindert werden (z.B. 29. Februar 2011), entfernen Sie die Kommentarklammern im Bereich "check code".

newDateTime( Jahr, Monat, Tag, Stunde, Minute, Sekunde )

Resultat: AS Datumsobjekt
Zweck: Lokaleunabhängige Erzeugung von Datumsobjekten mit Uhrzeit

Jahr, Monat, Tag, STunde, Minute und Sekunde sind Ganzzahlen, bei Fließkommazahlen werden Nachkommastellen gerundet.
Gültige Bereiche:
1 <= Jahr
1 <= Monat <= 12
1 <= Tag <= 127
1 <= Stunde <= 127
1 <= Minute <= 127
1 <= Sekunde <= 32767

Ein Fehler wird ausgelöst, wenn ein Argument außerhalb seines Bereichs liegt.

Erzeugt ein Datum mit Uhrzeit entsprechend der Eigenschaften. Beachten Sie den Hinweis "Bereiche in newDate / newDateTime ("Überlauf").

Sollen unzulässige Daten verhindert werden (z.B. 29. Februar 2011), entfernen Sie die Kommentarklammern im Bereich "check code".

DateToISOdayofweek ( Datumsobjekt )

Resultat: Ganzzahl
Zweck: Tagesnummer ermitteln mit Montag als erstem Wochentag

Liefert die Nummer des Wochentages entsprechend ISO zurück: Montag = 1, ..., Sonntag = 7.

DateToISOweekofyear( Datumsobjekt )

Resultat: Ganzzahl
Zweck: Kalenderwoche ermitteln für Länder, die nach ISO zählen.

Die Funktion liefert die Nummer der Woche zurück, in der Datumsobjekt liegt. Gezählt werden Wochen nach ISO-Regeln. (ISO-Wochen haben immer sieben Tage. 1. Januar im Jahr XXXX kann zur ersten Woche von XXXX gehören, aber auch zur letzten des Vorjahres. Die erste Woche des Jahres ist die erste, die mindestens vier Tage im Jahr XXXX hat.)

preceding_day( Wochentagsnummer, Datumsobjekt oder Tagesnummer )

Resultat: Datumsobjekt oder Ganzzahl, abhängig vom zweiten Argument.
Zweck: Das Datum eines bestimmten Wochentages vor einem Datum zu finden. Nützlich für eine Reihe spezieller Tage wie dem 1. Advent oder dem US Election Day.

Die Funktion liefert das Datum des gegebenen Wochentages vor dem gegebenen Datum zurück. Wochentagsnummer kann eine Ganzzahl von 1 bis 7 sein. Es gilt ISO-Konvention, also Montag ist 1, Sonntag ist 7. AppleScript-Tagesnamen (Sunday, Monday...) können alternativ benutzt werden.

Datumsobjekt oder Tagesnummer ist entweder ein AppleScript Datumsobjekt oder eine chronologische Julianische Tagesnummer. Wird ein Datumsobjekt benutzt, liefert die Funktion ein Datumsobjekt. Wird eine Nummer benutzt, liefert die Funktion eine Nummer.

date_to_cdn( Datumsobjekt )

Resultat: Ganzzahl
Zweck: Ermitteln der chronologischen julianischen Tagesnummer eines Datums.

Liefert die chronologische julianische Tagesnummer von Datumsobjekt zurück.

greg_to_cdn ( Jahr, Monat, Tag )

Resultat: Ganzzahl
Zweck: Umwandeln eines als drei Zahlen gegebenes Datum in eine chronologische julianische Tagesnummer, auch jenseits der Grenzen eines AppleScript Datumsobjekts.

Argumente sind Ganzzahlen.
Gültige Bereiche:
1 <= Monat <= 12
1 <= Tag <= 31
Werte außerhalb der Bereiche werden auf den nächsten Wert gerundet. Tageswerte laufen über, d.h. 29. Februar eines Gemeinjahres ergibt dasselbe wie der 1. März des Jahres.

Die Funktion liefert eine chronologische julianische Tagesnummer für ein Datum im gregorianischen Kalender, gegeben als Jahr, Monat und Tag.

Die Funktion erlaubt ein Jahr 0. Mit anderen Worten: 0 steht für Jahr 1 vor der Zeitenwende. -1 für das Jahr 2 v.d.Z. etc. (Dies ist für den gregorianischen Kalender konsistent mit ISO.)

cdn_to_date ( Tagesnummer )

Resultat: AS Datumsobjekt
Zweck: Konvertieren einer chronologischen julianischen Tagesnummer in ein Datum.

Das Argument ist Ganzzahl. Nachkommastellen werden ggf. gerundet.
Gültiger Bereich:
Tagesnummer >= 1721426
(1. Januar 0001)

Liefert das Datumsobjekt für die gegebene chronologische julianische Tagesnummer zurück.

cdn_to_greg ( Tagesnummer )

Resultat: Record
Zweck: Konvertierung einer chronologischen julianischen Tagesnummer in einen Datumsrecord, auch jenseits der Zeitschranken des AppleScript-Datumsobjekts.

Tagesnummer ist eine Ganzzahl.
Hat Tagesnummer Nachkommastellen, werden diese gerundet.

Liefert einen Record mit den Elementen year, month und day.

year im Ergebnis-Record folgt dem ISO-Komzept mit einem Jahr 0. Das heißt: Jahr -99 in diesem Schema ist dasselbe wie Jahr 100 vor der Zeitenwende in traditionellen Zählweisen.

julian_to_cdn ( Jahr_ad, Monat, Tag )

Resultat: Ganzzahl
Zweck: Ermitteln der chronologischen julianischen Tagesnummer zu einem Datum des julianischen Kalenders

Die Argumente sind Ganzzahlen aus folgenden Bereichen:
1 <= Monat <= 12
1 <= Tag <= 31
Werte außerhalb der Bereiche werden auf den nächsten Wert gerundet.

Die Funktion liefert die chronologische julianische Tagesnummer für ein Datum, gegeben als Jahr anno domini, Monat und Tag.

Um Rechenoperationen zu vereinfachen, erlaubt der Code ein Jahr 0. Das heißt: 0 steht für Jahr 1 vor Christi. -2 für das Jahr 2 vor Christi etc.

Tageswerte laufen über, d.h. 29. Februar eines Gemeinjahres ergibt dasselbe wie der 1. März des Jahres.

cdn_to_julian ( Tagesnummer )

Resultat: Record {year, month, day}
Zweck: Ermimtteln einer Datumsbeschreibung im julianischen Kalender für eine chronologische julianische Tagesnummer

Das Argument ist eine Ganzzahl
Gültiger Bereich:
Teagesnummer >= 0,

Tagesnummer ist die gegebene chronologische julianische Tagesnummer. Negative Werte lösen einen Fehler aus. Der Ergebnis-Record hat die Elemente year, month und day, jedes eine Ganzzahl.

Jahre vor Christi werden als 0 oder negative Werte geliefert. "0" meint das Jahr 1 vor Christi, "-1" das Jahr 2 vor Christi etc.

easter_greg_date ( Jahr_ad )

Resultat: AS Datumsobjekt
Zweck: Ermmitteln des Osterdatums für ein bestimmtes Jahr

Das Argument Jahr_ad ist eine Ganzzahl
Gültiger Bereich:
Jahr_ad >= 1
Niedrigere Werte lösen einen Fehler aus, Nachkommastellen werden gerundet.

Die Funktion liefert das Osterdatum des gegebenen Jahres als AS Datumsobjekt. Der Code beruht weitgehend auf Dershowitz/Reingold.

easter_greg_cdn ( Jahr_ad )

Resultat: Ganzzahl
Braucht: greg_to_cdn
Zweck: Ermmitteln des Osterdatums für ein bestimmtes Jahr als chronologische julianische Tagesnummer

Das Argument ist eine Ganzzahl.
Nachkommastellen werden ggf. gerundet.

Grundsätzlich der gleiche Code wie easter_greg_date, aber die Funktion liefert nicht ein AppleScript-Datumsobjekt. Statt dessen arbeitet sie im Konzept der chronologischen julianischen Tagesnummern.

easter_jul_date ( Jahr_ad )

Resultat: AS Datumsobjekt
Braucht: julian_to_cdn, cdn_to_date
Zweck: Ermitteln des Datums für das julianische (im wesentlichen: Orthodoxe) Osterfest im gregorianischen Kalender.

Das Argument ist eine Ganzzahl. Nachkommastellen werden ggf. gerundet.
Gültiger Bereich:
Jahr_ad >= 1

Liefert ein AppleScript-Datumsobjekt für das orthodoxe Osterdatum im gegebenen Jahr anno domini. Eigenschaften des Datumsobjekts geören zum gregorianischen Kalender, wie bei jedem AS-Datumsobjekt.

easter_jul_cdn ( Jahr_ad )

Resultat: Ganzzahl
Braucht: julian_to_cdn
Zweck: Ermitteln des julianischen Osterdatums für Jahr_ad als chronologische julianische Tagesnummer.

Das Argument ist eine Ganzzahl. Nachkommastellen werden ggf. gerundet.
Gültiger Bereich:
Jahr_ad >= 1

Grundsätzlich der gleiche Code wie easter_jul_date, aber die Funktion liefert nicht ein AppleScript-Datumsobjekt. Statt dessen arbeitet sie im Konzept der chronologischen julianischen Tagesnummern.

rosh_hashanah_cdn ( Jahr_am )

Resultat: Ganzzahl
Zweck: Ermitteln der chronologischen julianischen Tagesnummer für den 1. Tischri des Jahres anno mundi.

Das Argument ist eine Ganzzahl (Jahreszahl im hebräischen Kalender).
Gültiger Bereich:
Jahr_am >= 1

Die Funktion liefert die chronologische julianische Tagesnummer für den Neujahrstag des Jahres.

(Hinweis: Jahr am = Jahr ad + 3760 für die Tage vom 1. Januar bis zum 29. Elul. Jahr am = Jahr ad + 3761 für Tage vom 1. Tischri bis zum 31. Dezember.)

heb_to_cdn ( Jahr_am, Monat, Tag )

Resultat: Ganzzahl
Braucht: rosh_hashanah_cdn
Zweck: Konvertieren eines hebräischen Datums in eine chronologische julianische Tagesnummer.

Alle Argumente sind Ganzzahlen mit folgenden gültigen Bereichen:
Jahr_am >= 1
1 <= Monat <= 13
1 <= Tag <= 30
Argumente außerhalb der Bereiche lösen einen Fehler aus.

Jahr_am ist das Jahr anno mundi eines hebräischen Datums. Monat ist die Monatsnummer, gezählt von Nisan als 1. Tag ist die Nummer des Tages im Monat.

Monate und Schaltjahre: Monat 12 ist Adar in Gemeinjahren, Adar I in Schaltjahren. Monat 13 ist Adar in Gemeinjahren, Adar II in Schaltjahren.

Überlauf von Tagen: In Monaten mit 29 Tagen liefert 30 den 1. des Folgemonats. Beispiel: 30. Kislew liefert den 1. Tevet in kurzen Jahren. 30. Adar Rischon liefert den 1. Nisan in Gemeinjahren.

cdn_to_heb ( Tagesnummer )

Resultat: Record {year, month, day}
Braucht: rosh_hashanah_cdn
Zweck: Konvertieren einer chronologischen julianischen Tagesnummer in ein hebräisches Datum.

Das Argument ist eine Ganzzahl.
Gültiger Bereich:
Tagesnummer >= 347998 (Startpunkt des hebräischen Kalenders)

Liefert einen Record mit den Elementen year, month und day für das Datum im hebräischen Kalender. Bei den Monaten wird Nisan als 1 gezählt, Adar Scheni in Schaltjahren als 13.

is_leap_greg ( Jahr )

Resultat: Wahrheitswert
Zweck: Test, ob das Jahr ein Schaltjahr im gregorianischen Kalender ist.

As Argument ist eine Ganzzahl für das Jahr. Das Ergbnis ist true, wenn das Jahr ein Schaltjahr im gregorianischen Kalender ist, anderenfalls false.

is_leap_jul ( Jahr )

Resultat: Wahrheitswert
Zweck: Test, ob das Jahr ein Schaltjahr im julianischen Kalender ist.

As Argument ist eine Ganzzahl für das Jahr. Das Ergbnis ist true, wenn das Jahr ein Schaltjahr im julianischen Kalender ist, anderenfalls false.

is_leap_heb ( Jahr )

Resultat: Wahrheitswert
Zweck: Test, ob das Jahr ein Schaltjahr im hebräischen Kalender ist.

As Argument ist eine Ganzzahl für das Jahr. Das Ergbnis ist true, wenn das Jahr ein Schaltjahr im hebräischen Kalender ist, anderenfalls false.

___________________________________

Hinweise

Bereiche in newDate / newDateTime ("Überlauf")

Setzt man die Ganzzahl-Eigenschaften eines AS Datumsobjekts, sind Werte möglich, die auf den ersten Blick verblüffen.

year: Mögliche Daten sind begrenzt auf den 1 Januar 1000 bis zum 31. Dezember 9999, Wenn ein Datum im Script Editor eingegeben wird. Das ist eher ein Verhalten des Parsers im Editor beim Kompilieren des Scripts. Setzt man die Jahreszahl-Eigenschaft numerisch, sind Werte von 1 bis 32767 möglich. (Man kann das Jahr auf 0 setzen, aber das Verhalten ist seltsam.)

month: Monate sind Konstanten, keine Ganzzahlen. Das Verhalten wird seltsam, wenn man Werte jenseits von 12 setzt. (Der Wert 13 scheint sich allerdings zu verhalten, wie man von einem Überlauf erwartet.)

days: Tage laufen wie erwartet über in einem Bereich von 1 bis 127. Bei höheren Werten wird es seltsam. Es schreint, dass das höchste der 8 bits in Zweier-Komplement-Darstellung interpretiert wird: 256 verhält sich wie 0 und liefert den letzten des Vormonats, 255 ist -1 und liefert 2 Tage zuvor usw. Mir ist keine technische Dokumentation bekannt, die dieses Verhalten spezifiziert, deshalb Vorsicht, wenn man das Verhalten als "Feature" benutzt.

hour: Stunden zeigen dasselbe Zweierkomplement-Verhalten wie day. Das Verhalten ist also wie erwartet im Bereich 0 bis 127.

minute: Wie hour.

second: Der gültige Bereich ist 0 bis 32767

Chronologische julianische Tagesnummern

"Julianische Daten" zählen Zeit, die seit Mittag dem 1. Januar 4713 vor Christi im julianischen Kalender vergangen sind (= 24. November 4714 vor der Zeitrechnung im gregorianischen Kalender). Werden diese Werte als Kalender benutzt, ist es üblich, sie auf Mitternacht zu normieren. Damit ist jede julianische Tagesnummer eine Fließkommazahlm, die auf ",5" endet. Zur Vereinfachung in Kalenderrechnungen wurde das Konzept einer chronologischen julianischen Tagesnummer eingeführt, die Ganzzahlen benutzt.

Chronologische julianische Tagesnummern werden als Zwischenkalender benutzt. Damit ist die Konvertierung von Daten zwischen beliebigen implementierten Kalendern möglich.