Class for handling dates/times, including MJD, UTC, and TAI. More...

#include <DateTime.h>

Public Types
enum	DateSystem { JD = 0, MJD, EPOCH }

enum	Timescale { TAI = 5, UTC, TT }

Public Member Functions
	DateTime ()
	Default constructor: construct an invalid DateTime. More...

	DateTime (long long nsecs, Timescale scale=TAI)
	Construct a DateTime from nanoseconds since the unix epoch. More...

	DateTime (double date, DateSystem system=MJD, Timescale scale=TAI)
	Construct a DateTime from a double in the specified system and scale. More...

	DateTime (int year, int month, int day, int hr, int min, int sec, Timescale scale=TAI)
	Construct a DateTime from year, month, day, etc. More...

	DateTime (std::string const &iso8601, Timescale scale)
	Construct a DateTime from an ISO8601 string. More...

long long	nsecs (Timescale scale=TAI) const
	Get date as nanoseconds since the unix epoch. More...

double	get (DateSystem system=MJD, Timescale scale=TAI) const
	Get date as a double in a specified representation, such as MJD. More...

std::string	toString (Timescale scale) const
	Get date as an ISO8601-formatted string. More...

struct tm	gmtime (Timescale scale) const
	Get date as a tm struct, with truncated fractional seconds. More...

struct timespec	timespec (Timescale scale) const
	Get date as a timespec struct, with time in seconds and nanoseconds. More...

struct timeval	timeval (Timescale scale) const
	Get date as a timeval struct, with time in seconds and microseconds. More...

bool	isValid () const
	Is this date valid? More...

bool	operator== (DateTime const &rhs) const

std::size_t	hash_value () const noexcept
	Return a hash of this object. More...

Static Public Member Functions
static DateTime	now (void)
	Return current time as a DateTime. More...

static void	initializeLeapSeconds (std::string const &leapString)
	Initialize the leap second table from USNO. More...

Static Public Attributes
static constexpr long long	invalid_nsecs = std::numeric_limits<std::int64_t>::min()

Friends
class	boost::serialization::access

Detailed Description

Class for handling dates/times, including MJD, UTC, and TAI.

Definition at line 64 of file DateTime.h.

Member Enumeration Documentation

◆ DateSystem

enum lsst::daf::base::DateTime::DateSystem

Enumerator
JD
MJD
EPOCH

Definition at line 66 of file DateTime.h.

◆ Timescale

enum lsst::daf::base::DateTime::Timescale

Enumerator
TAI
UTC
TT

Definition at line 67 of file DateTime.h.

Constructor & Destructor Documentation

◆ DateTime() [1/5]

lsst::daf::base::DateTime::DateTime ( )

explicit

Default constructor: construct an invalid DateTime.

Definition at line 306 of file DateTime.cc.

◆ DateTime() [2/5]

lsst::daf::base::DateTime::DateTime	(	long long	nsecs,
		Timescale	scale = `TAI`
	)

explicit

Construct a DateTime from nanoseconds since the unix epoch.

Parameters

[in]	nsecs	integer nanoseconds since the unix epoch; if nsecs == DateTime.invalid_nsecs then the DateTime is invalid, regardless of scale
[in]	scale	time scale of input (TAI, TT or UTC, default TAI).

Exceptions

lsst.pex.exceptions.DomainError if scale is UTC and the date is before 1961-01-01

Definition at line 308 of file DateTime.cc.

◆ DateTime() [3/5]

lsst::daf::base::DateTime::DateTime	(	double	date,
		DateSystem	system = `MJD`,
		Timescale	scale = `TAI`
	)

explicit

Construct a DateTime from a double in the specified system and scale.

Parameters

[in]	date	specified date
[in]	system	time system of input (JD, MJD, or EPOCH)
[in]	scale	time scale of input (TAI, TT or UTC, default TAI).

Exceptions

lsst.pex.exceptions.DomainError if scale is UTC and the date is before 1961-01-01

Definition at line 310 of file DateTime.cc.

◆ DateTime() [4/5]

lsst::daf::base::DateTime::DateTime	(	int	year,
		int	month,
		int	day,
		int	hr,
		int	min,
		int	sec,
		Timescale	scale = `TAI`
	)

Construct a DateTime from year, month, day, etc.

(tm struct fields)

Parameters

[in]	year	year; must be in the range [1902, 2261], inclusive.
[in]	month	month number, where January = 1
[in]	day	day of the month (1 to 31).
[in]	hr	hour (0 to 23)
[in]	min	minute (0 to 59)
[in]	sec	integer seconds (0 to 60)
[in]	scale	time scale of input (TAI, TT or UTC, default TAI).

Exceptions

lsst.pex.exceptions.DomainError if year is < 1902 or > 2261, or if scale is UTC and the date is before 1961-01-01 (the start of the leap second table)

Definition at line 327 of file DateTime.cc.

◆ DateTime() [5/5]

lsst::daf::base::DateTime::DateTime	(	std::string const &	iso8601,
		Timescale	scale
	)

explicit

Construct a DateTime from an ISO8601 string.

Accepts a restricted subset of ISO8601: yyyy-mm-ddThh:mm:ss.nnnnnnnnnZ where:

the final Z is required for UTC and prohibited for TAI or TT
the - and : separators are optional
the decimal point and fractional seconds are optional
the decimal point may be a comma

Parameters

[in]	iso8601	ISO8601 string representation of date and time
[in]	scale	time scale of input (TAI, TT or UTC, default TAI).

Exceptions

lsst.pex.exceptions.DomainError if year is < 1902 or > 2261, or if scale is UTC and the date is before 1961-01-01 (the start of the leap second table)

