Various tools for working with time

Modules
	Putting a thread to sleep

	Timespec comparisons

Files
file	sofa.hpp
	Wrapper for the sofa library headers, adding a namespace.

Functions
template<typename typeT = double, clockid_t clk_id = CLOCK_REALTIME>
typeT	mx::sys::get_curr_time (timespec &tsp)
	Get the current system time in seconds. More...

template<typename typeT = double, clockid_t clk_id = CLOCK_REALTIME>
typeT	mx::sys::get_curr_time ()
	Get the current system time in seconds. More...

void	mx::sys::timespecAddNsec (timespec &ts, unsigned nsec)
	Adds a time offset to an existing timespec. More...

template<typename floatT >
void	mx::sys::parse_hms (floatT &h, floatT &m, floatT &s, const std::string &hmsstr)

double	mx::sys::Cal2mjd (int yr, int mon, int day, int hr, int min, double sec)
	Converts a Gregorian calendar date into modified Julian date (MJD). More...

int	mx::sys::ISO8601dateBreakdown (int &yr, int &mon, int &day, int &hr, int &min, double &sec, const std::string &fdate)
	Parse an ISO8601 date of the form "YYYY-MM-DDTHH:MM:SS.S" into the individual components. More...

double	mx::sys::ISO8601date2mjd (const std::string &fdate)
	Parse an ISO8601 date of the form "YYYY-MM-DDTHH:MM:SS.S" and return the modified Julian date (MJD) More...

template<typename timeT >
std::string	mx::sys::ISO8601DateTimeStr (const timeT &timeIn, int timeZone=0)
	Get a date-time string in ISO 8601 format. More...

template<>
std::string	mx::sys::ISO8601DateTimeStr< time_t > (const time_t &timeIn, int timeZone)
	Get a date-time string in ISO 8601 format for time_t. More...

template<>
std::string	mx::sys::ISO8601DateTimeStr< timespec > (const timespec &timeIn, int timeZone)
	Get a date-time string in ISO 8601 format for timespec. More...

std::string	mx::sys::ISO8601DateTimeStr (int timeZone=0)
	Get a date-time string in ISO 8601 format for the current UTC time. More...

std::string	mx::sys::ISO8601DateTimeStrMJD (const double &timeIn, int timeZone=0)
	Get a date-time string in ISO 8601 format for an MJD. More...

int	mx::sys::timeStamp (std::string &tstamp, timespec &ts)
	Get a timestamp string in the form YYYYMMDDHHMMSS.SSSSSSSSS. More...

int	mx::sys::timespecUTC2TAIMJD (double &djm, double &djmf, const timespec &tsp, tm *tm0)
	Convert a UTC timespec to TAI modified Julian date. More...

Function Documentation

◆ Cal2mjd()

double mx::sys::Cal2mjd	(	int	yr,
		int	mon,
		int	day,
		int	hr,
		int	min,
		double	sec
	)

Converts a Gregorian calendar date into modified Julian date (MJD).

Uses the SOFA function iauCal2jd. This is not a template in floating point because SOFA is always double precision.

Return values

double	containing the MJD
<0	on error (-1 = bad year, -2 = bad month, -3 = bad day)

Test:: Verify calculation of MJD. [test doc]

Parameters

[in]	yr	Gregorian calendar year
[in]	mon	Gregorian calendar month
[in]	day	Gregorian calendar day
[in]	hr	Gregorian calendar hour
[in]	min	Gregorian calendar minute
[in]	sec	Gregorian calendar second

Definition at line 85 of file timeUtils.cpp.

References mx::astro::constants::day().

Referenced by mx::sys::ISO8601date2mjd(), and SCENARIO().

◆ get_curr_time() [1/2]

template<typename typeT = double, clockid_t clk_id = CLOCK_REALTIME>

typeT mx::sys::get_curr_time ( )

Get the current system time in seconds.

