PCL
pcl::TimePoint Class Reference

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
 
TimePointoperator+= (double days)
 
TimePointoperator-= (double days)
 
TimePointoperator= (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 ()
 

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
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 917 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 714 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 788 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 752 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 824 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 696 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 770 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 732 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 806 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 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.

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

See also
IsDeltaTExtrapolationEnabled(), EnableDeltaTExtrapolation()

◆ DisableDeltaTExtrapolation()

static void pcl::TimePoint::DisableDeltaTExtrapolation ( bool  disable = true)
inlinestatic

Disables extrapolation of Delta T values.

See DeltaT() for information on Delta T extrapolation.

Definition at line 646 of file TimePoint.h.

◆ EnableDeltaTExtrapolation()

static void pcl::TimePoint::EnableDeltaTExtrapolation ( bool  enable = true)
static

Enables extrapolation of Delta T values.

See DeltaT() for information on Delta T extrapolation.

◆ 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 995 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 1012 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 952 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 975 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]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 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]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 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]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 297 of file TimePoint.h.

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

◆ IsDeltaTExtrapolationEnabled()

static bool pcl::TimePoint::IsDeltaTExtrapolationEnabled ( )
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.

◆ 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 893 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 905 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 868 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 842 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 674 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 685 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 884 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 723 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 797 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 761 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 833 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 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
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 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
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 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
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';
static TimePoint Now()
TimePoint()=default

◆ 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
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 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 1094 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 1117 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 1035 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 1065 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 929 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 859 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 705 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 779 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 742 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 815 of file TimePoint.h.


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