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 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 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 ()

Detailed Description

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.

See also: ISO8601ConversionOptions, IsoString::ParseISO8601DateTime()

Definition at line 102 of file TimePoint.h.

Constructor & Destructor Documentation

◆ TimePoint() [1/11]

pcl::TimePoint::TimePoint ( )

default

Default constructor. Yields an invalid TimePoint object that cannot be used until properly initialized.

◆ TimePoint() [2/11]

pcl::TimePoint::TimePoint ( double jd )

inline

Constructs a TimePoint object for a given instant represented as a Julian date.

Definition at line 116 of file TimePoint.h.

◆ TimePoint() [3/11]

pcl::TimePoint::TimePoint	(	double	jd1,
		double	jd2
	)

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.

◆ TimePoint() [4/11]

pcl::TimePoint::TimePoint	(	int	year,
		int	month,
		double	days
	)

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().

◆ TimePoint() [5/11]

pcl::TimePoint::TimePoint	(	int	year,
		int	month,
		int	day,
		double	dayFraction
	)

inline

Constructs a TimePoint object from separate date components plus a day fraction.

Definition at line 152 of file TimePoint.h.

References pcl::CalendarTimeToJD().

◆ TimePoint() [6/11]

pcl::TimePoint::TimePoint	(	int	year,
		int	month,
		int	day,
		int	hour,
		int	minute,
		double	seconds
	)

inline

Constructs a TimePoint object from separate date and time components.

Definition at line 160 of file TimePoint.h.

References pcl::CalendarTimeToJD().

◆ TimePoint() [7/11]

pcl::TimePoint::TimePoint ( const IsoString & dateTime )

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().

◆ TimePoint() [8/11]

pcl::TimePoint::TimePoint ( const String & dateTime )

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().

◆ TimePoint() [9/11]

pcl::TimePoint::TimePoint ( time_t time )

Constructs a TimePoint object from a time_t value. The specified time value will be interpreted as UTC.

◆ TimePoint() [10/11]

pcl::TimePoint::TimePoint ( const FileTime & fileTime )

Constructs a TimePoint object from a FileTime object.

Parameters

fileTime Reference to a FileTime structure, from which date and time elements will be obtained to construct a TimePoint object. The file time is expected to be represented as UTC, which is coherent with most file systems.

◆ TimePoint() [11/11]

pcl::TimePoint::TimePoint ( const TimePoint & )

default

Copy constructor.

Member Function Documentation

◆ B1950()

static TimePoint pcl::TimePoint::B1950 ( )

inlinestatic

Returns a TimePoint object corresponding to the B1950.0 epoch, namely JD 2433282.42345905, corresponding to 1949 December 31.92345905.

Definition at line 884 of file TimePoint.h.

◆ CenturiesSince()

constexpr double pcl::TimePoint::CenturiesSince ( const TimePoint & t ) const

inlineconstexpr

Returns the time interval in Julian centuries (36525 days) elapsed since the specified time point t.

Definition at line 681 of file TimePoint.h.

◆ CenturiesSinceJ2000()

constexpr double pcl::TimePoint::CenturiesSinceJ2000 ( ) const

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 755 of file TimePoint.h.

◆ CenturiesSinceReferenceEpoch()

constexpr double pcl::TimePoint::CenturiesSinceReferenceEpoch ( ) const

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 719 of file TimePoint.h.

◆ CenturiesSinceUNIXEpoch()

constexpr double pcl::TimePoint::CenturiesSinceUNIXEpoch ( ) const

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 791 of file TimePoint.h.

◆ Day()

int pcl::TimePoint::Day ( ) const

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().

◆ DayFraction()

double pcl::TimePoint::DayFraction ( ) const

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().

◆ DaysSince()

constexpr double pcl::TimePoint::DaysSince ( const TimePoint & t ) const

inlineconstexpr

Returns the time interval in days elapsed since the specified time point t.

Definition at line 663 of file TimePoint.h.

