Goby3  3.1.5a
2024.05.23
goby::time Namespace Reference

Functions and objects related to timekeeping. More...

Classes

struct  ASIOGobyTime
 
struct  SimulatorSettings
 Parameters for enabling and configuring simulation time. More...
 
struct  SteadyClock
 Essentially the same as std::chrono::steady_clock except the time returned by SteadyClock::now() can be "warped" (made to run faster than real time) for simulation purposes. To do this, set the appropriate parameters in SimulatorSettings. More...
 
struct  SystemClock
 Essentially the same as std::chrono::system_clock except the time returned by SystemClock::now() can be "warped" (made to run faster than real time) for simulation purposes. To do this, set the appropriate parameters in SimulatorSettings. More...
 

Typedefs

using MicroTimeUnit = decltype(boost::units::si::micro *boost::units::si::seconds)
 microsecond unit More...
 
using MicroTime = boost::units::quantity< MicroTimeUnit, std::int64_t >
 quantity of microseconds (using int64) More...
 
using SITime = boost::units::quantity< boost::units::si::time, double >
 quantity of seconds (using double) More...
 

Functions

template<typename ToTimeType , typename FromTimeType , typename std::enable_if< std::is_same< ToTimeType, FromTimeType >{}, int >::type = 0>
ToTimeType convert (FromTimeType from_time)
 Convert between time representations (this function works for tautological conversions) More...
 
template<typename ToTimeType , typename FromTimeType , typename ToUnitType = typename ToTimeType::unit_type, typename ToValueType = typename ToTimeType::value_type, typename FromUnitType = typename FromTimeType::unit_type, typename FromValueType = typename FromTimeType::value_type, typename std::enable_if< !std::is_same< ToTimeType, FromTimeType >{} &&std::is_same< ToTimeType, boost::units::quantity< ToUnitType, ToValueType >>{} &&std::is_same< FromTimeType, boost::units::quantity< FromUnitType, FromValueType >>{}, int >::type = 0>
ToTimeType convert (FromTimeType from_time)
 Convert between time representations (this function converts between two different boost::units::quantity of time) More...
 
template<typename ToTimeType , typename FromTimeType , typename ToUnitType = typename ToTimeType::unit_type, typename ToValueType = typename ToTimeType::value_type, typename std::enable_if< std::is_same< ToTimeType, boost::units::quantity< ToUnitType, ToValueType >>{} &&(std::is_same< FromTimeType, SystemClock::time_point >{}||std::is_same< FromTimeType, std::chrono::system_clock::time_point >{}), int >::type = 0>
ToTimeType convert (FromTimeType from_time)
 Convert between time representations (this function converts to a boost::units::quantity of time from either a chrono::system_clock::time_point or a goby::time::SystemClock::time_point) More...
 
template<typename TimeType = SystemClock::time_point>
std::string str (TimeType value=SystemClock::now< TimeType >())
 Returns the provided time (or current time if omitted) as a human-readable string. More...
 
template<typename TimeType = SystemClock::time_point>
std::string file_str (TimeType value=SystemClock::now< TimeType >())
 Returns the provided time (or current time if omitted) as an ISO string suitable for file names (no spaces or special characters, e.g. 20180322T215258) More...
 
template<typename ToDurationType , typename FromDurationType , typename std::enable_if< std::is_same< ToDurationType, FromDurationType >{}, int >::type = 0>
ToDurationType convert_duration (FromDurationType from_duration)
 Convert between duration representations (this function works for tautological conversions) More...
 
template<typename ToDurationType , typename FromDurationType , typename ToUnitType = typename ToDurationType::unit_type, typename ToValueType = typename ToDurationType::value_type, typename FromUnitType = typename FromDurationType::unit_type, typename FromValueType = typename FromDurationType::value_type, typename std::enable_if< !std::is_same< ToDurationType, FromDurationType >{} &&std::is_same< ToDurationType, boost::units::quantity< ToUnitType, ToValueType >>{} &&std::is_same< FromDurationType, boost::units::quantity< FromUnitType, FromValueType >>{}, int >::type = 0>
ToDurationType convert_duration (FromDurationType from_duration)
 Convert between duration representations (this function converts between two different boost::units::quantity of time) More...
 
template<typename ToTimeType >
ToTimeType convert_from_nmea (const std::string &utc, boost::gregorian::date return_date=boost::gregorian::day_clock::universal_day())
 Convert from NMEA0183 time representations (i.e. "HHMMSS[.SSSS]") to any time format supported by the goby::time::convert function family. This function assumes the time is from the current day. More...
 
template<typename ToTimeType >
ToTimeType convert_from_nmea (const std::string &utc, const std::string &date)
 Convert from NMEA0183 time representations (i.e. "HHMMSS[.SSSS]") to any time format supported by the goby::time::convert function family. This function assumes the time is from the current day. More...
 
