1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /************************************************************************
4 * Copyright (C) 1996-2008,2014 International Business Machines Corporation *
5 * and others. All Rights Reserved. *
6 ************************************************************************
7 * 2003-nov-07 srl Port from Java
13 #include "unicode/utypes.h"
15 #if !UCONFIG_NO_FORMATTING
17 #include "gregoimp.h" // for Math
18 #include "unicode/unistr.h"
23 * <code>CalendarAstronomer</code> is a class that can perform the calculations to
24 * determine the positions of the sun and moon, the time of sunrise and
25 * sunset, and other astronomy-related data. The calculations it performs
26 * are in some cases quite complicated, and this utility class saves you
27 * the trouble of worrying about them.
29 * The measurement of time is a very important part of astronomy. Because
30 * astronomical bodies are constantly in motion, observations are only valid
31 * at a given moment in time. Accordingly, each <code>CalendarAstronomer</code>
32 * object has a <code>time</code> property that determines the date
33 * and time for which its calculations are performed. You can set and
34 * retrieve this property with {@link #setDate setDate}, {@link #getDate getDate}
35 * and related methods.
37 * Almost all of the calculations performed by this class, or by any
38 * astronomer, are approximations to various degrees of accuracy. The
39 * calculations in this class are mostly modelled after those described
41 * <a href="http://www.amazon.com/exec/obidos/ISBN=0521356997" target="_top">
42 * Practical Astronomy With Your Calculator</a>, by Peter J.
43 * Duffett-Smith, Cambridge University Press, 1990. This is an excellent
44 * book, and if you want a greater understanding of how these calculations
45 * are performed it a very good, readable starting point.
47 * <strong>WARNING:</strong> This class is very early in its development, and
48 * it is highly likely that its API will change to some degree in the future.
49 * At the moment, it basically does just enough to support {@link IslamicCalendar}
50 * and {@link ChineseCalendar}.
52 * @author Laura Werner
56 class U_I18N_API CalendarAstronomer
: public UMemory
{
62 * Represents the position of an object in the sky relative to the ecliptic,
63 * the plane of the earth's orbit around the Sun.
64 * This is a spherical coordinate system in which the latitude
65 * specifies the position north or south of the plane of the ecliptic.
66 * The longitude specifies the position along the ecliptic plane
67 * relative to the "First Point of Aries", which is the Sun's position in the sky
68 * at the Vernal Equinox.
70 * Note that Ecliptic objects are immutable and cannot be modified
71 * once they are constructed. This allows them to be passed and returned by
72 * value without worrying about whether other code will modify them.
74 * @see CalendarAstronomer.Equatorial
75 * @see CalendarAstronomer.Horizon
78 class U_I18N_API Ecliptic
: public UMemory
{
81 * Constructs an Ecliptic coordinate object.
83 * @param lat The ecliptic latitude, measured in radians.
84 * @param lon The ecliptic longitude, measured in radians.
87 Ecliptic(double lat
= 0, double lon
= 0) {
93 * Setter for Ecliptic Coordinate object
94 * @param lat The ecliptic latitude, measured in radians.
95 * @param lon The ecliptic longitude, measured in radians.
98 void set(double lat
, double lon
) {
104 * Return a string representation of this object
107 UnicodeString
toString() const;
110 * The ecliptic latitude, in radians. This specifies an object's
111 * position north or south of the plane of the ecliptic,
112 * with positive angles representing north.
118 * The ecliptic longitude, in radians.
119 * This specifies an object's position along the ecliptic plane
120 * relative to the "First Point of Aries", which is the Sun's position
121 * in the sky at the Vernal Equinox,
122 * with positive angles representing east.
124 * A bit of trivia: the first point of Aries is currently in the
125 * constellation Pisces, due to the precession of the earth's axis.
132 * Represents the position of an
133 * object in the sky relative to the plane of the earth's equator.
134 * The <i>Right Ascension</i> specifies the position east or west
135 * along the equator, relative to the sun's position at the vernal
136 * equinox. The <i>Declination</i> is the position north or south
137 * of the equatorial plane.
139 * Note that Equatorial objects are immutable and cannot be modified
140 * once they are constructed. This allows them to be passed and returned by
141 * value without worrying about whether other code will modify them.
143 * @see CalendarAstronomer.Ecliptic
144 * @see CalendarAstronomer.Horizon
147 class U_I18N_API Equatorial
: public UMemory
{
150 * Constructs an Equatorial coordinate object.
152 * @param asc The right ascension, measured in radians.
153 * @param dec The declination, measured in radians.
156 Equatorial(double asc
= 0, double dec
= 0)
157 : ascension(asc
), declination(dec
) { }
161 * @param asc The right ascension, measured in radians.
162 * @param dec The declination, measured in radians.
165 void set(double asc
, double dec
) {
171 * Return a string representation of this object, with the
172 * angles measured in degrees.
175 UnicodeString
toString() const;
178 * Return a string representation of this object with the right ascension
179 * measured in hours, minutes, and seconds.
182 //String toHmsString() {
183 //return radToHms(ascension) + "," + radToDms(declination);
187 * The right ascension, in radians.
188 * This is the position east or west along the equator
189 * relative to the sun's position at the vernal equinox,
190 * with positive angles representing East.
196 * The declination, in radians.
197 * This is the position north or south of the equatorial plane,
198 * with positive angles representing north.
205 * Represents the position of an object in the sky relative to
207 * The <i>Altitude</i> represents the object's elevation above the horizon,
208 * with objects below the horizon having a negative altitude.
209 * The <i>Azimuth</i> is the geographic direction of the object from the
210 * observer's position, with 0 representing north. The azimuth increases
211 * clockwise from north.
213 * Note that Horizon objects are immutable and cannot be modified
214 * once they are constructed. This allows them to be passed and returned by
215 * value without worrying about whether other code will modify them.
217 * @see CalendarAstronomer.Ecliptic
218 * @see CalendarAstronomer.Equatorial
221 class U_I18N_API Horizon
: public UMemory
{
224 * Constructs a Horizon coordinate object.
226 * @param alt The altitude, measured in radians above the horizon.
227 * @param azim The azimuth, measured in radians clockwise from north.
230 Horizon(double alt
=0, double azim
=0)
231 : altitude(alt
), azimuth(azim
) { }
234 * Setter for Ecliptic Coordinate object
235 * @param alt The altitude, measured in radians above the horizon.
236 * @param azim The azimuth, measured in radians clockwise from north.
239 void set(double alt
, double azim
) {
245 * Return a string representation of this object, with the
246 * angles measured in degrees.
249 UnicodeString
toString() const;
252 * The object's altitude above the horizon, in radians.
258 * The object's direction, in radians clockwise from north.
265 //-------------------------------------------------------------------------
266 // Assorted private data used for conversions
267 //-------------------------------------------------------------------------
269 // My own copies of these so compilers are more likely to optimize them away
270 static const double PI
;
273 * The average number of solar days from one new moon to the next. This is the time
274 * it takes for the moon to return the same ecliptic longitude as the sun.
275 * It is longer than the sidereal month because the sun's longitude increases
276 * during the year due to the revolution of the earth around the sun.
277 * Approximately 29.53.
279 * @see #SIDEREAL_MONTH
281 * @deprecated ICU 2.4. This class may be removed or modified.
283 static const double SYNODIC_MONTH
;
285 //-------------------------------------------------------------------------
287 //-------------------------------------------------------------------------
290 * Construct a new <code>CalendarAstronomer</code> object that is initialized to
291 * the current date and time.
294 CalendarAstronomer();
297 * Construct a new <code>CalendarAstronomer</code> object that is initialized to
298 * the specified date and time.
301 CalendarAstronomer(UDate d
);
304 * Construct a new <code>CalendarAstronomer</code> object with the given
305 * latitude and longitude. The object's time is set to the current
308 * @param longitude The desired longitude, in <em>degrees</em> east of
309 * the Greenwich meridian.
311 * @param latitude The desired latitude, in <em>degrees</em>. Positive
312 * values signify North, negative South.
314 * @see java.util.Date#getTime()
317 CalendarAstronomer(double longitude
, double latitude
);
323 ~CalendarAstronomer();
325 //-------------------------------------------------------------------------
326 // Time and date getters and setters
327 //-------------------------------------------------------------------------
330 * Set the current date and time of this <code>CalendarAstronomer</code> object. All
331 * astronomical calculations are performed based on this time setting.
333 * @param aTime the date and time, expressed as the number of milliseconds since
334 * 1/1/1970 0:00 GMT (Gregorian).
340 void setTime(UDate aTime
);
344 * Set the current date and time of this <code>CalendarAstronomer</code> object. All
345 * astronomical calculations are performed based on this time setting.
347 * @param aTime the date and time, expressed as the number of milliseconds since
348 * 1/1/1970 0:00 GMT (Gregorian).
353 void setDate(UDate aDate
) { setTime(aDate
); }
356 * Set the current date and time of this <code>CalendarAstronomer</code> object. All
357 * astronomical calculations are performed based on this time setting.
359 * @param jdn the desired time, expressed as a "julian day number",
360 * which is the number of elapsed days since
361 * 1/1/4713 BC (Julian), 12:00 GMT. Note that julian day
362 * numbers start at <em>noon</em>. To get the jdn for
363 * the corresponding midnight, subtract 0.5.
366 * @see #JULIAN_EPOCH_MS
369 void setJulianDay(double jdn
);
372 * Get the current time of this <code>CalendarAstronomer</code> object,
373 * represented as the number of milliseconds since
374 * 1/1/1970 AD 0:00 GMT (Gregorian).
383 * Get the current time of this <code>CalendarAstronomer</code> object,
384 * expressed as a "julian day number", which is the number of elapsed
385 * days since 1/1/4713 BC (Julian), 12:00 GMT.
388 * @see #JULIAN_EPOCH_MS
391 double getJulianDay();
394 * Return this object's time expressed in julian centuries:
395 * the number of centuries after 1/1/1900 AD, 12:00 GMT
400 double getJulianCentury();
403 * Returns the current Greenwich sidereal time, measured in hours
406 double getGreenwichSidereal();
409 double getSiderealOffset();
412 * Returns the current local sidereal time, measured in hours
415 double getLocalSidereal();
418 * Converts local sidereal time to Universal Time.
420 * @param lst The Local Sidereal Time, in hours since sidereal midnight
421 * on this object's current date.
423 * @return The corresponding Universal Time, in milliseconds since
427 double lstToUT(double lst
);
431 * Convert from ecliptic to equatorial coordinates.
433 * @param ecliptic The ecliptic
434 * @param result Fillin result
435 * @return reference to result
437 Equatorial
& eclipticToEquatorial(Equatorial
& result
, const Ecliptic
& ecliptic
);
440 * Convert from ecliptic to equatorial coordinates.
442 * @param eclipLong The ecliptic longitude
443 * @param eclipLat The ecliptic latitude
445 * @return The corresponding point in equatorial coordinates.
448 Equatorial
& eclipticToEquatorial(Equatorial
& result
, double eclipLong
, double eclipLat
);
451 * Convert from ecliptic longitude to equatorial coordinates.
453 * @param eclipLong The ecliptic longitude
455 * @return The corresponding point in equatorial coordinates.
458 Equatorial
& eclipticToEquatorial(Equatorial
& result
, double eclipLong
) ;
463 Horizon
& eclipticToHorizon(Horizon
& result
, double eclipLong
) ;
465 //-------------------------------------------------------------------------
467 //-------------------------------------------------------------------------
470 * Returns sunLongitude which may be adjusted for correctness
471 * based on the time, using a table which only has data covering
472 * gregorian years 1900-2100.
474 * @param theSunLongitude the sunLongitude to be adjusted if necessary
475 * @param theTime the time for which the sunLongitude is to be adjusted
478 static double adjustSunLongitude(double &theSunLongitude
, UDate theTime
);
481 * The longitude of the sun at the time specified by theTime.
482 * This does not result in caching of any of the intermediate computations.
485 static double getSunLongitudeForTime(UDate theTime
);
488 * The longitude of the sun at the time specified by this object.
489 * The longitude is measured in radians along the ecliptic
490 * from the "first point of Aries," the point at which the ecliptic
491 * crosses the earth's equatorial plane at the vernal equinox.
493 * Currently, this method uses an approximation of the two-body Kepler's
494 * equation for the earth and the sun. It does not take into account the
495 * perturbations caused by the other planets, the moon, etc.
498 double getSunLongitude();
501 * TODO Make this public when the entire class is package-private.
503 /*public*/ static void getSunLongitude(double julianDay
, double &longitude
, double &meanAnomaly
);
506 * The position of the sun at this object's current date and time,
507 * in equatorial coordinates.
508 * @param result fillin for the result
511 Equatorial
& getSunPosition(Equatorial
& result
);
515 * Constant representing the vernal equinox.
516 * For use with {@link #getSunTime getSunTime}.
517 * Note: In this case, "vernal" refers to the northern hemisphere's seasons.
520 // static double VERNAL_EQUINOX();
523 * Constant representing the summer solstice.
524 * For use with {@link #getSunTime getSunTime}.
525 * Note: In this case, "summer" refers to the northern hemisphere's seasons.
528 static double SUMMER_SOLSTICE();
531 * Constant representing the autumnal equinox.
532 * For use with {@link #getSunTime getSunTime}.
533 * Note: In this case, "autumn" refers to the northern hemisphere's seasons.
536 // static double AUTUMN_EQUINOX();
539 * Constant representing the winter solstice.
540 * For use with {@link #getSunTime getSunTime}.
541 * Note: In this case, "winter" refers to the northern hemisphere's seasons.
544 static double WINTER_SOLSTICE();
547 * Find the next time at which the sun's ecliptic longitude will have
551 UDate
getSunTime(double desired
, UBool next
);
554 * Returns the time (GMT) of sunrise or sunset on the local date to which
555 * this calendar is currently set.
557 * NOTE: This method only works well if this object is set to a
558 * time near local noon. Because of variations between the local
559 * official time zone and the geographic longitude, the
560 * computation can flop over into an adjacent day if this object
561 * is set to a time near local midnight.
565 UDate
getSunRiseSet(UBool rise
);
567 //-------------------------------------------------------------------------
569 //-------------------------------------------------------------------------
572 * The position of the moon at the time set on this
573 * object, in equatorial coordinates.
575 * @return const reference to internal field of calendar astronomer. Do not use outside of the lifetime of this astronomer.
577 const Equatorial
& getMoonPosition();
580 * The "age" of the moon at the time specified in this object.
581 * This is really the angle between the
582 * current ecliptic longitudes of the sun and the moon,
583 * measured in radians.
591 * Calculate the phase of the moon at the time set in this object.
592 * The returned phase is a <code>double</code> in the range
593 * <code>0 <= phase < 1</code>, interpreted as follows:
596 * <li>0.25: First quarter
597 * <li>0.50: Full moon
598 * <li>0.75: Last quarter
604 double getMoonPhase();
606 class U_I18N_API MoonAge
: public UMemory
{
610 void set(double l
) { value
= l
; }
615 * Constant representing a new moon.
616 * For use with {@link #getMoonTime getMoonTime}
619 static const MoonAge
NEW_MOON();
622 * Constant representing the moon's first quarter.
623 * For use with {@link #getMoonTime getMoonTime}
626 // static const MoonAge FIRST_QUARTER();
629 * Constant representing a full moon.
630 * For use with {@link #getMoonTime getMoonTime}
633 static const MoonAge
FULL_MOON();
636 * Constant representing the moon's last quarter.
637 * For use with {@link #getMoonTime getMoonTime}
640 // static const MoonAge LAST_QUARTER();
643 * Find the next or previous time of a new moon if date is in the
644 * range handled by this function (approx gregorian 1900-2100),
647 * @param theTime the time relative to which the function should find
648 * the next or previous new moon
649 * @param next <tt>true</tt> if the next occurrance of the new moon
650 * is desired, <tt>false</tt> for the previous occurrance.
653 static UDate
getNewMoonTimeInRange(UDate theTime
, UBool next
);
656 * Find the next or previous time at which the Moon's ecliptic
657 * longitude will have the desired value.
659 * @param desired The desired longitude.
660 * @param next <tt>true</tt> if the next occurrance of the phase
661 * is desired, <tt>false</tt> for the previous occurrance.
664 UDate
getMoonTime(double desired
, UBool next
);
665 UDate
getMoonTime(const MoonAge
& desired
, UBool next
);
668 * Returns the time (GMT) of sunrise or sunset on the local date to which
669 * this calendar is currently set.
672 UDate
getMoonRiseSet(UBool rise
);
674 //-------------------------------------------------------------------------
675 // Interpolation methods for finding the time at which a given event occurs
676 //-------------------------------------------------------------------------
679 class AngleFunc
: public UMemory
{
681 virtual double eval(CalendarAstronomer
&) = 0;
682 virtual ~AngleFunc();
684 friend class AngleFunc
;
686 UDate
timeOfAngle(AngleFunc
& func
, double desired
,
687 double periodDays
, double epsilon
, UBool next
);
689 class CoordFunc
: public UMemory
{
691 virtual void eval(Equatorial
& result
, CalendarAstronomer
&) = 0;
692 virtual ~CoordFunc();
694 friend class CoordFunc
;
696 double riseOrSet(CoordFunc
& func
, UBool rise
,
697 double diameter
, double refraction
,
700 //-------------------------------------------------------------------------
701 // Other utility methods
702 //-------------------------------------------------------------------------
706 * Return the obliquity of the ecliptic (the angle between the ecliptic
707 * and the earth's equator) at the current time. This varies due to
708 * the precession of the earth's axis.
710 * @return the obliquity of the ecliptic relative to the equator,
711 * measured in radians.
713 double eclipticObliquity();
715 //-------------------------------------------------------------------------
717 //-------------------------------------------------------------------------
720 * Current time in milliseconds since 1/1/1970 AD
721 * @see java.util.Date#getTime
725 /* These aren't used yet, but they'll be needed for sunset calculations
726 * and equatorial to horizon coordinate conversions
733 // The following fields are used to cache calculated results for improved
734 // performance. These values all depend on the current time setting
735 // of this object, so the clearCache method is provided.
739 double julianCentury
;
741 double meanAnomalySun
;
742 double moonLongitude
;
743 double moonEclipLong
;
744 double meanAnomalyMoon
;
745 double eclipObliquity
;
751 Equatorial moonPosition
;
752 UBool moonPositionSet
;
757 // UDate local(UDate localMillis);
767 * Cache of month -> julian day
770 class CalendarCache
: public UMemory
{
772 static int32_t get(CalendarCache
** cache
, int32_t key
, UErrorCode
&status
);
773 static void put(CalendarCache
** cache
, int32_t key
, int32_t value
, UErrorCode
&status
);
774 virtual ~CalendarCache();
776 CalendarCache(int32_t size
, UErrorCode
& status
);
777 static void createCache(CalendarCache
** cache
, UErrorCode
& status
);