◆ DaysSinceJ2000()

constexpr double pcl::TimePoint::DaysSinceJ2000 ( ) const

inlineconstexpr

Returns the time interval in days elapsed since the standard J2000 epoch (JD 2451545.0 = 2000 January 1.5).

Definition at line 737 of file TimePoint.h.

◆ DaysSinceReferenceEpoch()

constexpr double pcl::TimePoint::DaysSinceReferenceEpoch ( ) const

inlineconstexpr

Returns the time interval in days elapsed since the reference epoch. Currently this function is equivalent to DaysSinceJ2000().

Definition at line 699 of file TimePoint.h.

◆ DaysSinceUNIXEpoch()

constexpr double pcl::TimePoint::DaysSinceUNIXEpoch ( ) const

inlineconstexpr

Returns the time interval in days elapsed since the standard UNIX epoch (JD 2440587.5 = 1970 January 1.0).

Definition at line 773 of file TimePoint.h.

◆ DeltaAT()

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 before that year is a conceptual error. For convenience, zero is returned in such case instead of throwing an exception.

The returned value is the difference TAI-UTC in seconds.

◆ DeltaT()

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, 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).

The returned value is the difference TT-UT1 in seconds.

◆ FromString() [1/4]

static TimePoint pcl::TimePoint::FromString ( const IsoString & dateTime )

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 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.

See also: TryFromString( TimePoint&, const IsoString& ), IsoString::ParseISO8601DateTime()

Definition at line 962 of file TimePoint.h.

◆ FromString() [2/4]

static TimePoint pcl::TimePoint::FromString ( const String & dateTime )

inlinestatic

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.

See also: TryFromString( TimePoint&, const String& ), String::ParseISO8601DateTime()

Definition at line 979 of file TimePoint.h.

◆ FromString() [3/4]

static TimePoint pcl::TimePoint::FromString	(	double &	tz,
		const IsoString &	dateTime
	)

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.

See also: TryFromString( TimePoint&, double&, const IsoString& ), IsoString::ParseISO8601DateTime()

Definition at line 919 of file TimePoint.h.

References pcl::IsoString::ParseISO8601DateTime().

◆ FromString() [4/4]

static TimePoint pcl::TimePoint::FromString	(	double &	tz,
		const String &	dateTime
	)

inlinestatic

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.

See also: TryFromString( TimePoint&, double&, const String& ), String::ParseISO8601DateTime()

Definition at line 942 of file TimePoint.h.

References pcl::String::ParseISO8601DateTime().

◆ GetCalendarTime() [1/3]

void pcl::TimePoint::GetCalendarTime	(	int &	year,
		int &	month,
		int &	day
	)		const

inline

Extracts the individual date components.

Parameters

