lsst.daf.base::DateTime Class Reference

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

#include <DateTime.h>

Public Types
enum	Timescale { TAI, UTC, TT }
enum	DateSystem { JD, MJD, EPOCH }

Public Member Functions
	DateTime (long long nsecs=0LL, Timescale scale=TAI)
	DateTime (double date, DateSystem system=MJD, Timescale scale=TAI)
	DateTime (int year, int month, int day, int hr, int min, int sec, Timescale scale=TAI)
	DateTime (std::string const &iso8601)
long long	nsecs (Timescale scale=TAI) const
double	mjd (Timescale scale=TAI) const
double	get (DateSystem system=MJD, Timescale scale=TAI) const
std::string	toString (void) const
struct tm	gmtime (void) const
struct timespec	timespec (void) const
struct timeval	timeval (void) const
bool	operator== (DateTime const &rhs) const

Static Public Member Functions
static DateTime	now (void)
static void	initializeLeapSeconds (std::string const &leapString)

Private Member Functions
double	_getMjd (Timescale scale) const
double	_getJd (Timescale scale) const
double	_getEpoch (Timescale scale) const
void	setNsecsFromMjd (double mjd, Timescale scale)
	a function to convert MJD to interal nsecs More...
void	setNsecsFromJd (double jd, Timescale scale)
	a function to convert JD to internal nsecs More...
void	setNsecsFromEpoch (double epoch, Timescale scale)
	a function to convert epoch to internal nsecs More...
template<class Archive >
void	serialize (Archive ar, int const version)

Private Attributes
long long	_nsecs
	Nanoseconds since Unix epoch. More...

Friends
class	boost::serialization::access

Detailed Description

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

Definition at line 58 of file DateTime.h.

Member Enumeration Documentation

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

Enumerator
JD
MJD
EPOCH

Definition at line 61 of file DateTime.h.

{ JD, MJD, EPOCH };

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

Enumerator
TAI
UTC
TT

Definition at line 60 of file DateTime.h.

{ TAI, UTC, TT };

Constructor & Destructor Documentation

lsst.daf.base::DateTime::DateTime ( long long  nsecs = 0LL, Timescale  scale = TAI  )

explicit

Constructor.

Parameters

[in]	nsecs	Number of nanoseconds since the epoch.
[in]	scale	Timescale of input (TAI or UTC, default TAI).

Definition at line 290 of file DateTime.cc.

                                                          : _nsecs(nsecs) {
    if (scale == UTC) {
        _nsecs = utcToTai(_nsecs);
    } else if (scale == TT) {
        _nsecs -= TT_MINUS_TAI_NSECS;
    }
}

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

explicit

Constructor.

Parameters

[in]	date	Date.
[in]	system	The requested date system (JD, MJD, or Julian epoch)
[in]	scale	Timescale of input (TAI or UTC, default TAI).

Definition at line 303 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;
    }
}

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

Constructor.

Parameters

[in]	year	Year number.
[in]	month	Month number (Jan = 1).
[in]	day	Day number (1 to 31).
[in]	hr	Hour number (0 to 23).
[in]	min	Minute number (0 to 59).
[in]	sec	Second number (0 to 60).
[in]	scale	Timescale of input (TAI or UTC, default TAI).

Definition at line 331 of file DateTime.cc.

                                                                       {


    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 sep 21, 1677 0:00:00, and apr 12 2262 00:00:00
    // (refering to the values of EPOCH_IN_MJD +/- MAX_DAYS ... exceeds 64 bits.)
    // However, a tm struct is only 32 bits, and saturates at:
    //    low end - Dec 13 1901, 20:45:52
    //    hi end  - Jan 19 2038, 03:14:07
    
    if (secs == -1) {
        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 = secs * LL_NSEC_PER_SEC;
    if (scale == UTC) {
        _nsecs = utcToTai(_nsecs);
    } else if (scale == TT) {
        _nsecs -= TT_MINUS_TAI_NSECS;
    }

}

lsst.daf.base::DateTime::DateTime ( std::string const &  iso8601 )

explicit

Constructor. Accepts a restricted subset of ISO8601: yyyy-mm-ddThh:mm:ss.nnnnnnnnnZ where the - and : separators are optional, the fractional seconds are also optional, and the decimal point may be a comma.

Parameters

[in]

iso8601

ISO8601 representation of date and time. Must be UTC.

Definition at line 381 of file DateTime.cc.

                                                  {
    boost::regex re("(\\d{4})-?(\\d{2})-?(\\d{2})" "T"
                    "(\\d{2}):?(\\d{2}):?(\\d{2})" "([.,](\\d*))?" "Z");
    boost::smatch matches;
    if (!regex_match(iso8601, matches, re)) {
        throw LSST_EXCEPT(lsst::pex::exceptions::DomainError,
                          "Not in acceptable ISO8601 format: " + iso8601);
    }
    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()),
                UTC);
    _nsecs = dt._nsecs;
    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