Uses timespec, so nanosecond resolution is possible. This version creates a timespec internally.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Template Parameters

typeT	is the type to return the time in [default=double]. must have cast from integer types, and + and / operators defined.
clk_id	is the sys/time.h clock identifier [default=CLOCK_REALTIME]

Return values

typeT containing the current time in seconds

Test:: Verify operation of get_curr_time. [test doc]

Definition at line 91 of file timeUtils.hpp.

◆ get_curr_time() [2/2]

template<typename typeT = double, clockid_t clk_id = CLOCK_REALTIME>

typeT mx::sys::get_curr_time ( timespec & tsp )

Get the current system time in seconds.

Uses timespec, so nanosecond resolution is possible.

Template Parameters

typeT	is the type to return the time in [default=double]. must have cast from integer types, and + and / operators defined.
clk_id	is the sys/time.h clock identifier [default=CLOCK_REALTIME]

Return values

typeT containing the current time in seconds

Test:: Verify operation of get_curr_time. [test doc]

Parameters

[out] tsp a timespec to populate with the current time

Definition at line 63 of file timeUtils.hpp.

Referenced by mx::ipc::ompLoopWatcher< _outputT, _printPretty, _printLoops, _printPercent, _printNLine, _time >::ompLoopWatcher(), mx::ipc::ompLoopWatcher< _outputT, _printPretty, _printLoops, _printPercent, _printNLine, _time >::_advance(), mx::ipc::ompLoopWatcher< _outputT, _printPretty, _printLoops, _printPercent, _printNLine, _time >::_increment(), mx::improc::HCIobservation< _realT >::coaddImages(), mx::improc::HCIobservation< _realT >::combineFinim(), mx::improc::ADIobservation< _realT, _derotFunctObj >::derotate(), mx::improc::ADIobservation< _realT, _derotFunctObj >::injectFake(), mx::improc::HCIobservation< _realT >::preProcess(), mx::improc::HCIobservation< _realT >::readFiles(), mx::improc::HCIobservation< _realT >::readPSFSub(), mx::improc::HCIobservation< _realT >::readRDIFiles(), mx::improc::KLIPreduction< _realT, _derotFunctObj, _evCalcT >::regions(), SCENARIO(), mx::AO::sim::simulatedAOSystem< _realT, _wfsT, _reconT, _filterT, _dmT, _turbSeqT, _coronT >::takeResponseMatrix(), and mx::improc::KLIPreduction< _realT, _derotFunctObj, _evCalcT >::worker().

◆ ISO8601date2mjd()

double mx::sys::ISO8601date2mjd ( const std::string & fdate )

Parse an ISO8601 date of the form "YYYY-MM-DDTHH:MM:SS.S" and return the modified Julian date (MJD)

Parsing is currently only for the exact form above, which is the form in a FITS file. See https://en.wikipedia.org/?title=ISO_8601. After parsing calls Cal2mjd.

Test:: Verify conversion of an ISO 8601 time string to MJD. [test doc]

Parameters

[in] fdate a standard ISO8601 date string

Definition at line 132 of file timeUtils.cpp.

References mx::sys::Cal2mjd(), mx::astro::constants::day(), and mx::sys::ISO8601dateBreakdown().

Referenced by mx::improc::HCIobservation< _realT >::readFiles(), mx::improc::HCIobservation< _realT >::readPSFSub(), mx::improc::HCIobservation< _realT >::readRDIFiles(), and SCENARIO().

◆ ISO8601dateBreakdown()

int mx::sys::ISO8601dateBreakdown	(	int &	yr,
		int &	mon,
		int &	day,
		int &	hr,
		int &	min,
		double &	sec,
		const std::string &	fdate
	)

Parse an ISO8601 date of the form "YYYY-MM-DDTHH:MM:SS.S" into the individual components.

Parsing is currently only for the exact form above, which is the form in a FITS file. See https://en.wikipedia.org/?title=ISO_8601.

