Time and date functions.

Overview

Header: #include <mrpt/system/datetime.h>.

Library: [mrpt-system]

Defines types and functions to handle cross-platform timestamps. The basic type is mrpt::system::TTimeStamp, representing a high-resolution (100ns) Clock::time_point, compatible with all C++11 std::chrono functions.

There are also functions to convert forth and back to a double representation of timestamps: numbers just like UNIX epoch timestamps but with decimals for the fractionary part of seconds.

// typedefs

typedef mrpt::Clock::time_point mrpt::system::TTimeStamp;

// structs

struct mrpt::system::TTimeParts;

// global functions

const TTimeStamp& mrpt::system::InvalidTimeStamp();
mrpt::system::TTimeStamp mrpt::system::buildTimestampFromParts(const mrpt::system::TTimeParts& p);
mrpt::system::TTimeStamp mrpt::system::buildTimestampFromPartsLocalTime(const mrpt::system::TTimeParts& p);
void mrpt::system::timestampToParts(TTimeStamp t, TTimeParts& p, bool localTime = false);
mrpt::system::TTimeStamp mrpt::system::getCurrentTime();
mrpt::system::TTimeStamp mrpt::system::now();
mrpt::system::TTimeStamp mrpt::system::time_tToTimestamp(const double t);
mrpt::system::TTimeStamp mrpt::system::time_tToTimestamp(const time_t& t);
double mrpt::system::timestampTotime_t(const mrpt::system::TTimeStamp t);
double mrpt::system::timestampToDouble(const mrpt::system::TTimeStamp t);
double mrpt::system::timeDifference(const mrpt::system::TTimeStamp& t_first, const mrpt::system::TTimeStamp& t_later);
double mrpt::system::now_double();
mrpt::system::TTimeStamp mrpt::system::timestampAdd(const mrpt::system::TTimeStamp tim, const double num_seconds);
std::string mrpt::system::formatTimeInterval(const double timeSeconds);
std::string mrpt::system::dateTimeToString(const mrpt::system::TTimeStamp t);
std::string mrpt::system::dateTimeLocalToString(const mrpt::system::TTimeStamp t);
std::string mrpt::system::dateToString(const mrpt::system::TTimeStamp t);
double mrpt::system::extractDayTimeFromTimestamp(const mrpt::system::TTimeStamp t);
std::string mrpt::system::timeToString(const mrpt::system::TTimeStamp t);
std::string mrpt::system::timeLocalToString(const mrpt::system::TTimeStamp t, unsigned int secondFractionDigits = 6);
std::string mrpt::system::intervalFormat(const double seconds);
std::ostream& mrpt::system::operator << (std::ostream& o, const TTimeStamp& t);

// macros

#define INVALID_TIMESTAMP

Typedefs

typedef mrpt::Clock::time_point mrpt::system::TTimeStamp

A system independent time type, it holds the the number of 100-nanosecond intervals since January 1, 1601 (UTC) as a mrpt::Clock::time_point (uint64_t).

See also:

system::getCurrentTime, system::timeDifference, INVALID_TIMESTAMP, TTimeParts

Global Functions

const TTimeStamp& mrpt::system::InvalidTimeStamp()

Required to ensure INVALID_TIMESTAMP returns a “const T&”.

(New in MRPT 2.3.3)

mrpt::system::TTimeStamp mrpt::system::buildTimestampFromParts(const mrpt::system::TTimeParts& p)

Builds a timestamp from the parts (Parts are in UTC)

See also:

timestampToParts

mrpt::system::TTimeStamp mrpt::system::buildTimestampFromPartsLocalTime(const mrpt::system::TTimeParts& p)

Builds a timestamp from the parts (Parts are in local time)

See also:

timestampToParts, buildTimestampFromParts

void mrpt::system::timestampToParts(TTimeStamp t, TTimeParts& p, bool localTime = false)

Gets the individual parts of a date/time (days, hours, minutes, seconds) - UTC time or local time.

See also:

buildTimestampFromParts

mrpt::system::TTimeStamp mrpt::system::getCurrentTime()