std::ostream & operator<< (std::ostream &out, const goby::time::SystemClock::time_point &time)
 
std::ostream & operator<< (std::ostream &out, const goby::time::SteadyClock::time_point &time)
 
std::ostream & operator<< (std::ostream &out, const goby::time::SystemClock::duration &duration)
 

Detailed Description

Functions and objects related to timekeeping.

Goby timekeeping revolves around C++ chrono concepts, such as SystemClock (absolute world-referenced time) and SteadyClock (non-synchronized time that monotonically increases). These are thin wrappers are the std::chrono equivalents for the primary purpose of supporting simulation time that can proceed at a multiplier of real time.

For maximizing capability with other projects, Goby supports conversion (using the convert family of functions) amongst SystemClock and two other time representations: boost::units::quantity of time (e.g. boost::units::quantity<boost::units::si::time>) and boost::posix_time::ptime. DCCL uses the boost::units representation, and boost::posix_time::ptime was used by numerous projects prior to the release of std::chrono (and is still necessary until C++20 for its date functionality).

SystemClock (and std::chrono) distinguish between a time_point (an absolute point in time, e.g. July 31, 2019 at 11:45:32) and a time duration (e.g. 3 hours and 23 minutes). This distinction is not supported when using boost::units::quantity of time, so when calling the convert_duration functions, a boost::units::quantity of time represents a duration, whereas when calling the convert functions, a boost::units::quantity of time represents the number of seconds since the UNIX epoch (1970 Jan 1 at 00:00:00 UTC).

Typedef Documentation

◆ MicroTime

using goby::time::MicroTime = typedef boost::units::quantity<MicroTimeUnit, std::int64_t>

quantity of microseconds (using int64)

Definition at line 39 of file types.h.

◆ MicroTimeUnit

using goby::time::MicroTimeUnit = typedef decltype(boost::units::si::micro* boost::units::si::seconds)

microsecond unit

Definition at line 37 of file types.h.

◆ SITime

using goby::time::SITime = typedef boost::units::quantity<boost::units::si::time, double>

quantity of seconds (using double)

Definition at line 41 of file types.h.

Function Documentation

◆ convert() [1/3]

template<typename ToTimeType , typename FromTimeType , typename std::enable_if< std::is_same< ToTimeType, FromTimeType >{}, int >::type = 0>
ToTimeType goby::time::convert ( FromTimeType  from_time)

Convert between time representations (this function works for tautological conversions)

Convert between time representations (this function converts from a boost::posix_time::ptime to a time type supported by the other convert functions)

Convert between time representations (this function converts from a time type supported by the other convert functions to a boost::posix_time::ptime)

Template Parameters
ToTimeTypeThe type of the returned (converted) time
FromTimeTypeThe type of the input time
Parameters
from_timeTime to convert
Returns
Converted time

Definition at line 49 of file convert.h.

◆ convert() [2/3]

template<typename ToTimeType , typename FromTimeType , typename ToUnitType = typename ToTimeType::unit_type, typename ToValueType = typename ToTimeType::value_type, typename FromUnitType = typename FromTimeType::unit_type, typename FromValueType = typename FromTimeType::value_type, typename std::enable_if< !std::is_same< ToTimeType, FromTimeType >{} &&std::is_same< ToTimeType, boost::units::quantity< ToUnitType, ToValueType >>{} &&std::is_same< FromTimeType, boost::units::quantity< FromUnitType, FromValueType >>{}, int >::type = 0>
ToTimeType goby::time::convert ( FromTimeType  from_time)

Convert between time representations (this function converts between two different boost::units::quantity of time)

Template Parameters
ToTimeTypeThe type of the returned (converted) time
FromTimeTypeThe type of the input time
Parameters
from_timeTime to convert
Returns
Converted time

Definition at line 70 of file convert.h.

◆ convert() [3/3]

template<typename ToTimeType , typename FromTimeType , typename ToUnitType = typename ToTimeType::unit_type, typename ToValueType = typename ToTimeType::value_type, typename std::enable_if< std::is_same< ToTimeType, boost::units::quantity< ToUnitType, ToValueType >>{} &&(std::is_same< FromTimeType, SystemClock::time_point >{}||std::is_same< FromTimeType, std::chrono::system_clock::time_point >{}), int >::type = 0>
ToTimeType goby::time::convert ( FromTimeType  from_time)

Convert between time representations (this function converts to a boost::units::quantity of time from either a chrono::system_clock::time_point or a goby::time::SystemClock::time_point)

Convert between time representations (this function converts to either a chrono::system_clock::time_point or a goby::time::SystemClock::time_point from a boost::units::quantity of time)

