]> git.saurik.com Git - apple/icu.git/blob - icuSources/i18n/astro.h
ICU-66108.tar.gz
[apple/icu.git] / icuSources / i18n / astro.h
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
8 */
9
10 #ifndef ASTRO_H
11 #define ASTRO_H
12
13 #include "unicode/utypes.h"
14
15 #if !UCONFIG_NO_FORMATTING
16
17 #include "gregoimp.h" // for Math
18 #include "unicode/unistr.h"
19
20 U_NAMESPACE_BEGIN
21
22 /**
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.
28 * <p>
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.
36 * <p>
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
40 * in the book
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.
46 * <p>
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}.
51 *
52 * @author Laura Werner
53 * @author Alan Liu
54 * @internal
55 */
56 class U_I18N_API CalendarAstronomer : public UMemory {
57 public:
58 // some classes
59
60 public:
61 /**
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.
69 * <p>
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.
73 *
74 * @see CalendarAstronomer.Equatorial
75 * @see CalendarAstronomer.Horizon
76 * @internal
77 */
78 class U_I18N_API Ecliptic : public UMemory {
79 public:
80 /**
81 * Constructs an Ecliptic coordinate object.
82 * <p>
83 * @param lat The ecliptic latitude, measured in radians.
84 * @param lon The ecliptic longitude, measured in radians.
85 * @internal
86 */
87 Ecliptic(double lat = 0, double lon = 0) {
88 latitude = lat;
89 longitude = lon;
90 }
91
92 /**
93 * Setter for Ecliptic Coordinate object
94 * @param lat The ecliptic latitude, measured in radians.
95 * @param lon The ecliptic longitude, measured in radians.
96 * @internal
97 */
98 void set(double lat, double lon) {
99 latitude = lat;
100 longitude = lon;
101 }
102
103 /**
104 * Return a string representation of this object
105 * @internal
106 */
107 UnicodeString toString() const;
108
109 /**
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.
113 * @internal
114 */
115 double latitude;
116
117 /**
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.
123 * <p>
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.
126 * @internal
127 */
128 double longitude;
129 };
130
131 /**
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.
138 * <p>
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.
142 *
143 * @see CalendarAstronomer.Ecliptic
144 * @see CalendarAstronomer.Horizon
145 * @internal
146 */
147 class U_I18N_API Equatorial : public UMemory {
148 public:
149 /**
150 * Constructs an Equatorial coordinate object.
151 * <p>
152 * @param asc The right ascension, measured in radians.
153 * @param dec The declination, measured in radians.
154 * @internal
155 */
156 Equatorial(double asc = 0, double dec = 0)
157 : ascension(asc), declination(dec) { }
158
159 /**
160 * Setter
161 * @param asc The right ascension, measured in radians.
162 * @param dec The declination, measured in radians.
163 * @internal
164 */
165 void set(double asc, double dec) {
166 ascension = asc;
167 declination = dec;
168 }
169
170 /**
171 * Return a string representation of this object, with the
172 * angles measured in degrees.
173 * @internal
174 */
175 UnicodeString toString() const;
176
177 /**
178 * Return a string representation of this object with the right ascension
179 * measured in hours, minutes, and seconds.
180 * @internal
181 */
182 //String toHmsString() {
183 //return radToHms(ascension) + "," + radToDms(declination);
184 //}
185
186 /**
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.
191 * @internal
192 */
193 double ascension;
194
195 /**
196 * The declination, in radians.
197 * This is the position north or south of the equatorial plane,
198 * with positive angles representing north.
199 * @internal
200 */
201 double declination;
202 };
203
204 /**
205 * Represents the position of an object in the sky relative to
206 * the local horizon.
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.
212 * <p>
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.
216 *
217 * @see CalendarAstronomer.Ecliptic
218 * @see CalendarAstronomer.Equatorial
219 * @internal
220 */
221 class U_I18N_API Horizon : public UMemory {
222 public:
223 /**
224 * Constructs a Horizon coordinate object.
225 * <p>
226 * @param alt The altitude, measured in radians above the horizon.
227 * @param azim The azimuth, measured in radians clockwise from north.
228 * @internal
229 */
230 Horizon(double alt=0, double azim=0)
231 : altitude(alt), azimuth(azim) { }
232
233 /**
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.
237 * @internal
238 */
239 void set(double alt, double azim) {
240 altitude = alt;
241 azimuth = azim;
242 }
243
244 /**
245 * Return a string representation of this object, with the
246 * angles measured in degrees.
247 * @internal
248 */
249 UnicodeString toString() const;
250
251 /**
252 * The object's altitude above the horizon, in radians.
253 * @internal
254 */
255 double altitude;
256
257 /**
258 * The object's direction, in radians clockwise from north.
259 * @internal
260 */
261 double azimuth;
262 };
263
264 public:
265 //-------------------------------------------------------------------------
266 // Assorted private data used for conversions
267 //-------------------------------------------------------------------------
268
269 // My own copies of these so compilers are more likely to optimize them away
270 static const double PI;
271
272 /**
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.
278 *
279 * @see #SIDEREAL_MONTH
280 * @internal
281 * @deprecated ICU 2.4. This class may be removed or modified.
282 */
283 static const double SYNODIC_MONTH;
284
285 //-------------------------------------------------------------------------
286 // Constructors
287 //-------------------------------------------------------------------------
288
289 /**
290 * Construct a new <code>CalendarAstronomer</code> object that is initialized to
291 * the current date and time.
292 * @internal
293 */
294 CalendarAstronomer();
295
296 /**
297 * Construct a new <code>CalendarAstronomer</code> object that is initialized to
298 * the specified date and time.
299 * @internal
300 */
301 CalendarAstronomer(UDate d);
302
303 /**
304 * Construct a new <code>CalendarAstronomer</code> object with the given
305 * latitude and longitude. The object's time is set to the current
306 * date and time.
307 * <p>
308 * @param longitude The desired longitude, in <em>degrees</em> east of
309 * the Greenwich meridian.
310 *
311 * @param latitude The desired latitude, in <em>degrees</em>. Positive
312 * values signify North, negative South.
313 *
314 * @see java.util.Date#getTime()
315 * @internal
316 */
317 CalendarAstronomer(double longitude, double latitude);
318
319 /**
320 * Destructor
321 * @internal
322 */
323 ~CalendarAstronomer();
324
325 //-------------------------------------------------------------------------
326 // Time and date getters and setters
327 //-------------------------------------------------------------------------
328
329 /**
330 * Set the current date and time of this <code>CalendarAstronomer</code> object. All
331 * astronomical calculations are performed based on this time setting.
332 *
333 * @param aTime the date and time, expressed as the number of milliseconds since
334 * 1/1/1970 0:00 GMT (Gregorian).
335 *
336 * @see #setDate
337 * @see #getTime
338 * @internal
339 */
340 void setTime(UDate aTime);
341
342
343 /**
344 * Set the current date and time of this <code>CalendarAstronomer</code> object. All
345 * astronomical calculations are performed based on this time setting.
346 *
347 * @param aTime the date and time, expressed as the number of milliseconds since
348 * 1/1/1970 0:00 GMT (Gregorian).
349 *
350 * @see #getTime
351 * @internal
352 */
353 void setDate(UDate aDate) { setTime(aDate); }
354
355 /**
356 * Set the current date and time of this <code>CalendarAstronomer</code> object. All
357 * astronomical calculations are performed based on this time setting.
358 *
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.
364 *
365 * @see #getJulianDay
366 * @see #JULIAN_EPOCH_MS
367 * @internal
368 */
369 void setJulianDay(double jdn);
370
371 /**
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).
375 *
376 * @see #setTime
377 * @see #getDate
378 * @internal
379 */
380 UDate getTime();
381
382 /**
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.
386 *
387 * @see #setJulianDay
388 * @see #JULIAN_EPOCH_MS
389 * @internal
390 */
391 double getJulianDay();
392
393 /**
394 * Return this object's time expressed in julian centuries:
395 * the number of centuries after 1/1/1900 AD, 12:00 GMT
396 *
397 * @see #getJulianDay
398 * @internal
399 */
400 double getJulianCentury();
401
402 /**
403 * Returns the current Greenwich sidereal time, measured in hours
404 * @internal
405 */
406 double getGreenwichSidereal();
407
408 private:
409 double getSiderealOffset();
410 public:
411 /**
412 * Returns the current local sidereal time, measured in hours
413 * @internal
414 */
415 double getLocalSidereal();
416
417 /**
418 * Converts local sidereal time to Universal Time.
419 *
420 * @param lst The Local Sidereal Time, in hours since sidereal midnight
421 * on this object's current date.
422 *
423 * @return The corresponding Universal Time, in milliseconds since
424 * 1 Jan 1970, GMT.
425 */
426 //private:
427 double lstToUT(double lst);
428
429 /**
430 *
431 * Convert from ecliptic to equatorial coordinates.
432 *
433 * @param ecliptic The ecliptic
434 * @param result Fillin result
435 * @return reference to result
436 */
437 Equatorial& eclipticToEquatorial(Equatorial& result, const Ecliptic& ecliptic);
438
439 /**
440 * Convert from ecliptic to equatorial coordinates.
441 *
442 * @param eclipLong The ecliptic longitude
443 * @param eclipLat The ecliptic latitude
444 *
445 * @return The corresponding point in equatorial coordinates.
446 * @internal
447 */
448 Equatorial& eclipticToEquatorial(Equatorial& result, double eclipLong, double eclipLat);
449
450 /**
451 * Convert from ecliptic longitude to equatorial coordinates.
452 *
453 * @param eclipLong The ecliptic longitude
454 *
455 * @return The corresponding point in equatorial coordinates.
456 * @internal
457 */
458 Equatorial& eclipticToEquatorial(Equatorial& result, double eclipLong) ;
459
460 /**
461 * @internal
462 */
463 Horizon& eclipticToHorizon(Horizon& result, double eclipLong) ;
464
465 //-------------------------------------------------------------------------
466 // The Sun
467 //-------------------------------------------------------------------------
468
469 /**
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.
473 * <p>
474 * @param theSunLongitude the sunLongitude to be adjusted if necessary
475 * @param theTime the time for which the sunLongitude is to be adjusted
476 * @internal
477 */
478 static double adjustSunLongitude(double &theSunLongitude, UDate theTime);
479
480 /**
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.
483 * @internal
484 */
485 static double getSunLongitudeForTime(UDate theTime);
486
487 /**
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.
492 * <p>
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.
496 * @internal
497 */
498 double getSunLongitude();
499
500 /**
501 * TODO Make this public when the entire class is package-private.
502 */
503 /*public*/ static void getSunLongitude(double julianDay, double &longitude, double &meanAnomaly);
504
505 /**
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
509 * @internal
510 */
511 Equatorial& getSunPosition(Equatorial& result);
512
513 public:
514 /**
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.
518 * @internal
519 */
520 // static double VERNAL_EQUINOX();
521
522 /**
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.
526 * @internal
527 */
528 static double SUMMER_SOLSTICE();
529
530 /**
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.
534 * @internal
535 */
536 // static double AUTUMN_EQUINOX();
537
538 /**
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.
542 * @internal
543 */
544 static double WINTER_SOLSTICE();
545
546 /**
547 * Find the next time at which the sun's ecliptic longitude will have
548 * the desired value.
549 * @internal
550 */
551 UDate getSunTime(double desired, UBool next);
552
553 /**
554 * Returns the time (GMT) of sunrise or sunset on the local date to which
555 * this calendar is currently set.
556 *
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.
562 *
563 * @internal
564 */
565 UDate getSunRiseSet(UBool rise);
566
567 //-------------------------------------------------------------------------
568 // The Moon
569 //-------------------------------------------------------------------------
570
571 /**
572 * The position of the moon at the time set on this
573 * object, in equatorial coordinates.
574 * @internal
575 * @return const reference to internal field of calendar astronomer. Do not use outside of the lifetime of this astronomer.
576 */
577 const Equatorial& getMoonPosition();
578
579 /**
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.
584 *
585 * @see #getMoonPhase
586 * @internal
587 */
588 double getMoonAge();
589
590 /**
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:
594 * <ul>
595 * <li>0.00: New moon
596 * <li>0.25: First quarter
597 * <li>0.50: Full moon
598 * <li>0.75: Last quarter
599 * </ul>
600 *
601 * @see #getMoonAge
602 * @internal
603 */
604 double getMoonPhase();
605
606 class U_I18N_API MoonAge : public UMemory {
607 public:
608 MoonAge(double l)
609 : value(l) { }
610 void set(double l) { value = l; }
611 double value;
612 };
613
614 /**
615 * Constant representing a new moon.
616 * For use with {@link #getMoonTime getMoonTime}
617 * @internal
618 */
619 static const MoonAge NEW_MOON();
620
621 /**
622 * Constant representing the moon's first quarter.
623 * For use with {@link #getMoonTime getMoonTime}
624 * @internal
625 */
626 // static const MoonAge FIRST_QUARTER();
627
628 /**
629 * Constant representing a full moon.
630 * For use with {@link #getMoonTime getMoonTime}
631 * @internal
632 */
633 static const MoonAge FULL_MOON();
634
635 /**
636 * Constant representing the moon's last quarter.
637 * For use with {@link #getMoonTime getMoonTime}
638 * @internal
639 */
640 // static const MoonAge LAST_QUARTER();
641
642 /**
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),
645 * else return 0.
646 * <p>
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.
651 * @internal
652 */
653 static UDate getNewMoonTimeInRange(UDate theTime, UBool next);
654
655 /**
656 * Find the next or previous time at which the Moon's ecliptic
657 * longitude will have the desired value.
658 * <p>
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.
662 * @internal
663 */
664 UDate getMoonTime(double desired, UBool next);
665 UDate getMoonTime(const MoonAge& desired, UBool next);
666
667 /**
668 * Returns the time (GMT) of sunrise or sunset on the local date to which
669 * this calendar is currently set.
670 * @internal
671 */
672 UDate getMoonRiseSet(UBool rise);
673
674 //-------------------------------------------------------------------------
675 // Interpolation methods for finding the time at which a given event occurs
676 //-------------------------------------------------------------------------
677
678 // private
679 class AngleFunc : public UMemory {
680 public:
681 virtual double eval(CalendarAstronomer&) = 0;
682 virtual ~AngleFunc();
683 };
684 friend class AngleFunc;
685
686 UDate timeOfAngle(AngleFunc& func, double desired,
687 double periodDays, double epsilon, UBool next);
688
689 class CoordFunc : public UMemory {
690 public:
691 virtual void eval(Equatorial& result, CalendarAstronomer&) = 0;
692 virtual ~CoordFunc();
693 };
694 friend class CoordFunc;
695
696 double riseOrSet(CoordFunc& func, UBool rise,
697 double diameter, double refraction,
698 double epsilon);
699
700 //-------------------------------------------------------------------------
701 // Other utility methods
702 //-------------------------------------------------------------------------
703 private:
704
705 /**
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.
709 *
710 * @return the obliquity of the ecliptic relative to the equator,
711 * measured in radians.
712 */
713 double eclipticObliquity();
714
715 //-------------------------------------------------------------------------
716 // Private data
717 //-------------------------------------------------------------------------
718 private:
719 /**
720 * Current time in milliseconds since 1/1/1970 AD
721 * @see java.util.Date#getTime
722 */
723 UDate fTime;
724
725 /* These aren't used yet, but they'll be needed for sunset calculations
726 * and equatorial to horizon coordinate conversions
727 */
728 double fLongitude;
729 double fLatitude;
730 double fGmtOffset;
731
732 //
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.
736 //
737
738 double julianDay;
739 double julianCentury;
740 double sunLongitude;
741 double meanAnomalySun;
742 double moonLongitude;
743 double moonEclipLong;
744 double meanAnomalyMoon;
745 double eclipObliquity;
746 double siderealT0;
747 double siderealTime;
748
749 void clearCache();
750
751 Equatorial moonPosition;
752 UBool moonPositionSet;
753
754 /**
755 * @internal
756 */
757 // UDate local(UDate localMillis);
758 };
759
760 U_NAMESPACE_END
761
762 struct UHashtable;
763
764 U_NAMESPACE_BEGIN
765
766 /**
767 * Cache of month -> julian day
768 * @internal
769 */
770 class CalendarCache : public UMemory {
771 public:
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();
775 private:
776 CalendarCache(int32_t size, UErrorCode& status);
777 static void createCache(CalendarCache** cache, UErrorCode& status);
778 /**
779 * not implemented
780 */
781 CalendarCache();
782 UHashtable *fTable;
783 };
784
785 U_NAMESPACE_END
786
787 #endif
788 #endif