Definition at line 385 of file DateTime.cc.

Member Function Documentation

◆ get()

double lsst::daf::base::DateTime::get	(	DateSystem	system = `MJD`,
		Timescale	scale = `TAI`
	)		const

Get date as a double in a specified representation, such as MJD.

Returns: the date in the required system, for the requested scale

Parameters

[in]	system	desired time system (JD, MJD, or EPOCH)
[in]	scale	desired time scale (TAI, TT or UTC)

Exceptions

lsst.pex.exceptions.DomainError	if scale is UTC and the UTC date is before 1961-01-01
lsst.pex.exceptions.RuntimeError	if DateTime is invalid

Definition at line 429 of file DateTime.cc.

◆ gmtime()

struct tm lsst::daf::base::DateTime::gmtime ( Timescale scale ) const

Get date as a tm struct, with truncated fractional seconds.

Parameters

[in] scale desired time scale (TAI, TT or UTC)

Returns: date as a tm struct

Exceptions

lsst.pex.exceptions.DomainError	if scale is UTC and the UTC date is before 1961-01-01
lsst.pex.exceptions.RuntimeError	if DateTime is invalid

Definition at line 465 of file DateTime.cc.

◆ hash_value()

std::size_t lsst::daf::base::DateTime::hash_value ( ) const

noexcept

Return a hash of this object.

Definition at line 515 of file DateTime.cc.

◆ initializeLeapSeconds()

void lsst::daf::base::DateTime::initializeLeapSeconds ( std::string const & leapString )

static

Initialize the leap second table from USNO.

The data can be found here: http://maia.usno.navy.mil/ser7/tai-utc.dat and is saved in DateTime.cc as static constant leapString.

Parameters

leapString leap second table from USNO as a single multiline string.

Definition at line 527 of file DateTime.cc.

◆ isValid()

bool lsst::daf::base::DateTime::isValid ( ) const

inline

Is this date valid?

Definition at line 202 of file DateTime.h.

◆ now()

DateTime lsst::daf::base::DateTime::now ( void )

static

Return current time as a DateTime.

Assumes the system clock keeps UTC, as almost all computers do.

Definition at line 517 of file DateTime.cc.

◆ nsecs()

long long lsst::daf::base::DateTime::nsecs ( Timescale scale = TAI ) const

Get date as nanoseconds since the unix epoch.

Note: If the DateTime is invalid then the returned value is DateTime.invalid_nsecs, regardless of scale.

Parameters

[in] scale desired time scale (TAI, TT or UTC)

Returns: the date as nanoseconds since the unix epoch in the specified time scale

Exceptions

lsst.pex.exceptions.DomainError if scale is UTC and the UTC date is before 1961-01-01

Definition at line 447 of file DateTime.cc.

◆ operator==()

bool lsst::daf::base::DateTime::operator== ( DateTime const & rhs ) const

Definition at line 513 of file DateTime.cc.

◆ timespec()

struct timespec lsst::daf::base::DateTime::timespec ( Timescale scale ) const

Get date as a timespec struct, with time in seconds and nanoseconds.

Parameters

[in] scale Desired time scale (TAI, TT or UTC)

Returns: date as a timespec struct

Exceptions

lsst.pex.exceptions.DomainError	if scale is UTC and the UTC date is before 1961-01-01
lsst.pex.exceptions.RuntimeError	if DateTime is invalid

Definition at line 481 of file DateTime.cc.

◆ timeval()

struct timeval lsst::daf::base::DateTime::timeval ( Timescale scale ) const

Get date as a timeval struct, with time in seconds and microseconds.

Parameters

[in] scale desired time scale (TAI, TT or UTC)

Returns: date as a timeval struct

Exceptions

lsst.pex.exceptions.DomainError	if scale is UTC and the UTC date is before 1961-01-01
lsst.pex.exceptions.RuntimeError	if DateTime is invalid

Definition at line 490 of file DateTime.cc.

◆ toString()

std::string lsst::daf::base::DateTime::toString ( Timescale scale ) const

Get date as an ISO8601-formatted string.

The returned format is: yyyy-mm-ddThh:mm:ss.sssssssssZ where the final Z is only present if scale is UTC

Parameters

[in] scale Desired time scale (TAI, TT or UTC).

Exceptions

lsst.pex.exceptions.DomainError	if scale is UTC and the UTC date is before 1961-01-01
lsst.pex.exceptions.RuntimeError	if DateTime is invalid

Definition at line 499 of file DateTime.cc.

Friends And Related Function Documentation

◆ boost::serialization::access

friend class boost::serialization::access

friend

Definition at line 289 of file DateTime.h.

Member Data Documentation

◆ invalid_nsecs

constexpr long long lsst::daf::base::DateTime::invalid_nsecs = std::numeric_limits<std::int64_t>::min()

static

Definition at line 74 of file DateTime.h.

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

include/lsst/daf/base/DateTime.h
src/DateTime.cc

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ DateSystem

◆ Timescale

Constructor & Destructor Documentation

◆ DateTime() [1/5]

◆ DateTime() [2/5]

◆ DateTime() [3/5]

◆ DateTime() [4/5]

◆ DateTime() [5/5]

Member Function Documentation

◆ get()

◆ gmtime()

◆ hash_value()

◆ initializeLeapSeconds()

◆ isValid()

◆ now()

◆ nsecs()

◆ operator==()

◆ timespec()

◆ timeval()

◆ toString()

Friends And Related Function Documentation

◆ boost::serialization::access

Member Data Documentation

◆ invalid_nsecs