PCL
|
An instant in any timescale. More...
#include <TimePoint.h>
Public Member Functions | |
TimePoint ()=default | |
TimePoint (const FileTime &fileTime) | |
TimePoint (const IsoString &dateTime) | |
TimePoint (const String &dateTime) | |
TimePoint (const TimePoint &)=default | |
TimePoint (double jd) | |
TimePoint (double jd1, double jd2) | |
TimePoint (int year, int month, double days) | |
TimePoint (int year, int month, int day, double dayFraction) | |
TimePoint (int year, int month, int day, int hour, int minute, double seconds) | |
TimePoint (time_t time) | |
constexpr double | CenturiesSince (const TimePoint &t) const |
constexpr double | CenturiesSinceJ2000 () const |
constexpr double | CenturiesSinceReferenceEpoch () const |
constexpr double | CenturiesSinceUNIXEpoch () const |
int | Day () const |
double | DayFraction () const |
constexpr double | DaysSince (const TimePoint &t) const |
constexpr double | DaysSinceJ2000 () const |
constexpr double | DaysSinceReferenceEpoch () const |
constexpr double | DaysSinceUNIXEpoch () const |
double | DeltaAT () const |
double | DeltaT () const |
void | GetCalendarTime (int &year, int &month, int &day) const |
void | GetCalendarTime (int &year, int &month, int &day, double &dayf) const |
void | GetCalendarTime (int &year, int &month, int &day, int &hour, int &minute, double &seconds) const |
constexpr bool | IsValid () const |
constexpr double | JD () const |
constexpr double | JDF () const |
constexpr int | JDI () const |
TimePoint | LocalTimeToUTC () const |
constexpr double | MillisecondsSinceUNIXEpoch () const |
constexpr double | MJD () const |
int | Month () const |
operator IsoString () const | |
operator String () const | |
TimePoint & | operator+= (double days) |
TimePoint & | operator-= (double days) |
TimePoint & | operator= (const TimePoint &)=default |
constexpr double | SecondsSince (const TimePoint &t) const |
constexpr double | SecondsSinceJ2000 () const |
constexpr double | SecondsSinceReferenceEpoch () const |
constexpr double | SecondsSinceUNIXEpoch () const |
double | SystemOffsetFromUTC () const |
IsoString | ToIsoString (const ISO8601ConversionOptions &options=ISO8601ConversionOptions(), double tz=0) const |
IsoString | ToIsoString (const IsoString &format) const |
IsoString | ToIsoString (unsigned timeItems, unsigned precision=3, double tz=0, bool timeZone=true, bool zuluTime=true) const |
String | ToString (const ISO8601ConversionOptions &options=ISO8601ConversionOptions(), double tz=0) const |
String | ToString (const String &format) const |
String | ToString (unsigned timeItems, unsigned precision=3, double tz=0, bool timeZone=true, bool zuluTime=true) const |
TimePoint | UTCToLocalTime () const |
int | Year () const |
constexpr double | YearsSince (const TimePoint &t) const |
constexpr double | YearsSinceJ2000 () const |
constexpr double | YearsSinceReferenceEpoch () const |
constexpr double | YearsSinceUNIXEpoch () const |
Static Public Member Functions | |
static TimePoint | B1950 () |
static void | DisableDeltaTExtrapolation (bool disable=true) |
static void | EnableDeltaTExtrapolation (bool enable=true) |
static TimePoint | FromString (const IsoString &dateTime) |
static TimePoint | FromString (const String &dateTime) |
static TimePoint | FromString (double &tz, const IsoString &dateTime) |
static TimePoint | FromString (double &tz, const String &dateTime) |
static bool | IsDeltaTExtrapolationEnabled () |
static TimePoint | J2000 () |
static TimePoint | J2100 () |
static TimePoint | Now () |
static TimePoint | ReferenceEpoch () |
static bool | TryFromString (TimePoint &t, const IsoString &dateTime) |
static bool | TryFromString (TimePoint &t, const String &dateTime) |
static bool | TryFromString (TimePoint &t, double &tz, const IsoString &dateTime) |
static bool | TryFromString (TimePoint &t, double &tz, const String &dateTime) |
static TimePoint | UNIXEpoch () |
TimePoint represents an instant, an infinitesimal point in time, in any timescale. The internal representation of time consists of the separate integer and fractional components of a Julian date. This guarantees a numerical resolution better than one nanosecond, as well as fast time relational and arithmetic operations.
Definition at line 102 of file TimePoint.h.
|
default |
Default constructor. Yields an invalid TimePoint object that cannot be used until properly initialized.
|
inline |
Constructs a TimePoint object for a given instant represented as a Julian date.
Definition at line 116 of file TimePoint.h.
|
inline |
Constructs a TimePoint object from two separate Julian date components, jd1 and jd2, where the resulting JD is jd1 + jd2.
Specifying a JD in two parts greatly improves the accuracy of time representation, by increasing the effective bit length used to store time points. To maximize time resolution and calculation efficiency, TimePoint normalizes its internal representation as the separate integer and fractional components of a JD. This guarantees a numerical resolution better than one nanosecond.
Definition at line 133 of file TimePoint.h.
|
inline |
Constructs a TimePoint object from separate date components.
Definition at line 143 of file TimePoint.h.
References pcl::CalendarTimeToJD(), pcl::Frac(), and pcl::TruncInt().
|
inline |
Constructs a TimePoint object from separate date components plus a day fraction.
Definition at line 152 of file TimePoint.h.
References pcl::CalendarTimeToJD().
|
inline |
Constructs a TimePoint object from separate date and time components.
Definition at line 160 of file TimePoint.h.
References pcl::CalendarTimeToJD().
|
inline |
Constructs a TimePoint object from an ISO 8601 extended date/time representation specified as an 8-bit ISO/IEC-8859-1 string.
If the source representation specifies a nonzero time zone, it will be subtracted from the time point represented by this object. In other words, the newly constructed object will always transport a time point in the UTC timescale.
Definition at line 174 of file TimePoint.h.
References pcl::CalendarTimeToJD(), and pcl::IsoString::ParseISO8601DateTime().
|
inline |
Constructs a TimePoint object from an ISO 8601 extended date/time representation specified as a UTF-16 string.
If the source representation specifies a nonzero time zone, it will be subtracted from the time point represented by this object. In other words, the newly constructed object will always transport a time point in the UTC timescale.
Definition at line 191 of file TimePoint.h.
References pcl::CalendarTimeToJD(), and pcl::String::ParseISO8601DateTime().
pcl::TimePoint::TimePoint | ( | time_t | time | ) |
Constructs a TimePoint object from a time_t value. The specified time value will be interpreted as UTC.
pcl::TimePoint::TimePoint | ( | const FileTime & | fileTime | ) |
|
default |
Copy constructor.
|
inlinestatic |
Returns a TimePoint object corresponding to the B1950.0 epoch, namely JD 2433282.42345905, corresponding to 1949 December 31.92345905.
Definition at line 917 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in Julian centuries (36525 days) elapsed since the specified time point t.
Definition at line 714 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in Julian centuries (36525 days) elapsed since the standard J2000 epoch (JD 2451545.0 = 2000 January 1.5).
Definition at line 788 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in Julian centuries (36525 days) elapsed since the reference epoch. Currently this function is equivalent to CenturiesSinceJ2000().
Definition at line 752 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in Julian centuries (36525 days) elapsed since the standard UNIX epoch (JD 2440587.5 = 1970 January 1.0).
Definition at line 824 of file TimePoint.h.
|
inline |
Returns the day component of this time point in the range [1,31].
Definition at line 331 of file TimePoint.h.
References pcl::JDToCalendarTime().
|
inline |
Returns the day fraction component of this time point in the range [0,1).
Definition at line 341 of file TimePoint.h.
References pcl::JDToCalendarTime().
|
inlineconstexpr |
Returns the time interval in days elapsed since the specified time point t.
Definition at line 696 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in days elapsed since the standard J2000 epoch (JD 2451545.0 = 2000 January 1.5).
Definition at line 770 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in days elapsed since the reference epoch. Currently this function is equivalent to DaysSinceJ2000().
Definition at line 732 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in days elapsed since the standard UNIX epoch (JD 2440587.5 = 1970 January 1.0).
Definition at line 806 of file TimePoint.h.
double pcl::TimePoint::DeltaAT | ( | ) | const |
Returns the value of Delta AT, or the difference TAI-UTC, corresponding to this time point, which is assumed to represent an instant in the UTC timescale.
If possible, this member function returns an interpolated value from the global Delta AT database, which will be loaded and parsed upon the first call to this function as a thread-safe procedure. See EphemerisFile::DeltaATDataFilePath() and EphemerisFile::OverrideDeltaATDataFilePath() for more information.
UTC does not exist before 1960, so calling this function for a TimePoint object before that year is a conceptual error. For convenience, zero is returned in such a case instead of throwing an exception.
The returned value is the difference TAI-UTC in seconds.
double pcl::TimePoint::DeltaT | ( | ) | const |
Returns the value of Delta T, or the difference TT-UT1, corresponding to this time point.
If possible, this member function returns an interpolated value from the global Delta T database, which will be loaded and parsed upon the first call to this function as a thread-safe procedure. See EphemerisFile::DeltaTDataFilePath() and EphemerisFile::OverrideDeltaTDataFilePath() for more information.
Otherwise, if this time point falls outside the Delta T database time span, the behavior of this function depends on whether Delta T extrapolation is currently enabled. If extrapolation is enabled, this function will use the polynomial expressions for Delta T included in Five Millennium Canon of Solar Eclipses, by Fred Espenak and Jean Meeus (NASA/TP–2006–214141, Revision 1.0, 2007). If extrapolation of Delta T values is disabled, this function will return the value for the closest time point available in the global Delta T database. Delta T extrapolation is disabled by default.
The returned value is the difference TT-UT1 in seconds.
|
inlinestatic |
Disables extrapolation of Delta T values.
See DeltaT() for information on Delta T extrapolation.
Definition at line 646 of file TimePoint.h.
|
static |
Enables extrapolation of Delta T values.
See DeltaT() for information on Delta T extrapolation.
Returns a TimePoint object constructed from an ISO 8601 extended date/time representation specified as an 8-bit ISO/IEC-8859-1 string.
If the source representation specifies a nonzero time zone, it will be subtracted from the time point constructed by this function. In other words, the newly constructed object will always transport a time point in the UTC timescale without offset.
Definition at line 995 of file TimePoint.h.
Returns a TimePoint object constructed from an ISO 8601 extended date/time representation specified as a UTF-16 string.
If the source representation specifies a nonzero time zone, it will be subtracted from the time point constructed by this function. In other words, the newly constructed object will always transport a time point in the UTC timescale without offset.
Definition at line 1012 of file TimePoint.h.
|
inlinestatic |
Returns a TimePoint object constructed from an ISO 8601 extended date/time representation specified as an 8-bit ISO/IEC-8859-1 string. If successful, stores the evaluated time zone offset, in hours, in the specified variable tz. Otherwise this function throws the appropriate Error exception.
If the source representation specifies a nonzero time zone, it will be subtracted from the time point constructed by this function. In other words, the newly constructed object will always transport a time point in the UTC timescale without offset.
Definition at line 952 of file TimePoint.h.
References pcl::IsoString::ParseISO8601DateTime().
Returns a TimePoint object constructed from an ISO 8601 extended date/time representation specified as a UTF-16 string. If successful, stores the evaluated time zone offset, in hours, in the specified variable tz. Otherwise this function throws the appropriate Error exception.
If the source representation specifies a nonzero time zone, it will be subtracted from the time point constructed by this function. In other words, the newly constructed object will always transport a time point in the UTC timescale without offset.
Definition at line 975 of file TimePoint.h.
References pcl::String::ParseISO8601DateTime().
|
inline |
Extracts the individual date components.
[out] | year | Reference to a variable that will receive the year component of this time point. |
[out] | month | Reference to a variable that will receive the month component of this time point, in the range [1,12]. |
[out] | day | Reference to a variable that will receive the day component of this time point, in the range [1,31]. |
Definition at line 248 of file TimePoint.h.
References pcl::JDToCalendarTime().
|
inline |
Extracts the individual date and day fraction components.
[out] | year | Reference to a variable that will receive the year component of this time point. |
[out] | month | Reference to a variable that will receive the month component of this time point, in the range [1,12]. |
[out] | day | Reference to a variable that will receive the day component of this time point, in the range [1,31]. |
[out] | dayf | Reference to a variable that will receive the day fraction component of this time point, in the range [0,1). |
Definition at line 270 of file TimePoint.h.
References pcl::JDToCalendarTime().
|
inline |
Extracts the individual date and time components.
[out] | year | Reference to a variable that will receive the year component of this time point. |
[out] | month | Reference to a variable that will receive the month component of this time point, in the range [1,12]. |
[out] | day | Reference to a variable that will receive the day component of this time point, in the range [1,31]. |
[out] | hour | Reference to a variable that will receive the hour component of this time point, in the range [0,23]. |
[out] | minute | Reference to a variable that will receive the minute component of this time point, in the range [0,59]. |
[out] | seconds | Reference to a variable that will receive the seconds component of this time point, in the range [0,60). |
Definition at line 297 of file TimePoint.h.
References pcl::Frac(), pcl::JDToCalendarTime(), and pcl::TruncInt().
|
static |
Returns true iff extrapolation of Delta T values is currently enabled for the TimePoint class.
Delta T extrapolation is disabled by default. See DeltaT() for more information.
|
inlineconstexpr |
Returns true iff this is a valid TimePoint instance. An invalid TimePoint does not represent a valid time point, generates empy string representations, and cannot be used until properly initialized.
Definition at line 231 of file TimePoint.h.
Referenced by pcl::operator<().
|
inlinestatic |
Returns a TimePoint object corresponding to the standard J2000 epoch, namely JD 2451545.0, corresponding to the midday of 2000 January 1.
Definition at line 893 of file TimePoint.h.
|
inlinestatic |
Returns a TimePoint object corresponding to the standard J2100 epoch, namely JD 2488070.0, corresponding to the midday of 2100 January 1.
Definition at line 905 of file TimePoint.h.
|
inlineconstexpr |
Returns the Julian date corresponding to this time point.
The time point representation returned by this member function only has millisecond resolution. For higher resolution time point representations up to one nanosecond, use the separate integer and fractional components given by JDI() and JDF().
If this is an invalid TimePoint (for example, a default constructed instance), the value returned by this function is meaningless as a Julian date.
Definition at line 583 of file TimePoint.h.
Referenced by pcl::operator<(), and pcl::operator==().
|
inlineconstexpr |
Returns the fractional part of the Julian date corresponding to this time point.
Definition at line 566 of file TimePoint.h.
Referenced by pcl::JPLEphemeris::ComputeState(), pcl::operator-(), pcl::operator<(), and pcl::operator==().
|
inlineconstexpr |
Returns the integer part of the Julian date (also referred to as Julian day number) corresponding to this time point.
Definition at line 557 of file TimePoint.h.
Referenced by pcl::JPLEphemeris::ComputeState(), pcl::operator-(), pcl::operator<(), and pcl::operator==().
|
inline |
Returns this time point represented as UTC, assuming that this object represents a time point in Local Standard Time (LST).
Definition at line 868 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in milliseconds elapsed since the standard UNIX epoch (JD 2440587.5 = 1970 January 1.0).
Definition at line 842 of file TimePoint.h.
|
inlineconstexpr |
Returns the modified Julian date (MJD) corresponding to this time point.
This function returns JD() - 2400000.5. Refer to the JD() member function for more information.
Definition at line 594 of file TimePoint.h.
|
inline |
Returns the month component of this time point in the range [1,12].
Definition at line 321 of file TimePoint.h.
References pcl::JDToCalendarTime().
|
static |
Returns a TimePoint object corresponding to the current date and time in the UTC timescale.
Referenced by pcl::FileDataCacheItem::DaysSinceLastUsed().
|
inlineexplicit |
IsoString conversion operator. Equivalent to ToIsoString().
Definition at line 548 of file TimePoint.h.
|
inlineexplicit |
String conversion operator. Equivalent to ToString().
Definition at line 540 of file TimePoint.h.
|
inline |
Adds the specified number of days to this time point. Returns a reference to this object.
Definition at line 674 of file TimePoint.h.
|
inline |
Subtracts the specified number of days from this time point. Returns a reference to this object.
Definition at line 685 of file TimePoint.h.
Copy assignment operator. Returns a reference to this object.
|
inlinestatic |
Returns a TimePoint object corresponding to the reference epoch. Currently this function returns J2000(), that is JD 2451545.0, corresponding to the midday of 2000 January 1.
Definition at line 884 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in seconds elapsed since the specified time point t.
Definition at line 723 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in seconds elapsed since the standard J2000 epoch (JD 2451545.0 = 2000 January 1.5).
Definition at line 797 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in seconds elapsed since the reference epoch. Currently this function is equivalent to SecondsSinceJ2000().
Definition at line 761 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in seconds elapsed since the standard UNIX epoch (JD 2440587.5 = 1970 January 1.0).
Definition at line 833 of file TimePoint.h.
double pcl::TimePoint::SystemOffsetFromUTC | ( | ) | const |
Returns the UTC offset for this time point on the host machine, or the difference Local Standard Time (LST) minus Universal Coordinated Time (UTC), in hours, at the date represented by this object. This function takes into account daylight saving time when applicable.
|
inline |
Returns an ISO 8601 extended date/time representation of this time point as an 8-bit ISO/IEC-8859-1 string.
options | Optional settings to control the representation of date and time in ISO 8601 extended format. |
tz | Time zone offset in hours. The default value is zero. |
If this is an invalid TimePoint (for example, a default constructed instance), this function returns an empty string.
Definition at line 412 of file TimePoint.h.
Returns a custom representation of this time point as an 8-bit ISO/IEC-8859-1 string.
See ToString( const String& ) for detailed information on the format string argument.
If this is an invalid TimePoint (for example, a default constructed instance), this function returns an empty string.
|
inline |
Returns an ISO 8601 extended date/time representation of this time point as an 8-bit ISO/IEC-8859-1 string.
timeItems | Number of represented time items. Can be 0, 1, 2 or 3. All items but the last one are represented as integer values. The last item is represented as a floating point value with the specified precision. |
precision | Number of decimal digits for the last represented time item. The default value is three decimal digits. |
tz | Time zone offset in hours. The default value is zero. |
timeZone | Whether to append a time zone specifier to the ISO 8601 representation. The default value is true. |
zuluTime | Whether to append the 'Z' special time zone specifier for UTC time without offset, or the '+00:00' specifier otherwise. The default value is true. |
If this is an invalid TimePoint (for example, a default constructed instance), this function returns an empty string.
Definition at line 443 of file TimePoint.h.
|
inline |
Returns an ISO 8601 extended date/time representation of this time point as a UTF-16 string.
options | Optional settings to control the representation of date and time in ISO 8601 extended format. |
tz | Time zone offset in hours. The default value is zero. |
If this is an invalid TimePoint (for example, a default constructed instance), this function returns an empty string.
Definition at line 362 of file TimePoint.h.
Returns a custom representation of this time point as a UTF-16 string.
format | A date and time format string. The following format tokens will be replaced with formatted date and time items, as described in the following table:
Other characters in the format string will be included literally in the result. To include a percent sign '%', escape it by preceding it with a backslash: "\\%". To include a backslash character, it must also be escaped as two consecutive slashes: "\\\\". |
If this is an invalid TimePoint (for example, a default constructed instance), this function returns an empty string.
Example:
|
inline |
Returns an ISO 8601 extended date/time representation of this time point as a UTF-16 string.
timeItems | Number of represented time items. Can be 0, 1, 2 or 3. All items but the last one are represented as integer values. The last item is represented as a floating point value with the specified precision. |
precision | Number of decimal digits for the last represented time item. The default value is three decimal digits. |
tz | Time zone offset in hours. The default value is zero. |
timeZone | Whether to append a time zone specifier to the ISO 8601 representation. The default value is true. |
zuluTime | Whether to append the 'Z' special time zone specifier for UTC time without offset, or the '+00:00' specifier otherwise. The default value is true. |
If this is an invalid TimePoint (for example, a default constructed instance), this function returns an empty string.
Definition at line 393 of file TimePoint.h.
|
inlinestatic |
Attempts to evaluate the specified 8-bit string as a date and time specification in ISO 8601 extended format. If successful, stores the evaluated UTC time point in the specified variable t, then returns true
.
If the specified string cannot be evaluated as a valid date and time in ISO 8601 extended format, this function returns false
and does not change the passed variable t. This function does not throw any parsing exceptions.
If the source string contains a time zone offset, it is subtracted from the evaluated time point. In other words, the TimePoint value stored in t is always represented in the UTC timescale without any offset.
Definition at line 1094 of file TimePoint.h.
Attempts to evaluate the specified UTF-16 string as a date and time specification in ISO 8601 extended format. If successful, stores the evaluated UTC time point in the specified variable t, then returns true
.
If the specified string cannot be evaluated as a valid date and time in ISO 8601 extended format, this function returns false
and does not change the passed variable t. This function does not throw any parsing exceptions.
If the source string contains a time zone offset, it is subtracted from the evaluated time point. In other words, the TimePoint value stored in t is always represented in the UTC timescale without any offset.
Definition at line 1117 of file TimePoint.h.
|
inlinestatic |
Attempts to evaluate the specified 8-bit string as a date and time specification in ISO 8601 extended format. If successful, stores the evaluated UTC time point in the specified variable t, and the evaluated time zone offset, in hours, in the variable tz, then returns true
.
If the specified string cannot be evaluated as a valid date and time in ISO 8601 extended format, this function returns false
and does not change the passed variables t and tz. This function does not throw any parsing exceptions.
If the source string contains a time zone offset, it is subtracted from the evaluated time point. In other words, the TimePoint value stored in t is always represented in the UTC timescale without any offset.
Definition at line 1035 of file TimePoint.h.
References pcl::IsoString::TryParseISO8601DateTime().
|
inlinestatic |
Attempts to evaluate the specified UTF-16 string as a date and time specification in ISO 8601 extended format. If successful, stores the evaluated UTC time point in the specified variable t, and the evaluated time zone offset, in hours, in the variable tz, then returns true
.
If the specified string cannot be evaluated as a valid date and time in ISO 8601 extended format, this function returns false
and does not change the passed variables t and tz. This function does not throw any parsing exceptions.
If the source string contains a time zone offset, it is subtracted from the evaluated time point. In other words, the TimePoint value stored in t is always represented in the UTC timescale without any offset.
Definition at line 1065 of file TimePoint.h.
References pcl::String::TryParseISO8601DateTime().
|
inlinestatic |
Returns a TimePoint object corresponding to the standard UNIX epoch, namely JD 2440587.5, corresponding to 1970 January 1.0.
Definition at line 929 of file TimePoint.h.
|
inline |
Returns this time point represented as Local Standard Time (LST), assuming that this object represents a time point in the UTC timescale.
Definition at line 859 of file TimePoint.h.
|
inline |
Returns the year component of this time point.
Definition at line 311 of file TimePoint.h.
References pcl::JDToCalendarTime().
|
inlineconstexpr |
Returns the time interval in Julian years (365.25 days) elapsed since the specified time point t.
Definition at line 705 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in Julian years (365.25 days) elapsed since the standard J2000 epoch (JD 2451545.0 = 2000 January 1.5).
Definition at line 779 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in Julian years (365.25 days) elapsed since the reference epoch. Currently this function is equivalent to YearsSinceJ2000().
Definition at line 742 of file TimePoint.h.
|
inlineconstexpr |
Returns the time interval in Julian years (365.25 days) elapsed since the standard UNIX epoch (JD 2440587.5 = 1970 January 1.0).
Definition at line 815 of file TimePoint.h.