lsst::daf::base::DateTime Class Reference

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
constexpr static 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.

{ JD = 0, MJD, EPOCH };  // EPOCH is Julian epoch year

Timescale

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

Enumerator
TAI
UTC
TT

Definition at line 68 of file DateTime.h.

                   {
        TAI = 5,
        UTC,
        TT
    };  // use values that do not overlap DateSystem

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.

: _nsecs(DateTime::invalid_nsecs) {}

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.

: _nsecs(nsecAnyToTai(nsecs, scale)) {}

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 [Julian] 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.

                                                                  {
    switch (system) {
        case MJD:
            setNsecsFromMjd(date, scale);
            break;
        case JD:
            setNsecsFromJd(date, scale);
            break;
        case EPOCH:
            setNsecsFromEpoch(date, scale);
            break;
        default:
            throw LSST_EXCEPT(pexEx::InvalidParameterError, "DateSystem must be MJD, JD, or EPOCH");
            break;
    }
}

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.

                                                                                          {
    int const minYear = 1902;
    int const maxYear = 2261;
    if ((year < minYear) || (year > maxYear)) {
        throw LSST_EXCEPT(
                lsst::pex::exceptions::DomainError,
                (boost::format("Year = %d out of range [%04d, %04d]") % year % minYear % maxYear).str());
    }
 
    struct tm tm;
    tm.tm_year = year - 1900;
    tm.tm_mon = month - 1;
    tm.tm_mday = day;
    tm.tm_hour = hr;
    tm.tm_min = min;
    tm.tm_sec = sec;
    tm.tm_wday = 0;
    tm.tm_yday = 0;
    tm.tm_isdst = 0;
    tm.tm_gmtoff = 0;
 
    // Convert to seconds since the epoch, correcting to UTC.
    // Although timegm() is non-standard, it is a commonly-supported
    // extension and is much safer/more reliable than mktime(3) in that
    // it doesn't try to deal with the anomalies of local time zones.
    time_t secs = timegm(&tm);
 
    // long long nsecs will blow out beyond 1677-09-21T00:00:00 and 2262-04-12T00:00:00
    // (refering to the values of EPOCH_IN_MJD +/- MAX_DAYS ... exceeds 64 bits.)
    // On older machines a tm struct is only 32 bits, and saturates at:
    //    low end - 1901-12-13, 20:45:52
    //    hi end  - 2038-01-19, 03:14:07
    // On newer machines the upper limit is a date in 2262, but the low end is unchanged,
    // and a unit test will show the problem for dates later than 2038-01-19
 
    // timegm returns -1 on error, but the date at unix epoch -1 second also returns a valid value of -1,
    // so be sure to test for that
 
    if (secs == -1) {
        bool isBad = true;  // assume the worst
        if (year == 1969) {
            // date may be the one date at which unix sec = -1; try a different year
            tm.tm_year = 70;
            if (timegm(&tm) != -1) {
                isBad = false;
            }
        }
        if (isBad) {
            throw LSST_EXCEPT(lsst::pex::exceptions::DomainError,
                              (boost::format("Unconvertible date: %04d-%02d-%02dT%02d:%02d:%02d") % year %
                               month % day % hr % min % sec)
                                      .str());
        }
    }
 
    _nsecs = nsecAnyToTai(secs * LL_NSEC_PER_SEC, scale);
}

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.

                                                            {
    boost::regex re;
    if (scale == UTC) {
        // time zone "Z" required
        re = boost::regex(
                "(\\d{4})-?(\\d{2})-?(\\d{2})"
                "T"
                "(\\d{2}):?(\\d{2}):?(\\d{2})"
                "([.,](\\d*))?"
                "Z");
    } else {
        // no time zone character accepted
        re = boost::regex(
                "(\\d{4})-?(\\d{2})-?(\\d{2})"
                "T"
                "(\\d{2}):?(\\d{2}):?(\\d{2})"
                "([.,](\\d*))?");
    }
    boost::smatch matches;
    if (!regex_match(iso8601, matches, re)) {
        throw LSST_EXCEPT(lsst::pex::exceptions::DomainError, "Not in acceptable ISO8601 format: " + iso8601);
    }
    // determine TAI nsec truncated to integer seconds
    // by constructing a DateTime from year, month, day...
    DateTime dt(atoi(matches.str(1).c_str()), atoi(matches.str(2).c_str()), atoi(matches.str(3).c_str()),
                atoi(matches.str(4).c_str()), atoi(matches.str(5).c_str()), atoi(matches.str(6).c_str()),
                scale);
    _nsecs = dt._nsecs;
    // add fractional seconds, if any
    if (matches[7].matched) {
        std::string frac = matches.str(8);
        int places = frac.size();
        if (places > 9) {  // truncate fractional nanosec
            frac.erase(9);
        }
        int value = atoi(frac.c_str());
        while (places < 9) {
            value *= 10;
            ++places;
        }
        _nsecs += value;
    }
}

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 [Julian] 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.

                                                             {
    _assertValid();
    switch (system) {
        case MJD:
            return _getMjd(scale);
            break;
        case JD:
            return _getJd(scale);
            break;
        case EPOCH:
            return _getEpoch(scale);
            break;
        default:
            throw LSST_EXCEPT(pexEx::InvalidParameterError, "DateSystem must be MJD, JD, or EPOCH");
            break;
    }
}

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 463 of file DateTime.cc.

                                                {
    _assertValid();
    struct tm gmt;
    long long nsecs = nsecTaiToAny(_nsecs, scale);
    // Round to negative infinity
    long long frac = nsecs % LL_NSEC_PER_SEC;
    if (nsecs < 0 && frac < 0) {
        nsecs -= LL_NSEC_PER_SEC + frac;
    } else {
        nsecs -= frac;
    }
    time_t secs = static_cast<time_t>(nsecs / LL_NSEC_PER_SEC);
    gmtime_r(&secs, &gmt);
    return gmt;
}

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.

