From a2b5909d2b689f4f609218d80087a332ce55f2be Mon Sep 17 00:00:00 2001
From: ulrich
Date: Fri, 24 Mar 2023 17:49:02 +0000
Subject: [PATCH] Kommentare fuer API-Doku hinzugefuegt
---
src/de/uhilger/zeitrechnung/ereignis/EinzelEreignis.java | 2
src/de/uhilger/zeitrechnung/ereignis/ChinesischesEreignis.java | 2
src/de/uhilger/zeitrechnung/ChinesischesDatum.java | 49 +++++++++
src/de/uhilger/zeitrechnung/kalender/ChinesischerKalender.java | 207 ++++++++++++++++++++++++++++++-----------
4 files changed, 202 insertions(+), 58 deletions(-)
diff --git a/src/de/uhilger/zeitrechnung/ChinesischesDatum.java b/src/de/uhilger/zeitrechnung/ChinesischesDatum.java
index 3ece41c..e0c9f79 100644
--- a/src/de/uhilger/zeitrechnung/ChinesischesDatum.java
+++ b/src/de/uhilger/zeitrechnung/ChinesischesDatum.java
@@ -1,6 +1,27 @@
+/*
+ Zeitrechnung - a class library to determine calendar events
+ Copyright (c) 1984-2023 Ulrich Hilger, http://uhilger.de
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
package de.uhilger.zeitrechnung;
/**
+ * Einfache Klasse fuer ein ChinesischesDatum, die neben
+ * Jahr, Monat und Tag auch den Zyklus im chinesischen
+ * Kalender abbildet und festhaelt, ob der Monat ein
+ * Schaltmonat ist.
*
* @author Ulrich Hilger
*/
@@ -9,28 +30,56 @@
private long zyklus;
private boolean schaltmonat;
+ /**
+ * Ein Objekt der Klasse ChinesischesDatum erzeugen
+ */
public ChinesischesDatum() {
super();
}
+ /**
+ * Ein Objekt der Klasse ChinesischesDatum erzeugen
+ *
+ * @param zyklus der Zyklus des chinesischen Kalenders
+ * @param jahr das Jahr im chinesischen Kalender
+ * @param monat der Monat im chinesischen Kalender
+ * @param schaltmonat true, wenn der Monat ein Schaltmonat ist, sonst false
+ * @param tag Tag im Monat des chinesischen Kalenders
+ */
public ChinesischesDatum(long zyklus, long jahr, int monat, boolean schaltmonat, int tag) {
super(jahr, monat, tag);
this.zyklus = zyklus;
this.schaltmonat = schaltmonat;
}
+ /**
+ * Den Zyklus dieses Datums im chinesischen Kalender ermitteln
+ * @return Zyklus
+ */
public long getZyklus() {
return zyklus;
}
+ /**
+ * Den Zyklkus im chinesischen Kalender angeben
+ * @param zyklus der Zyklus dieses Datums
+ */
public void setZyklus(long zyklus) {
this.zyklus = zyklus;
}
+ /**
+ * Ermitteln, ob der Monat dieses Datums ein Schaltmonat ist
+ * @return true, wenn der Monat ein Schaltmonat ist, sonst false
+ */
public boolean isSchaltmonat() {
return schaltmonat;
}
+ /**
+ * Angeben, ob der Monat dieses Datums ein Schaltmonat ist
+ * @param schaltmonat true, wenn der Monat ein Schaltmonat ist, sonst false
+ */
public void setSchaltmonat(boolean schaltmonat) {
this.schaltmonat = schaltmonat;
}
diff --git a/src/de/uhilger/zeitrechnung/ereignis/ChinesischesEreignis.java b/src/de/uhilger/zeitrechnung/ereignis/ChinesischesEreignis.java
index ff9b9f8..421bc76 100644
--- a/src/de/uhilger/zeitrechnung/ereignis/ChinesischesEreignis.java
+++ b/src/de/uhilger/zeitrechnung/ereignis/ChinesischesEreignis.java
@@ -55,7 +55,7 @@
public List<Datum> getZeitpunkte(long isoJahr) {
Definition def = getDefinition();
ChinesischerKalender j = new ChinesischerKalender();
- long tag = j.cDatumZuGenerisch(isoJahr, (int) def.getp1(), (int) def.getp2());
+ long tag = j.cDatumZuTagen(isoJahr, (int) def.getp1(), (int) def.getp2());
List daten = new ArrayList();
daten.add(new ISOKalender().vonTagen(tag));
return daten;
diff --git a/src/de/uhilger/zeitrechnung/ereignis/EinzelEreignis.java b/src/de/uhilger/zeitrechnung/ereignis/EinzelEreignis.java
index 4ce9094..ec8c730 100644
--- a/src/de/uhilger/zeitrechnung/ereignis/EinzelEreignis.java
+++ b/src/de/uhilger/zeitrechnung/ereignis/EinzelEreignis.java
@@ -51,8 +51,10 @@
/** Typnummer fuer Jom Ha Zikaron */
public static final int EE_JOM_HA_ZIKARON = 4;
+ /** Typnummer fuer das chinesische Neujahr */
public static final int EE_CHINESISCHES_NEUJAHR = 5;
+ /** Typnummer fuer Qingming */
public static final int EE_QINGMING = 6;
/**
diff --git a/src/de/uhilger/zeitrechnung/kalender/ChinesischerKalender.java b/src/de/uhilger/zeitrechnung/kalender/ChinesischerKalender.java
index aaad010..baf2fda 100644
--- a/src/de/uhilger/zeitrechnung/kalender/ChinesischerKalender.java
+++ b/src/de/uhilger/zeitrechnung/kalender/ChinesischerKalender.java
@@ -57,25 +57,86 @@
*/
public class ChinesischerKalender extends BasisKalender implements Wandler {
+ /**
+ * Der Start der chinesischen Zeitrechung laesst sich aus dem heutigen
+ * chinesischen Datum errechnen. Das erste Jahr des ersten Zyklus faellt
+ * so auf den 15. Februar -2636 im gregorianischen Kalender.
+ */
public static final long STARTTAG = new ISOKalender().zuTagen(-2636, Definition.FEBRUAR, 15);
private long zyklus;
private boolean schaltmonat;
+ /**
+ * Den Zyklus angeben, in dem ein Jahr des chinesischen Kalenders liegt, das
+ * mit der Methode zuTagen(jahr, monat, tag) in ein generisches Datum
+ * umgerechnet werden soll.
+ *
+ * Diese Methode ist eine Hilfsfunktion, wenn nicht die Methode
+ * zuTagen(zyklus, jahr, monat, schaltmonat, tag) genutzt werden kann.
+ *
+ * @param zyklus der Zyklus im chinesischen Ḱalender
+ */
public void setZyklus(long zyklus) {
this.zyklus = zyklus;
}
+ /**
+ * Angeben, ob ein Monat eines Datums im chinesischen Kalender ein
+ * Schaltmonat ist, das mit der Methode
+ * zuTagen(jahr, monat, tag) in ein generisches Datum
+ * umgerechnet werden soll.
+ *
+ * Diese Methode ist eine Hilfsfunktion, wenn nicht die Methode
+ * zuTagen(zyklus, jahr, monat, schaltmonat, tag) genutzt werden kann.
+ *
+ * @param schaltmonat
+ */
public void setSchaltmonat(boolean schaltmonat) {
this.schaltmonat = schaltmonat;
}
+ /**
+ * Die Anzahl der Tage ermitteln, die zwischen einem gegebenen Datum
+ * des chinesischen Kalenders und dem Tag liegen, der im
+ * Gregorianischen Kalender mit dem Datum 1. Januar 1 bezeichnet ist.
+ *
+ * @param zyklus der Zyklus des chinesischen Kalenders
+ * @param jahr das Jahr des chinesischen Kalenders
+ * @param monat der Monat des chinesischen Kalenders
+ * @param schaltmonat true, wenn der Monat ein Schaltmonat ist, sonst false
+ * @param tag Tag im Monat des chinesischen Kalenders
+ *
+ * @return Anzahl Tage, die zwischen dem gegebenen Datum
+ * des chinesischen Kalenders und dem Tag liegen, der im
+ * Gregorianischen Kalender mit dem Datum 1. Januar 1 bezeichnet ist.
+ * Liegt das gegebene Datum vor dem 1. Januar 1 (gregorianisch), wird
+ * eine negative Zahl zurueckgegeben.
+ */
public long zuTagen(long zyklus, int jahr, int monat, boolean schaltmonat, int tag) {
this.zyklus = zyklus;
this.schaltmonat = schaltmonat;
return zuTagen(jahr, monat, tag);
}
+ /**
+ * Die Anzahl der Tage ermitteln, die zwischen einem gegebenen Datum
+ * des chinesischen Kalenders und dem Tag liegen, der im
+ * Gregorianischen Kalender mit dem Datum 1. Januar 1 bezeichnet ist.
+ *
+ * Bei Verwendung dieser Methode muessen zuvor die Methode setZyklus
+ * und setSchaltmonat genutzt werden.
+ *
+ * @param jahr das Jahr im betreffenden Kalendersystem
+ * @param monat der Monat im betreffenden Kalendersystem
+ * @param tag der Tag im betreffenden Kalendersysem
+ *
+ * @return Anzahl Tage, die zwischen dem gegebenen Datum
+ * des chinesischen Kalenders und dem Tag liegen, der im
+ * Gregorianischen Kalender mit dem Datum 1. Januar 1 bezeichnet ist.
+ * Liegt das gegebene Datum vor dem 1. Januar 1 (gregorianisch), wird
+ * eine negative Zahl zurueckgegeben.
+ */
@Override
public long zuTagen(long jahr, int monat, int tag) {
long midYear = (long)Math.floor(STARTTAG + ((zyklus - 1) * 60 + (jahr - 1) + .5) * MITTLERES_TROPISCHES_JAHR);
@@ -88,6 +149,19 @@
return priorNewMoon + tag - 1;
}
+ /**
+ * Die Anzahl der Tage ermitteln, die zwischen einem gegebenen Datum
+ * des chinesischen Kalenders und dem Tag liegen, der im
+ * Gregorianischen Kalender mit dem Datum 1. Januar 1 bezeichnet ist.
+ *
+ * @param d das Datum im betreffenden Kalendersystem
+ *
+ * @return Anzahl Tage, die zwischen dem gegebenen Datum
+ * des chinesischen Kalenders und dem Tag liegen, der im
+ * Gregorianischen Kalender mit dem Datum 1. Januar 1 bezeichnet ist.
+ * Liegt das gegebene Datum vor dem 1. Januar 1 (gregorianisch), wird
+ * eine negative Zahl zurueckgegeben.
+ */
@Override
public long zuTagen(Datum d) {
if(d instanceof ChinesischesDatum) {
@@ -98,6 +172,15 @@
}
}
+ /**
+ * Das Datum des chinesischen Kalenders fuer ein generisches Datum
+ * ermitteln.
+ *
+ * @param tage Anzahl der Tage zwischen 1. Januar 1 im gregorianischen
+ * Kalender und dem Tag, dessen Datum des chinesischen Kalenders
+ * ermittelt werden soll
+ * @return das Datum im chinesischen Kalender
+ */
@Override
public ChinesischesDatum vonTagen(long tage) {
long s1 = winterSonnenwendeAmOderVor(tage);
@@ -120,25 +203,53 @@
return new ChinesischesDatum(cycle, year, month, leapMonth, day);
}
- /* ---- */
-
- public boolean hatSchaltmonatVorher(long mPrime, long m) {
- return m >= mPrime && (keinSolarerHauptabschnitt(m) || hatSchaltmonatVorher(mPrime, chinesischerNeumondVor(m)));
- }
-
- public double mitternachtInChina(long date) {
- return universalVonStandard(date, chinesischerOrt(date));
- }
-
- public final Ort peking(double tee) {
+ public long neujahr(long isoJahr) {
ISOKalender g = new ISOKalender();
- long year = g.jahrVonTagen((long)Math.floor(tee));
+ return neujahrAmOderVor(g.zuTagen(isoJahr, Definition.JULI, 1));
+ }
+
+ public long qingMing(long isoJahr) {
+ ISOKalender g = new ISOKalender();
+ return (long)Math.floor(solarerNebenabschnittAmOderNach(g.zuTagen(isoJahr, Definition.MAERZ, 30)));
+ }
+
+ /**
+ * Das generische Datum des Tages mit einem gegebenen festen Datum
+ * im chinesischen Kalender fuer ein gegebenes gregorianisches Jahr
+ * ermitteln
+ *
+ * @param isoJahr Jahr im gregorischen Kalender, in das ein gesuchtes Ereignis faellt
+ * @param cMonat Monat im chinesischen Kalender, an dem das Ereignis stattfindet
+ * @param cTag Tag im Monat des chinesischen Kalenders, an dem das Ereignis stattfindet
+ * @return generisches Datum des Ereignisses
+ */
+ public long cDatumZuTagen(long isoJahr, int cMonat, int cTag) {
+ ISOKalender g = new ISOKalender();
+ long elapsedYears = isoJahr - g.jahrVonTagen(STARTTAG) + 1;
+ long cycle = ganzzahlQuotient(elapsedYears - 1, 60) + 1;
+ int year = (int)moduloAngepasst(elapsedYears, 60);
+ return zuTagen(cycle, year, cMonat, false, cTag);
+ }
+
+ /* ---- Hilfsfunktionen --------- */
+
+ public boolean hatSchaltmonatVorher(long mHaupt, long m) {
+ return m >= mHaupt && (keinSolarerHauptabschnitt(m) || hatSchaltmonatVorher(mHaupt, chinesischerNeumondVor(m)));
+ }
+
+ public double mitternachtInChina(long tage) {
+ return universalVonStandard(tage, chinesischerOrt(tage));
+ }
+
+ public final Ort peking(double t) {
+ ISOKalender g = new ISOKalender();
+ long year = g.jahrVonTagen((long)Math.floor(t));
return new Ort("Peking", (double) (39.55), winkel(116,25,0),
(double) (43.5), year < 1929 ? 1397d/180 : 8);
}
- public final Ort chinesischerOrt(double tee) {
- return peking(tee);
+ public final Ort chinesischerOrt(double t) {
+ return peking(t);
}
public long neujahrAmOderVor(long tage) {
@@ -151,77 +262,59 @@
long s2 = winterSonnenwendeAmOderVor(s1 + 370);
long m12 = chinesischerNeumondAmOderNach(s1 + 1);
long m13 = chinesischerNeumondAmOderNach(m12 + 1);
- long nextM11 = chinesischerNeumondVor(s2 + 1);
- if((Math.round((nextM11 - m12) / MITTLERER_SYNODISCHER_MONAT) == 12) && (keinSolarerHauptabschnitt(m12) || keinSolarerHauptabschnitt(m13))) {
+ long naechsterM11 = chinesischerNeumondVor(s2 + 1);
+ if((Math.round((naechsterM11 - m12) / MITTLERER_SYNODISCHER_MONAT) == 12) && (keinSolarerHauptabschnitt(m12) || keinSolarerHauptabschnitt(m13))) {
return chinesischerNeumondAmOderNach(m13 + 1);
} else {
return m13;
}
}
- public long neujahr(long gYear) {
- ISOKalender g = new ISOKalender();
- return neujahrAmOderVor(g.zuTagen(gYear, Definition.JULI, 1));
- }
-
- public long qingMing(long gYear) {
- ISOKalender g = new ISOKalender();
- return (long)Math.floor(solarerNebenabschnittAmOderNach(g.zuTagen(gYear, Definition.MAERZ, 30)));
- }
-
- public long cDatumZuGenerisch(long isoJahr, int cMonat, int cTag) {
- ISOKalender g = new ISOKalender();
- long elapsedYears = isoJahr - g.jahrVonTagen(STARTTAG) + 1;
- long cycle = ganzzahlQuotient(elapsedYears - 1, 60) + 1;
- int year = (int)moduloAngepasst(elapsedYears, 60);
- return zuTagen(cycle, year, cMonat, false, cTag);
- }
-
- public long winterSonnenwendeAmOderVor(long date) {
- double approx = geschaetzteSolareLaengeVor(mitternachtInChina(date + 1), Definition.WINTER);
+ public long winterSonnenwendeAmOderVor(long tage) {
+ double approx = geschaetzteSolareLaengeVor(mitternachtInChina(tage + 1), Definition.WINTER);
long i;
for(i = (long)(Math.floor(approx) - 1); !(Definition.WINTER <= solareLaenge(mitternachtInChina(i + 1))); ++i);
return i;
}
- public boolean keinSolarerHauptabschnitt(long date) {
- return aktuellerSolarerHauptabschnitt(date) ==
- aktuellerSolarerHauptabschnitt(chinesischerNeumondAmOderNach(date + 1));
+ public boolean keinSolarerHauptabschnitt(long tage) {
+ return aktuellerSolarerHauptabschnitt(tage) ==
+ aktuellerSolarerHauptabschnitt(chinesischerNeumondAmOderNach(tage + 1));
}
- public int aktuellerSolarerHauptabschnitt(long date) {
- double s = solareLaenge(standardVonUniversal(date, chinesischerOrt(date)));
+ public int aktuellerSolarerHauptabschnitt(long tage) {
+ double s = solareLaenge(standardVonUniversal(tage, chinesischerOrt(tage)));
return (int)moduloAngepasst(2 + ganzzahlQuotient(s, (double) (30)), 12);
}
- public double solarerHauptabschnittAmOderNach(long date) {
- double l = modulo(30 * Math.ceil(solareLaenge(mitternachtInChina(date)) / 30), 360);
- return chinesischeSolareLaengeAmOderNach(date, l);
+ public double solarerHauptabschnittAmOderNach(long tage) {
+ double l = modulo(30 * Math.ceil(solareLaenge(mitternachtInChina(tage)) / 30), 360);
+ return chinesischeSolareLaengeAmOderNach(tage, l);
}
- public double solarerNebenabschnittAmOderNach(long date) {
- double l = modulo(30 * Math.ceil((solareLaenge(mitternachtInChina(date)) - (double) (15)) / 30) + (double) (15), 360);
- return chinesischeSolareLaengeAmOderNach(date, l);
+ public double solarerNebenabschnittAmOderNach(long tage) {
+ double l = modulo(30 * Math.ceil((solareLaenge(mitternachtInChina(tage)) - (double) (15)) / 30) + (double) (15), 360);
+ return chinesischeSolareLaengeAmOderNach(tage, l);
}
- public double chinesischeSolareLaengeAmOderNach(long date, double theta) {
- Ort beijing = chinesischerOrt(date);
- double tee = solareLaengeNach(standardVonUniversal(date, beijing), theta);
- return standardVonUniversal(tee, beijing);
+ public double chinesischeSolareLaengeAmOderNach(long tage, double theta) {
+ Ort peking = chinesischerOrt(tage);
+ double t = solareLaengeNach(standardVonUniversal(tage, peking), theta);
+ return standardVonUniversal(t, peking);
}
- public int aktuellerSolarerUnterabschnitt(long date) {
- double s = solareLaenge(mitternachtInChina(date));
+ public int aktuellerSolarerUnterabschnitt(long tage) {
+ double s = solareLaenge(mitternachtInChina(tage));
return (int)moduloAngepasst(3 + ganzzahlQuotient(s - (double) (15), (double) (30)), 12);
}
- public long chinesischerNeumondAmOderNach(long date) {
- double t = neumondNach(mitternachtInChina(date));
+ public long chinesischerNeumondAmOderNach(long tage) {
+ double t = neumondNach(mitternachtInChina(tage));
return (long)Math.floor(standardVonUniversal(t, chinesischerOrt(t)));
}
- public long chinesischerNeumondVor(long date) {
- double t = neumondVor((long) mitternachtInChina(date));
+ public long chinesischerNeumondVor(long tage) {
+ double t = neumondVor((long) mitternachtInChina(tage));
return (long)Math.floor(standardVonUniversal(t, chinesischerOrt(t)));
}
}
--
Gitblit v1.9.3