Returns the current (UTC) system time.

See also:

now

mrpt::system::TTimeStamp mrpt::system::now()

A shortcut for system::getCurrentTime.

See also:

getCurrentTime

mrpt::system::TTimeStamp mrpt::system::time_tToTimestamp(const double t)

Transform from standard “time_t” (actually a double number, it can contain fractions of seconds) to TTimeStamp.

See also:

timestampTotime_t

mrpt::system::TTimeStamp mrpt::system::time_tToTimestamp(const time_t& t)

Transform from standard “time_t” to TTimeStamp.

See also:

timestampTotime_t

double mrpt::system::timestampTotime_t(const mrpt::system::TTimeStamp t)

Transform from TTimeStamp to standard “time_t” (actually a double number, it can contain fractions of seconds).

See also:

time_tToTimestamp

double mrpt::system::timestampToDouble(const mrpt::system::TTimeStamp t)

Transform from TTimeStamp to standard “time_t” (actually a double number, it can contain fractions of seconds).

This function is just an (inline) alias of timestampTotime_t(), with a more significant name.

See also:

time_tToTimestamp

double mrpt::system::timeDifference(const mrpt::system::TTimeStamp& t_first, const mrpt::system::TTimeStamp& t_later)

Returns the time difference from t1 to t2 (positive if t2 is posterior to t1), in seconds

double mrpt::system::now_double()

Returns the current time, as a double (fractional version of time_t) instead of a TTimeStamp.

See also:

now(), timestampTotime_t()

mrpt::system::TTimeStamp mrpt::system::timestampAdd(const mrpt::system::TTimeStamp tim, const double num_seconds)

Shifts a timestamp the given amount of seconds (>0: forwards in time, <0: backwards)

std::string mrpt::system::formatTimeInterval(const double timeSeconds)

Returns a formated string with the given time difference (passed as the number of seconds), as a string [H]H:MM:SS.MILLISECONDS.

See also:

unitsFormat

std::string mrpt::system::dateTimeToString(const mrpt::system::TTimeStamp t)

Convert a timestamp into this textual form (UTC time): YEAR/MONTH/DAY,HH:MM:SS.MMM.

See also:

dateTimeLocalToString

std::string mrpt::system::dateTimeLocalToString(const mrpt::system::TTimeStamp t)

Convert a timestamp into this textual form (in local time): YEAR/MONTH/DAY,HH:MM:SS.MMM.

See also:

dateTimeToString

std::string mrpt::system::dateToString(const mrpt::system::TTimeStamp t)

Convert a timestamp into this textual form: YEAR/MONTH/DAY.

double mrpt::system::extractDayTimeFromTimestamp(const mrpt::system::TTimeStamp t)

Returns the number of seconds ellapsed from midnight in the given timestamp.

std::string mrpt::system::timeToString(const mrpt::system::TTimeStamp t)

Convert a timestamp into this textual form (UTC): HH:MM:SS.MMMMMM.

std::string mrpt::system::timeLocalToString(
    const mrpt::system::TTimeStamp t,
    unsigned int secondFractionDigits = 6
    )

Convert a timestamp into this textual form (in local time): HH:MM:SS.MMMMMM.

std::string mrpt::system::intervalFormat(const double seconds)

This function implements time interval formatting: Given a time in seconds, it will return a string describing the interval with the most appropriate unit.

E.g.:

  • “1 year, 3 days, 4 minutes”

  • “3 days, 8 hours”

  • “9 hours, 4 minutes, 4.3 sec”,

  • “3.34 sec”

  • “178.1 ms”

  • “87.1 us”

See also:

unitsFormat

std::ostream& mrpt::system::operator << (std::ostream& o, const TTimeStamp& t)

Textual representation of a TTimeStamp as the plain number in time_since_epoch().count()

Macros

#define INVALID_TIMESTAMP

Represents an invalid timestamp, where applicable.

It returns a const reference to a thread_local static object of type mrpt::Clock::time_point initialized with the default constructor, which is used as the reference “invalid” timestamp.