Template Parameters
ToTimeTypeThe type of the returned (converted) time
FromTimeTypeThe type of the input time
Parameters
from_timeTime to convert
Returns
Converted time

Definition at line 89 of file convert.h.

◆ convert_duration() [1/2]

template<typename ToDurationType , typename FromDurationType , typename std::enable_if< std::is_same< ToDurationType, FromDurationType >{}, int >::type = 0>
ToDurationType goby::time::convert_duration ( FromDurationType  from_duration)

Convert between duration representations (this function works for tautological conversions)

Template Parameters
ToDurationTypeThe type of the returned (converted) duration
FromDurationTypeThe type of the input duration
Parameters
from_durationDuration to convert
Returns
Converted duration

Definition at line 218 of file convert.h.

◆ convert_duration() [2/2]

template<typename ToDurationType , typename FromDurationType , typename ToUnitType = typename ToDurationType::unit_type, typename ToValueType = typename ToDurationType::value_type, typename FromUnitType = typename FromDurationType::unit_type, typename FromValueType = typename FromDurationType::value_type, typename std::enable_if< !std::is_same< ToDurationType, FromDurationType >{} &&std::is_same< ToDurationType, boost::units::quantity< ToUnitType, ToValueType >>{} &&std::is_same< FromDurationType, boost::units::quantity< FromUnitType, FromValueType >>{}, int >::type = 0>
ToDurationType goby::time::convert_duration ( FromDurationType  from_duration)

Convert between duration representations (this function converts between two different boost::units::quantity of time)

Convert between duration representations (this function converts from boost::units::quantity of time to std::chrono::duration.

Convert between duration representations (this function converts from std::chrono::duration to boost::units::quantity of time)

Template Parameters
ToDurationTypeThe type of the returned (converted) duration
FromDurationTypeThe type of the input duration
Parameters
from_durationDuration to convert
Returns
Converted duration

Definition at line 240 of file convert.h.

◆ convert_from_nmea() [1/2]

template<typename ToTimeType >
ToTimeType goby::time::convert_from_nmea ( const std::string &  utc,
boost::gregorian::date  return_date = boost::gregorian::day_clock::universal_day() 
)

Convert from NMEA0183 time representations (i.e. "HHMMSS[.SSSS]") to any time format supported by the goby::time::convert function family. This function assumes the time is from the current day.

Template Parameters
ToTimeTypeThe type of the returned (converted) time
Parameters
utcNMEA0183 time of day as string (e.g. "124511" or "124511.1234" with variable fractional seconds up and including microsecond precision
return_dateDate assigned to the input time when returned as a time point (defaults to the current day in UTC)
Returns
Converted time

Definition at line 300 of file convert.h.

◆ convert_from_nmea() [2/2]

template<typename ToTimeType >
ToTimeType goby::time::convert_from_nmea ( const std::string &  utc,
const std::string &  date 
)

Convert from NMEA0183 time representations (i.e. "HHMMSS[.SSSS]") to any time format supported by the goby::time::convert function family. This function assumes the time is from the current day.

Template Parameters
ToTimeTypeThe type of the returned (converted) time
Parameters
utcNMEA0183 time of day as string (e.g. "124511" or "124511.1234" with variable fractional seconds up and including microsecond precision
dateNMEA0183 date as string (e.g. "120120" for December 01, 2020)
Returns
Converted time

Definition at line 349 of file convert.h.

◆ file_str()

template<typename TimeType = SystemClock::time_point>
std::string goby::time::file_str ( TimeType  value = SystemClock::now<TimeType>())
inline

Returns the provided time (or current time if omitted) as an ISO string suitable for file names (no spaces or special characters, e.g. 20180322T215258)

Template Parameters
TimeTypeThe type of the input time
Parameters
valueTime to convert
Returns
Time formatted in a way suitable for file names

Definition at line 204 of file convert.h.

◆ operator<<() [1/3]

std::ostream& goby::time::operator<< ( std::ostream &  out,
const goby::time::SteadyClock::time_point time 
)
inline

Definition at line 40 of file io.h.

◆ operator<<() [2/3]

std::ostream& goby::time::operator<< ( std::ostream &  out,
const goby::time::SystemClock::duration duration 
)
inline

Definition at line 47 of file io.h.

◆ operator<<() [3/3]

std::ostream& goby::time::operator<< ( std::ostream &  out,
const goby::time::SystemClock::time_point time 
)
inline

Definition at line 36 of file io.h.

◆ str()

template<typename TimeType = SystemClock::time_point>
std::string goby::time::str ( TimeType  value = SystemClock::now<TimeType>())
inline

Returns the provided time (or current time if omitted) as a human-readable string.

Template Parameters
TimeTypeThe type of the input time
Parameters
valueTime to convert
Returns
Time formatted as a human readable string (e.g. for debug logging)

Definition at line 191 of file convert.h.