double lsst.daf.base::DateTime::_getEpoch ( Timescale  scale ) const

private

Convert to Julian Epoch.

Parameters

[in]

scale

Desired timescale (TAI or UTC, default TAI).

Returns

The Julian Epoch corresponding to the time.

Definition at line 481 of file DateTime.cc.

                                                       {
    return 2000.0 + (_getJd(scale) - JD2000)/365.25;
}

double lsst.daf.base::DateTime::_getJd ( Timescale  scale ) const

private

Convert to Julian Day.

Parameters

[in]

scale

Desired timescale (TAI or UTC, default TAI).

Returns

The Julian Day corresponding to the time.

Definition at line 473 of file DateTime.cc.

                                                    {
    return _getMjd(scale) + MJD_TO_JD;
}

double lsst.daf.base::DateTime::_getMjd ( Timescale  scale ) const

private

Convert to Modified Julian Day.

Parameters

[in]

scale

Desired timescale (TAI or UTC, default TAI).

Returns

The Modified Julian Day corresponding to the time.

Definition at line 455 of file DateTime.cc.

                                                     {

    double nsecs;
    if (scale == TAI) {
        nsecs = static_cast<double>(_nsecs);
    } else if (scale == TT) {
        nsecs = static_cast<double>(_nsecs) + TT_MINUS_TAI_NSECS;
    } else {
        nsecs = static_cast<double>(taiToUtc(_nsecs));
    }
    return nsecs / NSEC_PER_DAY + EPOCH_IN_MJD;
}

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

Generic Accessor

Returns

the date in the required system, for the requested scale

Parameters

[in]	system	The type of date requested (JD, MJD, or EPOCH)
[in]	scale	The time scale (UTC, or TAI)

Note

The NSECS can't be requested here as they're in long long form. A factory could be constructed, but it's more trouble than it's worth at this point.

Definition at line 418 of file DateTime.cc.

                                                                    {
    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;
    }
}

struct tm lsst.daf.base::DateTime::gmtime

(

void

)

const

Convert to struct tm. Truncate fractional seconds.

Returns

Structure with decoded time in UTC.

Definition at line 491 of file DateTime.cc.

                                            {
    struct tm gmt;
    long long nsecs = taiToUtc(_nsecs);
    // 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;
}

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

static

Initialize leap second table.

Parameters

leapString

Leap second table from USNO as a single multiline string.

Definition at line 567 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);
    }
}

double lsst.daf.base::DateTime::mjd ( Timescale  scale = TAI ) const

inline

Definition at line 69 of file DateTime.h.

                                            {  // deprecated, please use get(MJD)
        return _getMjd(scale);
    }

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

static

Return current time as a DateTime.

Returns

DateTime representing the current time.

Definition at line 553 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);
}

long long lsst.daf.base::DateTime::nsecs

(

Timescale

scale = TAI

)

const

Accessor.

Returns

Number of nanoseconds since the epoch in UTC or TAI.

Definition at line 440 of file DateTime.cc.

                                                      {
    if (scale == TAI) {
        return _nsecs;
    } else if (scale == TT) {
        return _nsecs + TT_MINUS_TAI_NSECS;
    } else {
        return taiToUtc(_nsecs);
    }
}

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

(

DateTime const &

rhs

)

const

Equality operator.

Returns

True if both DateTimes have the same nanosecond representation.

Definition at line 546 of file DateTime.cc.

                                                          {
    return _nsecs == rhs._nsecs;
}

template<class Archive >