Returns: 0 on success; -4 if fdate is not long enough

Test:: Verify parsing of an ISO 8601 time string [test doc]

Parameters

[out]	yr	Gregorian calendar year
[out]	mon	Gregorian calendar month
[out]	day	Gregorian calendar day
[out]	hr	Gregorian calendar hour
[out]	min	Gregorian calendar minute
[out]	sec	Gregorian calendar second
[in]	fdate	is a standard ISO8601 date string

Definition at line 106 of file timeUtils.cpp.

References mx::astro::constants::day(), and mx::sys::parse_hms().

Referenced by mx::sys::ISO8601date2mjd(), and SCENARIO().

◆ ISO8601DateTimeStr() [1/2]

template<typename timeT >

std::string mx::sys::ISO8601DateTimeStr	(	const timeT &	timeIn,
		int	timeZone = `0`
	)

Get a date-time string in ISO 8601 format.

For recognized time types, returns a string in the ISO 8601 format: YYYY-MM-DDYHH:MM:SS.SS, with optional timezone designation such as Z or +00:00.

Template Parameters

timeT is the time type

Return values

std::string containing the format date/time

Parameters

[in]	timeIn	the input time
[in]	timeZone	[optional] specifies whether to include a timezone designation. 0=> none, 1=> letter, 2=>offset.

References mx::sys::meanTimespec().

◆ ISO8601DateTimeStr() [2/2]

std::string mx::sys::ISO8601DateTimeStr ( int timeZone = 0 )

Get a date-time string in ISO 8601 format for the current UTC time.

Returns a string in the ISO 8601 format: YYYY-MM-DDYHH:MM:SS.SS, with optional timezone designation such as Z or +00:00.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Return values

std::string containing the format date/time

Parameters

[in] timeZone [optional] specifies whether to include a timezone designation. 0=> none, 1=> letter, 2=>offset.

Definition at line 185 of file timeUtils.cpp.

References mx::sys::ISO8601DateTimeStr< time_t >().

◆ ISO8601DateTimeStr< time_t >()

template<>

std::string mx::sys::ISO8601DateTimeStr< time_t >	(	const time_t &	timeIn,
		int	timeZone
	)

Get a date-time string in ISO 8601 format for time_t.

Returns a string in the ISO 8601 format: YYYY-MM-DDYHH:MM:SS, with optional timezone designation such as Z or +00:00.

Return values

std::string containing the format date/time

Parameters

[in]	timeIn	the input time
[in]	timeZone	[optional] specifies whether to include a timezone designation. 0=> none, 1=> letter, 2=>offset.

Definition at line 147 of file timeUtils.cpp.

Referenced by mx::sys::ISO8601DateTimeStr(), and mx::sys::ISO8601DateTimeStr< timespec >().

◆ ISO8601DateTimeStr< timespec >()

template<>

std::string mx::sys::ISO8601DateTimeStr< timespec >	(	const timespec &	timeIn,
		int	timeZone
	)

Get a date-time string in ISO 8601 format for timespec.

Returns a string in the ISO 8601 format: YYYY-MM-DDYHH:MM:SS.SSSSSSSSS, with optional timezone designation such as Z or +00:00.

Return values

std::string containing the format date/time

Parameters

[in]	timeIn	the input time
[in]	timeZone	[optional] specifies whether to include a timezone designation. 0=> none, 1=> letter, 2=>offset.

Definition at line 167 of file timeUtils.cpp.

References mx::sys::ISO8601DateTimeStr< time_t >().

◆ ISO8601DateTimeStrMJD()

std::string mx::sys::ISO8601DateTimeStrMJD	(	const double &	timeIn,
		int	timeZone = `0`
	)

Get a date-time string in ISO 8601 format for an MJD.

Returns a string in the ISO 8601 format: YYYY-MM-DDYHH:MM:SS.SSSSSSSSS, with optional timezone designation such as Z or +00:00.

