The Tor Browser: intl/icu/source/i18n/astro.h@6474c204b198 (annotated)

intl/icu/source/i18n/astro.h@6474c204b198 (annotated)

intl/icu/source/i18n/astro.h

Wed, 31 Dec 2014 06:09:35 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Wed, 31 Dec 2014 06:09:35 +0100
changeset 0: 6474c204b198
permissions: -rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

 /************************************************************************
  * Copyright (C) 1996-2008, International Business Machines Corporation *
  * and others. All Rights Reserved.                                     *
  ************************************************************************
  *  2003-nov-07   srl       Port from Java
  */
 #ifndef ASTRO_H
 #define ASTRO_H
 #include "unicode/utypes.h"
 #if !UCONFIG_NO_FORMATTING
 #include "gregoimp.h"  // for Math
 #include "unicode/unistr.h"
 U_NAMESPACE_BEGIN
 /**
  * <code>CalendarAstronomer</code> is a class that can perform the calculations to
  * determine the positions of the sun and moon, the time of sunrise and
  * sunset, and other astronomy-related data.  The calculations it performs
  * are in some cases quite complicated, and this utility class saves you
  * the trouble of worrying about them.
  * <p>
  * The measurement of time is a very important part of astronomy.  Because
  * astronomical bodies are constantly in motion, observations are only valid
  * at a given moment in time.  Accordingly, each <code>CalendarAstronomer</code>
  * object has a <code>time</code> property that determines the date
  * and time for which its calculations are performed.  You can set and
  * retrieve this property with {@link #setDate setDate}, {@link #getDate getDate}
  * and related methods.
  * <p>
  * Almost all of the calculations performed by this class, or by any
  * astronomer, are approximations to various degrees of accuracy.  The
  * calculations in this class are mostly modelled after those described
  * in the book
  * <a href="http://www.amazon.com/exec/obidos/ISBN=0521356997" target="_top">
  * Practical Astronomy With Your Calculator</a>, by Peter J.
  * Duffett-Smith, Cambridge University Press, 1990.  This is an excellent
  * book, and if you want a greater understanding of how these calculations
  * are performed it a very good, readable starting point.
  * <p>
  * <strong>WARNING:</strong> This class is very early in its development, and
  * it is highly likely that its API will change to some degree in the future.
  * At the moment, it basically does just enough to support {@link IslamicCalendar}
  * and {@link ChineseCalendar}.
  *
  * @author Laura Werner
  * @author Alan Liu
  * @internal
  */
 class U_I18N_API CalendarAstronomer : public UMemory {
 public:
   // some classes
 public:
   /**
    * Represents the position of an object in the sky relative to the ecliptic,
    * the plane of the earth's orbit around the Sun.
    * This is a spherical coordinate system in which the latitude
    * specifies the position north or south of the plane of the ecliptic.
    * The longitude specifies the position along the ecliptic plane
    * relative to the "First Point of Aries", which is the Sun's position in the sky
    * at the Vernal Equinox.
    * <p>
    * Note that Ecliptic objects are immutable and cannot be modified
    * once they are constructed.  This allows them to be passed and returned by
    * value without worrying about whether other code will modify them.
    *
    * @see CalendarAstronomer.Equatorial
    * @see CalendarAstronomer.Horizon
    * @internal
    */
   class U_I18N_API Ecliptic : public UMemory {
   public:
     /**
      * Constructs an Ecliptic coordinate object.
      * <p>
      * @param lat The ecliptic latitude, measured in radians.
      * @param lon The ecliptic longitude, measured in radians.
      * @internal
      */
     Ecliptic(double lat = 0, double lon = 0) {
       latitude = lat;
       longitude = lon;
     }
     /**
      * Setter for Ecliptic Coordinate object
      * @param lat The ecliptic latitude, measured in radians.
      * @param lon The ecliptic longitude, measured in radians.
      * @internal
      */
     void set(double lat, double lon) {
       latitude = lat;
       longitude = lon;
     }
     /**
      * Return a string representation of this object
      * @internal
      */
     UnicodeString toString() const;
     /**
      * The ecliptic latitude, in radians.  This specifies an object's
      * position north or south of the plane of the ecliptic,
      * with positive angles representing north.
      * @internal
      */
     double latitude;
     /**
      * The ecliptic longitude, in radians.
      * This specifies an object's position along the ecliptic plane
      * relative to the "First Point of Aries", which is the Sun's position
      * in the sky at the Vernal Equinox,
      * with positive angles representing east.
      * <p>
      * A bit of trivia: the first point of Aries is currently in the
      * constellation Pisces, due to the precession of the earth's axis.
      * @internal
      */
     double longitude;
   };
   /**
    * Represents the position of an
    * object in the sky relative to the plane of the earth's equator.
    * The <i>Right Ascension</i> specifies the position east or west
    * along the equator, relative to the sun's position at the vernal
    * equinox.  The <i>Declination</i> is the position north or south
    * of the equatorial plane.
    * <p>
    * Note that Equatorial objects are immutable and cannot be modified
    * once they are constructed.  This allows them to be passed and returned by
    * value without worrying about whether other code will modify them.
    *
    * @see CalendarAstronomer.Ecliptic
    * @see CalendarAstronomer.Horizon
    * @internal
    */
   class U_I18N_API Equatorial : public UMemory {
   public:
     /**
      * Constructs an Equatorial coordinate object.
      * <p>
      * @param asc The right ascension, measured in radians.
      * @param dec The declination, measured in radians.
      * @internal
      */
     Equatorial(double asc = 0, double dec = 0)
       : ascension(asc), declination(dec) { }
     /**
      * Setter
      * @param asc The right ascension, measured in radians.
      * @param dec The declination, measured in radians.
      * @internal
      */
     void set(double asc, double dec) {
       ascension = asc;
       declination = dec;
     }
     /**
      * Return a string representation of this object, with the
      * angles measured in degrees.
      * @internal
      */
     UnicodeString toString() const;
     /**
      * Return a string representation of this object with the right ascension
      * measured in hours, minutes, and seconds.
      * @internal
      */
     //String toHmsString() {
     //return radToHms(ascension) + "," + radToDms(declination);
     //}
     /**
      * The right ascension, in radians.
      * This is the position east or west along the equator
      * relative to the sun's position at the vernal equinox,
      * with positive angles representing East.
      * @internal
      */
     double ascension;
     /**
      * The declination, in radians.
      * This is the position north or south of the equatorial plane,
      * with positive angles representing north.
      * @internal
      */
     double declination;
   };
   /**
    * Represents the position of an  object in the sky relative to
    * the local horizon.
    * The <i>Altitude</i> represents the object's elevation above the horizon,
    * with objects below the horizon having a negative altitude.
    * The <i>Azimuth</i> is the geographic direction of the object from the
    * observer's position, with 0 representing north.  The azimuth increases
    * clockwise from north.
    * <p>
    * Note that Horizon objects are immutable and cannot be modified
    * once they are constructed.  This allows them to be passed and returned by
    * value without worrying about whether other code will modify them.
    *
    * @see CalendarAstronomer.Ecliptic
    * @see CalendarAstronomer.Equatorial
    * @internal
    */
   class U_I18N_API Horizon : public UMemory {
   public:
     /**
      * Constructs a Horizon coordinate object.
      * <p>
      * @param alt  The altitude, measured in radians above the horizon.
      * @param azim The azimuth, measured in radians clockwise from north.
      * @internal
      */
     Horizon(double alt=0, double azim=0)
       : altitude(alt), azimuth(azim) { }
     /**
      * Setter for Ecliptic Coordinate object
      * @param alt  The altitude, measured in radians above the horizon.
      * @param azim The azimuth, measured in radians clockwise from north.
      * @internal
      */
     void set(double alt, double azim) {
       altitude = alt;
       azimuth = azim;
     }
     /**
      * Return a string representation of this object, with the
      * angles measured in degrees.
      * @internal
      */
     UnicodeString toString() const;
     /**
      * The object's altitude above the horizon, in radians.
      * @internal
      */
     double altitude;
     /**
      * The object's direction, in radians clockwise from north.
      * @internal
      */
     double azimuth;
   };
 public:
   //-------------------------------------------------------------------------
   // Assorted private data used for conversions
   //-------------------------------------------------------------------------
   // My own copies of these so compilers are more likely to optimize them away
   static const double PI;
   /**
    * The average number of solar days from one new moon to the next.  This is the time
    * it takes for the moon to return the same ecliptic longitude as the sun.
    * It is longer than the sidereal month because the sun's longitude increases
    * during the year due to the revolution of the earth around the sun.
    * Approximately 29.53.
    *
    * @see #SIDEREAL_MONTH
    * @internal
    * @deprecated ICU 2.4. This class may be removed or modified.
    */
   static const double SYNODIC_MONTH;
   //-------------------------------------------------------------------------
   // Constructors
   //-------------------------------------------------------------------------
   /**
    * Construct a new <code>CalendarAstronomer</code> object that is initialized to
    * the current date and time.
    * @internal
    */
   CalendarAstronomer();
   /**
    * Construct a new <code>CalendarAstronomer</code> object that is initialized to
    * the specified date and time.
    * @internal
    */
   CalendarAstronomer(UDate d);
   /**
    * Construct a new <code>CalendarAstronomer</code> object with the given
    * latitude and longitude.  The object's time is set to the current
    * date and time.
    * <p>
    * @param longitude The desired longitude, in <em>degrees</em> east of
    *                  the Greenwich meridian.
    *
    * @param latitude  The desired latitude, in <em>degrees</em>.  Positive
    *                  values signify North, negative South.
    *
    * @see java.util.Date#getTime()
    * @internal
    */
   CalendarAstronomer(double longitude, double latitude);
   /**
    * Destructor
    * @internal
    */
   ~CalendarAstronomer();
   //-------------------------------------------------------------------------
   // Time and date getters and setters
   //-------------------------------------------------------------------------
   /**
    * Set the current date and time of this <code>CalendarAstronomer</code> object.  All
    * astronomical calculations are performed based on this time setting.
    *
    * @param aTime the date and time, expressed as the number of milliseconds since
    *              1/1/1970 0:00 GMT (Gregorian).
    *
    * @see #setDate
    * @see #getTime
    * @internal
    */
   void setTime(UDate aTime);
   /**
    * Set the current date and time of this <code>CalendarAstronomer</code> object.  All
    * astronomical calculations are performed based on this time setting.
    *
    * @param aTime the date and time, expressed as the number of milliseconds since
    *              1/1/1970 0:00 GMT (Gregorian).
    *
    * @see #getTime
    * @internal
    */
   void setDate(UDate aDate) { setTime(aDate); }
   /**
    * Set the current date and time of this <code>CalendarAstronomer</code> object.  All
    * astronomical calculations are performed based on this time setting.
    *
    * @param jdn   the desired time, expressed as a "julian day number",
    *              which is the number of elapsed days since
    *              1/1/4713 BC (Julian), 12:00 GMT.  Note that julian day
    *              numbers start at <em>noon</em>.  To get the jdn for
    *              the corresponding midnight, subtract 0.5.
    *
    * @see #getJulianDay
    * @see #JULIAN_EPOCH_MS
    * @internal
    */
   void setJulianDay(double jdn);
   /**
    * Get the current time of this <code>CalendarAstronomer</code> object,
    * represented as the number of milliseconds since
    * 1/1/1970 AD 0:00 GMT (Gregorian).
    *
    * @see #setTime
    * @see #getDate
    * @internal
    */
   UDate getTime();
   /**
    * Get the current time of this <code>CalendarAstronomer</code> object,
    * expressed as a "julian day number", which is the number of elapsed
    * days since 1/1/4713 BC (Julian), 12:00 GMT.
    *
    * @see #setJulianDay
    * @see #JULIAN_EPOCH_MS
    * @internal
    */
   double getJulianDay();
   /**
    * Return this object's time expressed in julian centuries:
    * the number of centuries after 1/1/1900 AD, 12:00 GMT
    *
    * @see #getJulianDay
    * @internal
    */
   double getJulianCentury();
   /**
    * Returns the current Greenwich sidereal time, measured in hours
    * @internal
    */
   double getGreenwichSidereal();
 private:
   double getSiderealOffset();
 public:
   /**
    * Returns the current local sidereal time, measured in hours
    * @internal
    */
   double getLocalSidereal();
   /**
    * Converts local sidereal time to Universal Time.
    *
    * @param lst   The Local Sidereal Time, in hours since sidereal midnight
    *              on this object's current date.
    *
    * @return      The corresponding Universal Time, in milliseconds since
    *              1 Jan 1970, GMT.
    */
   //private:
   double lstToUT(double lst);
   /**
    *
    * Convert from ecliptic to equatorial coordinates.
    *
    * @param ecliptic     The ecliptic
    * @param result       Fillin result
    * @return reference to result
    */
   Equatorial& eclipticToEquatorial(Equatorial& result, const Ecliptic& ecliptic);
   /**
    * Convert from ecliptic to equatorial coordinates.
    *
    * @param eclipLong     The ecliptic longitude
    * @param eclipLat      The ecliptic latitude
    *
    * @return              The corresponding point in equatorial coordinates.
    * @internal
    */
   Equatorial& eclipticToEquatorial(Equatorial& result, double eclipLong, double eclipLat);
   /**
    * Convert from ecliptic longitude to equatorial coordinates.
    *
    * @param eclipLong     The ecliptic longitude
    *
    * @return              The corresponding point in equatorial coordinates.
    * @internal
    */
   Equatorial& eclipticToEquatorial(Equatorial& result, double eclipLong) ;
   /**
    * @internal
    */
   Horizon& eclipticToHorizon(Horizon& result, double eclipLong) ;
   //-------------------------------------------------------------------------
   // The Sun
   //-------------------------------------------------------------------------
   /**
    * The longitude of the sun at the time specified by this object.
    * The longitude is measured in radians along the ecliptic
    * from the "first point of Aries," the point at which the ecliptic
    * crosses the earth's equatorial plane at the vernal equinox.
    * <p>
    * Currently, this method uses an approximation of the two-body Kepler's
    * equation for the earth and the sun.  It does not take into account the
    * perturbations caused by the other planets, the moon, etc.
    * @internal
    */
   double getSunLongitude();
   /**
    * TODO Make this public when the entire class is package-private.
    */
   /*public*/ void getSunLongitude(double julianDay, double &longitude, double &meanAnomaly);
   /**
    * The position of the sun at this object's current date and time,
    * in equatorial coordinates.
    * @param result fillin for the result
    * @internal
    */
   Equatorial& getSunPosition(Equatorial& result);
 public:
   /**
    * Constant representing the vernal equinox.
    * For use with {@link #getSunTime getSunTime}.
    * Note: In this case, "vernal" refers to the northern hemisphere's seasons.
    * @internal
    */
 //  static double VERNAL_EQUINOX();
   /**
    * Constant representing the summer solstice.
    * For use with {@link #getSunTime getSunTime}.
    * Note: In this case, "summer" refers to the northern hemisphere's seasons.
    * @internal
    */
   static double SUMMER_SOLSTICE();
   /**
    * Constant representing the autumnal equinox.
    * For use with {@link #getSunTime getSunTime}.
    * Note: In this case, "autumn" refers to the northern hemisphere's seasons.
    * @internal
    */
 //  static double AUTUMN_EQUINOX();
   /**
    * Constant representing the winter solstice.
    * For use with {@link #getSunTime getSunTime}.
    * Note: In this case, "winter" refers to the northern hemisphere's seasons.
    * @internal
    */
   static double WINTER_SOLSTICE();
   /**
    * Find the next time at which the sun's ecliptic longitude will have
    * the desired value.
    * @internal
    */
   UDate getSunTime(double desired, UBool next);
   /**
    * Returns the time (GMT) of sunrise or sunset on the local date to which
    * this calendar is currently set.
    *
    * NOTE: This method only works well if this object is set to a
    * time near local noon.  Because of variations between the local
    * official time zone and the geographic longitude, the
    * computation can flop over into an adjacent day if this object
    * is set to a time near local midnight.
    *
    * @internal
    */
   UDate getSunRiseSet(UBool rise);
   //-------------------------------------------------------------------------
   // The Moon
   //-------------------------------------------------------------------------
   /**
    * The position of the moon at the time set on this
    * object, in equatorial coordinates.
    * @internal
    * @return const reference to internal field of calendar astronomer. Do not use outside of the lifetime of this astronomer.
    */
   const Equatorial& getMoonPosition();
   /**
    * The "age" of the moon at the time specified in this object.
    * This is really the angle between the
    * current ecliptic longitudes of the sun and the moon,
    * measured in radians.
    *
    * @see #getMoonPhase
    * @internal
    */
   double getMoonAge();
   /**
    * Calculate the phase of the moon at the time set in this object.
    * The returned phase is a <code>double</code> in the range
    * <code>0 <= phase < 1</code>, interpreted as follows:
    * <ul>
    * <li>0.00: New moon
    * <li>0.25: First quarter
    * <li>0.50: Full moon
    * <li>0.75: Last quarter
    * </ul>
    *
    * @see #getMoonAge
    * @internal
    */
   double getMoonPhase();
   class U_I18N_API MoonAge : public UMemory {
   public:
     MoonAge(double l)
       :  value(l) { }
     void set(double l) { value = l; }
     double value;
   };
   /**
    * Constant representing a new moon.
    * For use with {@link #getMoonTime getMoonTime}
    * @internal
    */
   static const MoonAge NEW_MOON();
   /**
    * Constant representing the moon's first quarter.
    * For use with {@link #getMoonTime getMoonTime}
    * @internal
    */
 //  static const MoonAge FIRST_QUARTER();
   /**
    * Constant representing a full moon.
    * For use with {@link #getMoonTime getMoonTime}
    * @internal
    */
   static const MoonAge FULL_MOON();
   /**
    * Constant representing the moon's last quarter.
    * For use with {@link #getMoonTime getMoonTime}
    * @internal
    */
 //  static const MoonAge LAST_QUARTER();
   /**
    * Find the next or previous time at which the Moon's ecliptic
    * longitude will have the desired value.
    * <p>
    * @param desired   The desired longitude.
    * @param next      <tt>true</tt> if the next occurrance of the phase
    *                  is desired, <tt>false</tt> for the previous occurrance.
    * @internal
    */
   UDate getMoonTime(double desired, UBool next);
   UDate getMoonTime(const MoonAge& desired, UBool next);
   /**
    * Returns the time (GMT) of sunrise or sunset on the local date to which
    * this calendar is currently set.
    * @internal
    */
   UDate getMoonRiseSet(UBool rise);
   //-------------------------------------------------------------------------
   // Interpolation methods for finding the time at which a given event occurs
   //-------------------------------------------------------------------------
   // private
   class AngleFunc : public UMemory {
   public:
     virtual double eval(CalendarAstronomer&) = 0;
     virtual ~AngleFunc();
   };
   friend class AngleFunc;
   UDate timeOfAngle(AngleFunc& func, double desired,
                     double periodDays, double epsilon, UBool next);
   class CoordFunc : public UMemory {
   public:
     virtual void eval(Equatorial& result, CalendarAstronomer&) = 0;
     virtual ~CoordFunc();
   };
   friend class CoordFunc;
   double riseOrSet(CoordFunc& func, UBool rise,
                    double diameter, double refraction,
                    double epsilon);
   //-------------------------------------------------------------------------
   // Other utility methods
   //-------------------------------------------------------------------------
 private:
   /**
    * Return the obliquity of the ecliptic (the angle between the ecliptic
    * and the earth's equator) at the current time.  This varies due to
    * the precession of the earth's axis.
    *
    * @return  the obliquity of the ecliptic relative to the equator,
    *          measured in radians.
    */
   double eclipticObliquity();
   //-------------------------------------------------------------------------
   // Private data
   //-------------------------------------------------------------------------
 private:
   /**
    * Current time in milliseconds since 1/1/1970 AD
    * @see java.util.Date#getTime
    */
   UDate fTime;
   /* These aren't used yet, but they'll be needed for sunset calculations
    * and equatorial to horizon coordinate conversions
    */
   double fLongitude;
   double fLatitude;
   double fGmtOffset;
   //
   // The following fields are used to cache calculated results for improved
   // performance.  These values all depend on the current time setting
   // of this object, so the clearCache method is provided.
   //
   double    julianDay;
   double    julianCentury;
   double    sunLongitude;
   double    meanAnomalySun;
   double    moonLongitude;
   double    moonEclipLong;
   double    meanAnomalyMoon;
   double    eclipObliquity;
   double    siderealT0;
   double    siderealTime;
   void clearCache();
   Equatorial  moonPosition;
   UBool       moonPositionSet;
   /**
    * @internal
    */
 //  UDate local(UDate localMillis);
 };
 U_NAMESPACE_END
 struct UHashtable;
 U_NAMESPACE_BEGIN
 /**
  * Cache of month -> julian day
  * @internal
  */
 class CalendarCache : public UMemory {
 public:
   static int32_t get(CalendarCache** cache, int32_t key, UErrorCode &status);
   static void put(CalendarCache** cache, int32_t key, int32_t value, UErrorCode &status);
   virtual ~CalendarCache();
 private:
   CalendarCache(int32_t size, UErrorCode& status);
   static void createCache(CalendarCache** cache, UErrorCode& status);
   /**
    * not implemented
    */
   CalendarCache();
   UHashtable *fTable;
 };
 U_NAMESPACE_END
 #endif
 #endif

The Tor Browser / annotate

intl/icu/source/i18n/astro.h@6474c204b198 (annotated)

intl/icu/source/i18n/astro.h