[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().

◆ GetCalendarTime() [2/3]

void pcl::TimePoint::GetCalendarTime	(	int &	year,
		int &	month,
		int &	day,
		double &	dayf
	)		const

inline

Extracts the individual date and day fraction components.

Parameters

[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().

◆ GetCalendarTime() [3/3]

void pcl::TimePoint::GetCalendarTime	(	int &	year,
		int &	month,
		int &	day,
		int &	hour,
		int &	minute,
		double &	seconds
	)		const

inline

Extracts the individual date and time components.

Parameters

[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().

◆ IsValid()

constexpr bool pcl::TimePoint::IsValid ( ) const

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<().

◆ J2000()

static TimePoint pcl::TimePoint::J2000 ( )

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 860 of file TimePoint.h.

◆ J2100()

static TimePoint pcl::TimePoint::J2100 ( )

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 872 of file TimePoint.h.

◆ JD()

constexpr double pcl::TimePoint::JD ( ) const

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==().

◆ JDF()

constexpr double pcl::TimePoint::JDF ( ) const

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==().

◆ JDI()

constexpr int pcl::TimePoint::JDI ( ) const

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==().

◆ LocalTimeToUTC()

TimePoint pcl::TimePoint::LocalTimeToUTC ( ) const

inline

Returns this time point represented as UTC, assuming that this object represents a time point in Local Standard Time (LST).

Definition at line 835 of file TimePoint.h.

◆ MillisecondsSinceUNIXEpoch()

constexpr double pcl::TimePoint::MillisecondsSinceUNIXEpoch ( ) const

inlineconstexpr

Returns the time interval in milliseconds elapsed since the standard UNIX epoch (JD 2440587.5 = 1970 January 1.0).

Definition at line 809 of file TimePoint.h.

◆ MJD()

constexpr double pcl::TimePoint::MJD ( ) const

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.

◆ Month()

int pcl::TimePoint::Month ( ) const

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().

◆ Now()

static TimePoint pcl::TimePoint::Now ( )

static

Returns a TimePoint object corresponding to the current date and time in the UTC timescale.

Referenced by pcl::FileDataCacheItem::DaysSinceLastUsed().

◆ operator IsoString()

pcl::TimePoint::operator IsoString ( ) const

inlineexplicit

IsoString conversion operator. Equivalent to ToIsoString().

Definition at line 548 of file TimePoint.h.

◆ operator String()

pcl::TimePoint::operator String ( ) const

inlineexplicit

String conversion operator. Equivalent to ToString().

Definition at line 540 of file TimePoint.h.

◆ operator+=()

TimePoint& pcl::TimePoint::operator+= ( double days )

inline

Adds the specified number of days to this time point. Returns a reference to this object.

Definition at line 641 of file TimePoint.h.

◆ operator-=()

TimePoint& pcl::TimePoint::operator-= ( double days )

inline

Subtracts the specified number of days from this time point. Returns a reference to this object.

Definition at line 652 of file TimePoint.h.

◆ operator=()

TimePoint& pcl::TimePoint::operator= ( const TimePoint & )

default

Copy assignment operator. Returns a reference to this object.

◆ ReferenceEpoch()

static TimePoint pcl::TimePoint::ReferenceEpoch ( )

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 851 of file TimePoint.h.

◆ SecondsSince()

constexpr double pcl::TimePoint::SecondsSince ( const TimePoint & t ) const

inlineconstexpr

Returns the time interval in seconds elapsed since the specified time point t.

Definition at line 690 of file TimePoint.h.

◆ SecondsSinceJ2000()

constexpr double pcl::TimePoint::SecondsSinceJ2000 ( ) const

inlineconstexpr

Returns the time interval in seconds elapsed since the standard J2000 epoch (JD 2451545.0 = 2000 January 1.5).

Definition at line 764 of file TimePoint.h.

◆ SecondsSinceReferenceEpoch()

constexpr double pcl::TimePoint::SecondsSinceReferenceEpoch ( ) const

inlineconstexpr

Returns the time interval in seconds elapsed since the reference epoch. Currently this function is equivalent to SecondsSinceJ2000().

Definition at line 728 of file TimePoint.h.

◆ SecondsSinceUNIXEpoch()

constexpr double pcl::TimePoint::SecondsSinceUNIXEpoch ( ) const

inlineconstexpr

Returns the time interval in seconds elapsed since the standard UNIX epoch (JD 2440587.5 = 1970 January 1.0).

Definition at line 800 of file TimePoint.h.

◆ SystemOffsetFromUTC()

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.

◆ ToIsoString() [1/3]

IsoString pcl::TimePoint::ToIsoString	(	const ISO8601ConversionOptions &	options = `ISO8601ConversionOptions()`,
		double	tz = `0`
	)		const

inline

Returns an ISO 8601 extended date/time representation of this time point as an 8-bit ISO/IEC-8859-1 string.

Parameters

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.

See also: ISO8601ConversionOptions, IsoString::ParseISO8601DateTime(), IsValid()

Definition at line 412 of file TimePoint.h.

◆ ToIsoString() [2/3]

IsoString pcl::TimePoint::ToIsoString ( const IsoString & format ) const

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.

◆ ToIsoString() [3/3]

IsoString pcl::TimePoint::ToIsoString	(	unsigned	timeItems,
		unsigned	precision = `3`,
		double	tz = `0`,
		bool	timeZone = `true`,
		bool	zuluTime = `true`
	)		const

inline

Returns an ISO 8601 extended date/time representation of this time point as an 8-bit ISO/IEC-8859-1 string.

Parameters

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.

See also: ISO8601ConversionOptions, IsoString::ParseISO8601DateTime(), IsValid()

Definition at line 443 of file TimePoint.h.

◆ ToString() [1/3]

String pcl::TimePoint::ToString	(	const ISO8601ConversionOptions &	options = `ISO8601ConversionOptions()`,
		double	tz = `0`
	)		const

inline

Returns an ISO 8601 extended date/time representation of this time point as a UTF-16 string.

Parameters

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.

See also: ISO8601ConversionOptions, String::ParseISO8601DateTime(), IsValid()

Definition at line 362 of file TimePoint.h.

◆ ToString() [2/3]

String pcl::TimePoint::ToString ( const String & format ) const

Returns a custom representation of this time point as a UTF-16 string.

Parameters

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:

%Y	The four-digit year.
%M	Zero padded, two-digit month number, '01' through '12'.
%n	The month number, '1' through '12'.
%N	The English month name, 'January' through 'December'.
%D	Zero padded, two-digit day of month, '01' through '31'.
%d	The day of the month, '1' through '31'.
%h	Zero padded, two digits of hour, '00' through '23'.
%m	Zero padded, two digits of minute, '00' through '59'.
%s	Zero padded, two digits of the seconds truncated to an integer, '00' through '59'.
%s<p>	Zero padded representation of seconds rounded or truncated to <p> decimal digits, with <p> in [0,9]. Truncation instead of rounding will we used if the rounded value is equal to 60 seconds.

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:

TimePoint t = TimePoint::Now();
std::cout << t.ToString( "%Y-%M-%D %h:%m:%s" ) << '\n'
          << t.ToString( "%Y-%M-%D %h:%m:%s2" ) << '\n'
          << t.ToString( "Today is: %N %d, %Y %h:%m:%s" ) << '\n';

◆ ToString() [3/3]

String pcl::TimePoint::ToString	(	unsigned	timeItems,
		unsigned	precision = `3`,
		double	tz = `0`,
		bool	timeZone = `true`,
		bool	zuluTime = `true`
	)		const

inline

Returns an ISO 8601 extended date/time representation of this time point as a UTF-16 string.

Parameters

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.

See also: ISO8601ConversionOptions, String::ParseISO8601DateTime(), IsValid()

Definition at line 393 of file TimePoint.h.

◆ TryFromString() [1/4]

static bool pcl::TimePoint::TryFromString	(	TimePoint &	t,
		const IsoString &	dateTime
	)

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.

See also: FromString( const IsoString& ), IsoString::TryParseISO8601DateTime()

Definition at line 1061 of file TimePoint.h.

◆ TryFromString() [2/4]

static bool pcl::TimePoint::TryFromString	(	TimePoint &	t,
		const String &	dateTime
	)

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, 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.

See also: FromString( const String& ), String::TryParseISO8601DateTime()

Definition at line 1084 of file TimePoint.h.

◆ TryFromString() [3/4]

static bool pcl::TimePoint::TryFromString	(	TimePoint &	t,
		double &	tz,
		const IsoString &	dateTime
	)

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.

See also: FromString( const IsoString& ), IsoString::TryParseISO8601DateTime()

Definition at line 1002 of file TimePoint.h.

References pcl::IsoString::TryParseISO8601DateTime().

◆ TryFromString() [4/4]

static bool pcl::TimePoint::TryFromString	(	TimePoint &	t,
		double &	tz,
		const String &	dateTime
	)

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.

See also: FromString( const String& ), String::TryParseISO8601DateTime()

Definition at line 1032 of file TimePoint.h.

References pcl::String::TryParseISO8601DateTime().

◆ UNIXEpoch()

static TimePoint pcl::TimePoint::UNIXEpoch ( )

inlinestatic

Returns a TimePoint object corresponding to the standard UNIX epoch, namely JD 2440587.5, corresponding to 1970 January 1.0.

Definition at line 896 of file TimePoint.h.

◆ UTCToLocalTime()

TimePoint pcl::TimePoint::UTCToLocalTime ( ) const

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 826 of file TimePoint.h.

◆ Year()

int pcl::TimePoint::Year ( ) const

inline

Returns the year component of this time point.

Definition at line 311 of file TimePoint.h.

References pcl::JDToCalendarTime().

◆ YearsSince()

constexpr double pcl::TimePoint::YearsSince ( const TimePoint & t ) const

inlineconstexpr

Returns the time interval in Julian years (365.25 days) elapsed since the specified time point t.

Definition at line 672 of file TimePoint.h.

◆ YearsSinceJ2000()

constexpr double pcl::TimePoint::YearsSinceJ2000 ( ) const

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 746 of file TimePoint.h.

◆ YearsSinceReferenceEpoch()

constexpr double pcl::TimePoint::YearsSinceReferenceEpoch ( ) const

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 709 of file TimePoint.h.

◆ YearsSinceUNIXEpoch()

constexpr double pcl::TimePoint::YearsSinceUNIXEpoch ( ) const

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 782 of file TimePoint.h.

The documentation for this class was generated from the following file:

TimePoint.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TimePoint() [1/11]

◆ TimePoint() [2/11]

◆ TimePoint() [3/11]

◆ TimePoint() [4/11]

◆ TimePoint() [5/11]

◆ TimePoint() [6/11]

◆ TimePoint() [7/11]

◆ TimePoint() [8/11]

◆ TimePoint() [9/11]

◆ TimePoint() [10/11]

◆ TimePoint() [11/11]

Member Function Documentation

◆ B1950()

◆ CenturiesSince()

◆ CenturiesSinceJ2000()

◆ CenturiesSinceReferenceEpoch()

◆ CenturiesSinceUNIXEpoch()

◆ Day()

◆ DayFraction()

◆ DaysSince()

◆ DaysSinceJ2000()

◆ DaysSinceReferenceEpoch()

◆ DaysSinceUNIXEpoch()

◆ DeltaAT()

◆ DeltaT()

◆ FromString() [1/4]

◆ FromString() [2/4]

◆ FromString() [3/4]

◆ FromString() [4/4]

◆ GetCalendarTime() [1/3]

◆ GetCalendarTime() [2/3]

◆ GetCalendarTime() [3/3]

◆ IsValid()

◆ J2000()

◆ J2100()

◆ JD()

◆ JDF()

◆ JDI()

◆ LocalTimeToUTC()

◆ MillisecondsSinceUNIXEpoch()

◆ MJD()

◆ Month()

◆ Now()

◆ operator IsoString()

◆ operator String()

◆ operator+=()

◆ operator-=()

◆ operator=()

◆ ReferenceEpoch()

◆ SecondsSince()

◆ SecondsSinceJ2000()

◆ SecondsSinceReferenceEpoch()

◆ SecondsSinceUNIXEpoch()

◆ SystemOffsetFromUTC()

◆ ToIsoString() [1/3]

◆ ToIsoString() [2/3]

◆ ToIsoString() [3/3]

◆ ToString() [1/3]

◆ ToString() [2/3]

◆ ToString() [3/3]

◆ TryFromString() [1/4]

◆ TryFromString() [2/4]

◆ TryFromString() [3/4]

◆ TryFromString() [4/4]

◆ UNIXEpoch()

◆ UTCToLocalTime()

◆ Year()

◆ YearsSince()

◆ YearsSinceJ2000()

◆ YearsSinceReferenceEpoch()

◆ YearsSinceUNIXEpoch()