| Date::JD(3pm) | User Contributed Perl Documentation | Date::JD(3pm) |
Date::JD - conversion between flavours of Julian Date
use Date::JD qw(jd_to_mjd mjd_to_cjdnf cjdn_to_rd);
$mjd = jd_to_mjd($jd);
($cjdn, $cjdf) = mjd_to_cjdnf($mjd, $tz);
$rd = cjdn_to_rd($cjdn, $cjdf);
# and 509 other conversion functions
For date and time calculations it is convenient to represent dates by a simple linear count of days, rather than in a particular calendar. This is such a good idea that it has been invented several times. If there were a single such linear count then it would be the obvious data interchange format between calendar modules. With several versions, calendar modules can use such sensible data formats and still have interoperability problems. This module tackles that problem, by performing conversions between different flavours of day count. These day count systems are generically known as "Julian Dates", after the most venerable of them.
Among Julian Date systems there are also some non-trivial differences of concept. There are systems that count only complete days, and those that count fractional days also. There are some that are fixed to Universal Time (time on the prime meridian), and others that are interpreted according to a timezone. Some consider the day to start at noon and others at midnight, which is semantically significant for the complete-day counts. The functions of this module appropriately handle the semantics of all the non-trivial conversions.
The day count systems supported by this module are Julian Date, Reduced Julian Date, Modified Julian Date, Dublin Julian Date, Truncated Julian Date, Chronological Julian Date, Rata Die, and Lilian Date, each in both integral and fractional forms.
In the interests of orthogonality, all flavours of day count come in both integral and fractional varieties. Generally, there is a quantity named "XYZD" ("XYZ Date") which is a real count of days since a particular epoch (an integer plus a fraction) and a corresponding quantity named "XYZDN" ("XYZ Day Number") which is a count of complete days since the same epoch. XYZDN is the integral part of XYZD. There is also a quantity named "XYZDF" ("XYZ Day Fraction") which is a count of fractional days since the XYZDN changed (whether that is noon or midnight). XYZDF is the fractional part of XYZD, in the range [0, 1).
This quantity naming pattern is derived from JD (Julian Date) and JDN (Julian Day Number) which have the described correspondence. Most of the other flavours of day count listed below conventionally come in only one of the two varieties. The "XYZDF" name type is a neologism.
All calendar dates given are in ISO 8601 form (Gregorian calendar with astronomical year numbering). An hour number is appended to each date, separated by a "T"; hour 00 is midnight at the start of the day and hour 12 is noon in the middle of the day. An appended "Z" indicates that the date is to be interpreted in Universal Time (the timezone of the prime meridian), and so is absolute; where any other timezone is to be used then this is explicitly noted.
The interesting differences between these flavours are whether the day starts at noon or at midnight, and whether they are absolute or timezone-relative. Three of the four combinations of these features exist. There is no convention for counting days from timezone-relative noon that the author of this module is aware of.
For more background on these day count systems, <http://en.wikipedia.org/wiki/Julian_Date> is a good starting place.
A day count has meaning only in the context of a particular definition of "day". There are two main flavours of day to consider: solar and conventional.
A solar day is based on the apparent motion of Sol in the Terran sky (and thus on the rotation and orbit of Terra). The rotation of Terra is not constant in time, so this type of day is really a measure of angle, not of time. This is how days have been counted since antiquity, and is still (as of 2006) the basis of civil time. There are two subtypes of solar day: apparent and mean. The apparent solar day is based on the actual observable position of Sol in the sky from day to day, whereas the mean solar day smooths this motion out, in time, over the course of the year. At the sub-second level there are different types of smoothing that can be used (UT1, UT2, et al).
A conventional day is any type of day that is not based on Terran rotation. The astronomical Ephemeris Time, a time scale based on the motion of bodies in the Solar system, has a time unit that it calls "day" which is derived from astronomical observations. The modern relativistic coordinate time scales such as TT have a notional "day" of exactly 86400 SI seconds. The atomic time scale TAI also has a "day" which is as close to 86400 SI seconds as can be achieved. All of these "days" are roughly the duration of one Sol-relative rotation of Terra during the early nineteenth century, but are not otherwise related to planetary rotation.
Each of the day count scales handled by this module can be used with any of these types of day. For a day number to be meaningful it is necessary to be aware of which kind of day it is counting. Conversion between the different types of day is out of scope for this module. (See Time::UTC for TAI/UTC conversion.)
Day counts in this API may be native Perl numbers or "Math::BigRat" objects. Both are acceptable for all parameters, in any combination. In all conversion functions, the result is of the same type as the input, provided that the inputs are of consistent type. If native Perl numbers are supplied then the conversion is subject to floating point rounding, and possible overflow if the numbers are extremely large. The use of "Math::BigRat" is recommended to avoid these problems. With "Math::BigRat" the results are exact.
There are conversion functions between all pairs of day count systems. This is a total of 512 conversion functions (including 32 identity functions).
When converting between timezone-relative counts (CJD, RD, LD) and absolute counts (JD, RJD, MJD, DJD, TJD), the timezone that is being used must be specified. It is given in a ZONE argument as a fractional number of days offset from Universal Time. For example, US Central Standard Time, 6 hours behind UT, would be specified as a ZONE argument of -0.25. Beware of floating point rounding when the offset does not have a terminating binary representation (e.g., US Eastern Standard Time at -5/24); use of "Math::BigRat" avoids this problem. A ZONE parameter is not used when converting between absolute day counts (e.g., between JD and MJD) or between timezone-relative counts (e.g., between CJD and LD).
These functions are not recommended, because the context-sensitive return convention makes their use error-prone. They are retained for backward compatibility. You should prefer to use the more specific functions shown above.
If converting between systems that delimit days identically (e.g., between JD and RJD), the day fraction makes no difference to the integral day number of the output, and may be omitted from the input. If the day fraction is extracted from the output when it wasn't supplied as input, it will default to zero.
These functions are not recommended, because the context-sensitive return convention makes their use error-prone. They are retained for backward compatibility. You should prefer to use the more specific functions shown above.
Date::ISO8601, Date::MSD, DateTime, Time::UTC
Andrew Main (Zefram) <zefram@fysh.org>
Copyright (C) 2006, 2007, 2009, 2010, 2011, 2017 Andrew Main (Zefram) <zefram@fysh.org>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
| 2022-10-13 | perl v5.34.0 |