{ return std::hash<long long>()(_nsecs); }

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.

                                                                {
    Leap l;
    leapSecTable.clear();
    boost::regex re(
            "^\\d{4}.*?=JD\\s*([\\d.]+)\\s+TAI-UTC=\\s+([\\d.]+)\\s+S"
            " \\+ \\(MJD - ([\\d.]+)\\) X ([\\d.]+)\\s*S$");
    for (boost::cregex_iterator i = make_regex_iterator(leapString.c_str(), re);
         i != boost::cregex_iterator(); ++i) {
        double mjdUtc = strtod((*i)[1].first, 0) - MJD_TO_JD;
        l.offset = strtod((*i)[2].first, 0);
        l.mjdRef = strtod((*i)[3].first, 0);
        l.drift = strtod((*i)[4].first, 0);
        l.whenUtc = static_cast<long long>((mjdUtc - EPOCH_IN_MJD) * NSEC_PER_DAY);
        l.whenTai = l.whenUtc + static_cast<long long>(1.0e9 * (l.offset + (mjdUtc - l.mjdRef) * l.drift));
        leapSecTable.push_back(l);
    }
}

isValid()

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

inline

Is this date valid?

Definition at line 203 of file DateTime.h.

{ return _nsecs != DateTime::invalid_nsecs; };

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.

                           {
    struct timeval tv;
    int ret = gettimeofday(&tv, 0);
    if (ret != 0) {
        throw LSST_EXCEPT(lsst::pex::exceptions::RuntimeError, "Unable to get current time");
    }
    long long nsecs = tv.tv_sec * LL_NSEC_PER_SEC + tv.tv_usec * 1000LL;
    return DateTime(nsecs, DateTime::UTC);
}

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.

                                               {
    if (!isValid()) {
        // return the same invalid value for all time scales
        return DateTime::invalid_nsecs;
    }
    return nsecTaiToAny(_nsecs, scale);
}

operator==()

bool lsst::daf::base::DateTime::operator==

(

DateTime const &

rhs

)

const

Definition at line 513 of file DateTime.cc.

{ return _nsecs == rhs._nsecs; }

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 463 of file DateTime.cc.

                                                        {
    _assertValid();
    struct timespec ts;
    long long nsecs = nsecTaiToAny(_nsecs, scale);
    ts.tv_sec = static_cast<time_t>(nsecs / LL_NSEC_PER_SEC);
    ts.tv_nsec = static_cast<int>(nsecs % LL_NSEC_PER_SEC);
    return ts;
}

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 463 of file DateTime.cc.

                                                      {
    _assertValid();
    struct timeval tv;
    long long nsecs = nsecTaiToAny(_nsecs, scale);
    tv.tv_sec = static_cast<time_t>(nsecs / LL_NSEC_PER_SEC);
    tv.tv_usec = static_cast<int>((nsecs % LL_NSEC_PER_SEC) / 1000);
    return tv;
}

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.

                                                  {
    _assertValid();
    struct tm gmt(this->gmtime(scale));
 
    long long fracnsecs = nsecTaiToAny(_nsecs, scale) % LL_NSEC_PER_SEC;
    if (fracnsecs < 0) {
        fracnsecs += LL_NSEC_PER_SEC;
    }
    auto fmtStr = scale == UTC ? "%04d-%02d-%02dT%02d:%02d:%02d.%09dZ" : "%04d-%02d-%02dT%02d:%02d:%02d.%09d";
    return (boost::format(fmtStr) % (gmt.tm_year + 1900) % (gmt.tm_mon + 1) % gmt.tm_mday % gmt.tm_hour %
            gmt.tm_min % gmt.tm_sec % fracnsecs)
            .str();
}

Friends And Related Function Documentation

boost::serialization::access

friend class boost::serialization::access

friend

Definition at line 291 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()

staticconstexpr

Definition at line 75 of file DateTime.h.

---

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

• /j/snowflake/release/lsstsw/stack/cb4e2dc/Linux64/daf_base/20.0.0-4-gf910f65+5d3db074ba/include/lsst/daf/base/DateTime.h
• /j/snowflake/release/lsstsw/stack/cb4e2dc/Linux64/daf_base/20.0.0-4-gf910f65+5d3db074ba/src/DateTime.cc