Kommentare fuer API-Doku hinzugefuegt

ulrich

2023-03-24 a2b5909d2b689f4f609218d80087a332ce55f2be

Kommentare fuer API-Doku hinzugefuegt

 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;
  }  

 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;

 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;

  /**

 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)));
    }
}