PCL
pcl::TimePoint Class Reference

An instant in any timescale. More...

#include <TimePoint.h>

Public Member Functions

 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 (const IsoString &dateTime)
 
 TimePoint (const String &dateTime)
 
 TimePoint (time_t time)
 
 TimePoint (const FileTime &fileTime)
 
 TimePoint (const TimePoint &)=default
 
constexpr double CenturiesSince (const TimePoint &t) const
 
constexpr double CenturiesSinceJ2000 () const
 
constexpr double CenturiesSinceUNIXEpoch () const
 
int Day () const
 
double DayFraction () const
 
constexpr double DaysSince (const TimePoint &t) const
 
constexpr double DaysSinceJ2000 () const
 
constexpr double DaysSinceUNIXEpoch () const
 
double DeltaAT () const
 
double DeltaT () const
 
void GetComplexTime (int &year, int &month, int &day) const
 
void GetComplexTime (int &year, int &month, int &day, double &dayf) const
 
void GetComplexTime (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
 
TimePointoperator+= (double days)
 
TimePointoperator-= (double days)
 
TimePointoperator= (const TimePoint &)=default
 
constexpr double SecondsSince (const TimePoint &t) const
 
constexpr double SecondsSinceJ2000 () const
 
constexpr double SecondsSinceUNIXEpoch () const
 
double SystemOffsetFromUTC () const
 
IsoString ToIsoString (const ISO8601ConversionOptions &options=ISO8601ConversionOptions(), double tz=0) const
 
IsoString ToIsoString (unsigned timeItems, unsigned precision=3, double tz=0, bool timeZone=true, bool zuluTime=true) const
 
IsoString ToIsoString (const IsoString &format) const
 
String ToString (const ISO8601ConversionOptions &options=ISO8601ConversionOptions(), double tz=0) const
 
String ToString (unsigned timeItems, unsigned precision=3, double tz=0, bool timeZone=true, bool zuluTime=true) const
 
String ToString (const String &format) const
 
TimePoint UTCToLocalTime () const
 
int Year () const
 
constexpr double YearsSince (const TimePoint &t) const
 
constexpr double YearsSinceJ2000 () const
 
constexpr double YearsSinceUNIXEpoch () const
 

Static Public Member Functions

static TimePoint B1950 ()
 
static TimePoint FromString (double &tz, const IsoString &dateTime)
 
static TimePoint FromString (double &tz, const String &dateTime)
 
static TimePoint FromString (const IsoString &dateTime)
 
static TimePoint FromString (const String &dateTime)
 
static TimePoint J2000 ()
 
static TimePoint J2100 ()
 
static TimePoint Now ()
 
static bool TryFromString (TimePoint &t, double &tz, const IsoString &dateTime)
 
static bool TryFromString (TimePoint &t, double &tz, const String &dateTime)
 
static bool TryFromString (TimePoint &t, const IsoString &dateTime)
 
static bool TryFromString (TimePoint &t, 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 132 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 142 of file TimePoint.h.

References pcl::ComplexTimeToJD(), 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 151 of file TimePoint.h.

References pcl::ComplexTimeToJD().

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

References pcl::ComplexTimeToJD().

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

References pcl::ComplexTimeToJD(), 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 190 of file TimePoint.h.

References pcl::ComplexTimeToJD(), 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
fileTimeReference 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 835 of file TimePoint.h.

◆ CenturiesSince()

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

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

Definition at line 680 of file TimePoint.h.

◆ CenturiesSinceJ2000()

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

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

◆ CenturiesSinceUNIXEpoch()

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

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

References pcl::JDToComplexTime().

◆ DayFraction()

double pcl::TimePoint::DayFraction ( ) const
inline

Returns the day fraction component of this time point in the range [0,1).

Definition at line 340 of file TimePoint.h.

References pcl::JDToComplexTime().

◆ DaysSince()

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

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

Definition at line 662 of file TimePoint.h.

◆ DaysSinceJ2000()

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

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

Definition at line 698 of file TimePoint.h.

◆ DaysSinceUNIXEpoch()

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

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

Definition at line 734 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 ( 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 870 of file TimePoint.h.

References pcl::IsoString::ParseISO8601DateTime().

◆ FromString() [2/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 893 of file TimePoint.h.

References pcl::String::ParseISO8601DateTime().

◆ FromString() [3/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 913 of file TimePoint.h.

◆ FromString() [4/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 930 of file TimePoint.h.

◆ GetComplexTime() [1/3]

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

Extracts the individual date components.

Parameters
[out]yearReference to a variable that will receive the year component of this time point.
[out]monthReference to a variable that will receive the month component of this time point, in the range [1,12].
[out]dayReference to a variable that will receive the day component of this time point, in the range [1,31].

Definition at line 247 of file TimePoint.h.

References pcl::JDToComplexTime().

◆ GetComplexTime() [2/3]

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

Extracts the individual date and day fraction components.

Parameters
[out]yearReference to a variable that will receive the year component of this time point.
[out]monthReference to a variable that will receive the month component of this time point, in the range [1,12].
[out]dayReference to a variable that will receive the day component of this time point, in the range [1,31].
[out]dayfReference to a variable that will receive the day fraction component of this time point, in the range [0,1).

Definition at line 269 of file TimePoint.h.

References pcl::JDToComplexTime().

◆ GetComplexTime() [3/3]

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

Extracts the individual date and time components.

Parameters
[out]yearReference to a variable that will receive the year component of this time point.
[out]monthReference to a variable that will receive the month component of this time point, in the range [1,12].
[out]dayReference to a variable that will receive the day component of this time point, in the range [1,31].
[out]hourReference to a variable that will receive the hour component of this time point, in the range [0,23].
[out]minuteReference to a variable that will receive the minute component of this time point, in the range [0,59].
[out]secondsReference to a variable that will receive the seconds component of this time point, in the range [0,60).

Definition at line 296 of file TimePoint.h.

References pcl::Frac(), pcl::JDToComplexTime(), and pcl::TruncInt().

◆ IsValid()

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

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

Referenced by pcl::EphemerisFile::Handle::D(), and 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 811 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 823 of file TimePoint.h.

◆ JD()

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

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

Referenced by pcl::operator<(), and pcl::operator==().

◆ JDF()

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

Returns the fractional part of the Julian date corresponding to this time point.

Definition at line 565 of file TimePoint.h.

Referenced by pcl::JPLEphemeris::ComputeState(), pcl::operator-(), pcl::operator<(), and pcl::operator==().

◆ JDI()

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

Returns the integer part of the Julian date (also referred to as Julian day number) corresponding to this time point.

Definition at line 556 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 796 of file TimePoint.h.

◆ MillisecondsSinceUNIXEpoch()

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

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

Definition at line 770 of file TimePoint.h.

◆ MJD()

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

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

References pcl::JDToComplexTime().

◆ Now()

static TimePoint pcl::TimePoint::Now ( )
static

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

◆ operator IsoString()

pcl::TimePoint::operator IsoString ( ) const
inlineexplicit

IsoString conversion operator. Equivalent to ToIsoString().

Definition at line 547 of file TimePoint.h.

◆ operator String()

pcl::TimePoint::operator String ( ) const
inlineexplicit

String conversion operator. Equivalent to ToString().

Definition at line 539 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 640 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 651 of file TimePoint.h.

◆ operator=()

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

Copy assignment operator. Returns a reference to this object.

◆ SecondsSince()

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

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

Definition at line 689 of file TimePoint.h.

◆ SecondsSinceJ2000()

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

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

Definition at line 725 of file TimePoint.h.

◆ SecondsSinceUNIXEpoch()

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

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

Definition at line 761 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
optionsOptional settings to control the representation of date and time in ISO 8601 extended format.
tzTime 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 411 of file TimePoint.h.

◆ ToIsoString() [2/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
timeItemsNumber 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.
precisionNumber of decimal digits for the last represented time item. The default value is three decimal digits.
tzTime zone offset in hours. The default value is zero.
timeZoneWhether to append a time zone specifier to the ISO 8601 representation. The default value is true.
zuluTimeWhether 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 442 of file TimePoint.h.

◆ ToIsoString() [3/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.

◆ 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
optionsOptional settings to control the representation of date and time in ISO 8601 extended format.
tzTime 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 361 of file TimePoint.h.

◆ ToString() [2/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
timeItemsNumber 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.
precisionNumber of decimal digits for the last represented time item. The default value is three decimal digits.
tzTime zone offset in hours. The default value is zero.
timeZoneWhether to append a time zone specifier to the ISO 8601 representation. The default value is true.
zuluTimeWhether 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 392 of file TimePoint.h.

◆ ToString() [3/3]

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

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

Parameters
formatA 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:

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';

◆ TryFromString() [1/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 953 of file TimePoint.h.

References pcl::IsoString::TryParseISO8601DateTime().

◆ TryFromString() [2/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 983 of file TimePoint.h.

References pcl::String::TryParseISO8601DateTime().

◆ TryFromString() [3/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 1012 of file TimePoint.h.

◆ TryFromString() [4/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 1035 of file TimePoint.h.

References pcl::Abs(), pcl::Frac(), int32_max, and pcl::TruncInt().

◆ 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 847 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 787 of file TimePoint.h.

◆ Year()

int pcl::TimePoint::Year ( ) const
inline

Returns the year component of this time point.

Definition at line 310 of file TimePoint.h.

References pcl::JDToComplexTime().

◆ YearsSince()

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

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

Definition at line 671 of file TimePoint.h.

◆ YearsSinceJ2000()

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

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

◆ YearsSinceUNIXEpoch()

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

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


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