Return values

std::string containing the format date/time

Parameters

[in]	timeIn	the input time
[in]	timeZone	specifies whether to include a timezone designation. 0=> none, 1=> letter, 2=>offset.

Definition at line 190 of file timeUtils.cpp.

◆ parse_hms()

template<typename floatT >

void mx::sys::parse_hms	(	floatT &	h,
		floatT &	m,
		floatT &	s,
		const std::string &	hmsstr
	)

Parse a string of format hh:mm:ss.s Breaks a time string into constituent parts. Handles -h by distributing the sign to m and s.

Template Parameters

floatT is a floating point type

Test:: Verify parsing of a formatted time string. [test doc]

Parameters

[out]	h	the hour component coverted to floatT
[out]	m	the minute component converted to floatT
[out]	s	the second component converted to floatT
[in]	hmsstr	a string of format hh:mm:ss.s where ss.s can be of any precision

Definition at line 155 of file timeUtils.hpp.

References mx::astro::constants::h().

Referenced by mx::sys::ISO8601dateBreakdown(), and SCENARIO().

◆ timespecAddNsec()

void mx::sys::timespecAddNsec	(	timespec &	ts,
		unsigned	nsec
	)

Adds a time offset to an existing timespec.

The offset is specified in nanoseconds, which can be greater than 1e9.

Test:: Verify operation of timespecAddNsec. [test doc]

Parameters

	ts	[in.out] the time to add to
[in]	nsec	the number of nanoseconds to add to ts.

Definition at line 71 of file timeUtils.cpp.

Referenced by SCENARIO().

◆ timespecUTC2TAIMJD()

int mx::sys::timespecUTC2TAIMJD	(	double &	djm,
		double &	djmf,
		const timespec &	tsp,
		tm *	tm0
	)

Convert a UTC timespec to TAI modified Julian date.

Converts a timespec assumed to be in Coordinated Universal Time (UTC) to a Modified Julian Date (MJD) in International Atomic Time (TAI).

Return values

1	SOFA dubious year [see SOFA documentation for iauDat]
0	success
-1	SOFA bad year [see SOFA documentation for iauDat and iauCal2jd]
-2	SOFA bad month [see SOFA documentation for iauDat and iauCal2jd]
-3	SOFA bad day [see SOFA documentation for iauDat and iauCal2jd]
-4	SOFA bad fractional day [see SOFA documentation for iauDat and iauCal2jd]
-5	SOFA internal error [see SOFA documentation for iauDat and iauCal2jd]
-10	gmtime_r returned error, check errno

Parameters

[out]	djm	the modified Julian day number
[out]	djmf	the fraction of the day
[in]	tsp	contains the UTC time
[out]	tm0	[optional] will be filled with the broken down UTC time

Definition at line 243 of file timeUtils.cpp.

◆ timeStamp()

int mx::sys::timeStamp	(	std::string &	tstamp,
		timespec &	ts
	)

Get a timestamp string in the form YYYYMMDDHHMMSS.SSSSSSSSS.

Assumes the input timespec is in UTC.

Returns: 0 on success; -1 on error.

Parameters

[out]	tstamp	the string to hold the formatted time
[in]	ts	the timespec from which to produce the timestamp string

Definition at line 220 of file timeUtils.cpp.

Modules

Files

Functions

Function Documentation

◆ Cal2mjd()

◆ get_curr_time() [1/2]

◆ get_curr_time() [2/2]

◆ ISO8601date2mjd()

◆ ISO8601dateBreakdown()

◆ ISO8601DateTimeStr() [1/2]

◆ ISO8601DateTimeStr() [2/2]

◆ ISO8601DateTimeStr< time_t >()

◆ ISO8601DateTimeStr< timespec >()

◆ ISO8601DateTimeStrMJD()

◆ parse_hms()

◆ timespecAddNsec()

◆ timespecUTC2TAIMJD()

◆ timeStamp()