void lsst.daf.base::DateTime::serialize ( Archive  ar, int const  version  )

inlineprivate

Serialize DateTime to/from a Boost archive.

Parameters

[in,out]	ar	Archive to access.
[in]	version	Version of class serializer.

Definition at line 101 of file DateTime.h.

                                                                           {
        ar & _nsecs;
    }

void lsst.daf.base::DateTime::setNsecsFromEpoch ( double  epoch, Timescale  scale  )

private

a function to convert epoch to internal nsecs

Parameters

[in]	epoch	The Julian epoch
[in]	scale	The time scale (TAI, or UTC)

Definition at line 280 of file DateTime.cc.

                                                                     {
    setNsecsFromMjd(365.25*(epoch - 2000.0) + JD2000 - MJD_TO_JD, scale);
}

void lsst.daf.base::DateTime::setNsecsFromJd ( double  jd, Timescale  scale  )

private

a function to convert JD to internal nsecs

Parameters

[in]	jd	The Julian Day
[in]	scale	The time scale (TAI, or UTC)

Definition at line 271 of file DateTime.cc.

                                                               {
    setNsecsFromMjd(jd - MJD_TO_JD, scale);
}

void lsst.daf.base::DateTime::setNsecsFromMjd ( double  mjd, Timescale  scale  )

private

a function to convert MJD to interal nsecs

Parameters

[in]	mjd	The Modified Julian Day
[in]	scale	The time scale (TAI, or UTC)

Definition at line 245 of file DateTime.cc.

                                                                 {

    if (mjd > EPOCH_IN_MJD + MAX_DAYS) {
        throw LSST_EXCEPT(
                          lsst::pex::exceptions::DomainError,
                          (boost::format("MJD too far in the future: %1%") % mjd).str());
    }
    if (mjd < EPOCH_IN_MJD - MAX_DAYS) {
        throw LSST_EXCEPT(
                          lsst::pex::exceptions::DomainError,
                          (boost::format("MJD too far in the past: %1%") % mjd).str());
    }
    _nsecs = static_cast<long long>((mjd - EPOCH_IN_MJD) * NSEC_PER_DAY);
    if (scale == UTC) {
        _nsecs = utcToTai(_nsecs);
    } else if (scale == TT) {
        _nsecs -= TT_MINUS_TAI_NSECS;
    }

}

struct timespec lsst.daf.base::DateTime::timespec

(

void

)

const

Convert to struct timespec.

Returns

Structure with UTC time in seconds and nanoseconds.

Definition at line 510 of file DateTime.cc.

                                                    {
    struct timespec ts;
    long long nsecs = taiToUtc(_nsecs);
    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;
}

struct timeval lsst.daf.base::DateTime::timeval

(

void

)

const

Convert time to struct timeval.

Returns

Structure with UTC time in seconds and microseconds.

Definition at line 521 of file DateTime.cc.

                                                  {
    struct timeval tv;
    long long nsecs = taiToUtc(_nsecs);
    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;
}

std::string lsst.daf.base::DateTime::toString

(

void

)

const

Accessor.

Returns

ISO8601-formatted string representation. Always UTC.

Definition at line 532 of file DateTime.cc.

                                              {
    struct tm gmt(this->gmtime());
    long long nsecs = taiToUtc(_nsecs) % LL_NSEC_PER_SEC;
    if (nsecs < 0) {
        nsecs += LL_NSEC_PER_SEC;
    }
    return (boost::format("%04d-%02d-%02dT%02d:%02d:%02d.%09dZ") %
            (gmt.tm_year + 1900) % (gmt.tm_mon + 1) % gmt.tm_mday %
            gmt.tm_hour % gmt.tm_min % gmt.tm_sec % nsecs).str();
}

Friends And Related Function Documentation

friend class boost::serialization::access

friend

Definition at line 96 of file DateTime.h.

Member Data Documentation

long long lsst.daf.base::DateTime::_nsecs

private

Nanoseconds since Unix epoch.

Definition at line 86 of file DateTime.h.

---

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

• /home/lsstsw/stack/Linux64/daf_base/10.0-4-g027f45f+5/include/lsst/daf/base/DateTime.h
• /home/lsstsw/stack/Linux64/daf_base/10.0-4-g027f45f+5/src/DateTime.cc