A TimeStamp holds GPS second and nanosecond for some event. More...

#include "utl/TimeStamp.h"

Public Member Functions
double	GetGPSNanoSecond () const
	GPS nanosecond. More...

unsigned long	GetGPSSecond () const
	GPS second. More...

	operator bool () const

bool	operator!= (const TimeStamp &ts) const

TimeStamp	operator+ (const TimeInterval &ti) const
	[TimeStamp] + [TimeInterval] = [TimeStamp] More...

TimeStamp &	operator+= (const TimeInterval &ti)
	[TimeStamp] += [TimeInterval] = [TimeStamp] More...

TimeInterval	operator- (const TimeStamp &ts) const
	[TimeStamp] - [TimeStamp] = [TimeInterval] More...

TimeStamp	operator- (const TimeInterval &ti) const
	[TimeStamp] - [TimeInterval] = [TimeStamp] More...

TimeStamp &	operator-= (const TimeInterval &ti)
	[TimeStamp] -= [TimeInterval] = [TimeStamp] More...

bool	operator< (const TimeStamp &ts) const

bool	operator<= (const TimeStamp &ts) const

bool	operator== (const TimeStamp &ts) const

bool	operator> (const TimeStamp &ts) const

bool	operator>= (const TimeStamp &ts) const

void	SetGPSTime (const unsigned long sec, const double nsec=0)
	Set GPS second and (optionally) nanosecond. More...

	TimeStamp ()

	TimeStamp (const long sec, const double nsec=0)
	Construct from GPS second and nanosecond. More...

Static Public Member Functions
static TimeStamp	Max ()

Private Member Functions
void	SetNormalized (long sec, double nsec)
	Take care of positive nanosecond and GPS epoch. More...

Private Attributes
double	fGPSNanoSecond

unsigned long	fGPSSecond

Detailed Description

A TimeStamp holds GPS second and nanosecond for some event.

Introduction

This class holds a GPS second and nanosecond and provides methods to convert to seconds since Unix Epoch or to UTC, with proper accounting for leap seconds. Methods are also provided to return Modified Julian Date and formatted strings with UTC printout consistent with the conventions document, as well as strings of XML with date and time information.

A utl::TimeStamp represents the time of occurrence of some event. To represent time intervals between events, use the TimeInterval class. A number of arithmetic operations are defined between utl::TimeStamp and utl::TimeInterval. For example:

TimeStamp - TimeStamp = TimeInterval
TimeStamp - TimeInterval = TimeStamp
TimeStamp + TimeInterval = TimeStamp
TimeInterval + TimeInterval = TimeInterval

Time conventions

What is time? This is a brief summary of time systems, relevant for the Auger project operation (see http://tycho.usno.navy.mil/gpstt.html for details).

International Atomic Time (TAI) is a statistical time scale based on a large number of atomic clocks operating at standards laboratories around the world. Its unit interval is exactly one SI second at sea level. Neglecting the relativistic effects, this is probably the time scale in which Auger physics is happening.
Universal Time (UT) (and its variant UT1) is a time scale with unit of duration the mean solar day. It is based on the Earth's rotation and thus important for transformation of events into the galactic coordinates. Otherwise, not very useful for physics.
Coordinated Universal Time (UTC) differs from TAI by an integral number of seconds. UTC is kept within 0.9 seconds of UT1 by the introduction of one-second steps to UTC, the leap seconds. In contrast to UT1, UTC is running in parallel to TAI with piecewise constant offset.
Global Positioning System (GPS) time is synchronized to UTC but it is NOT adjusted for leap seconds. Since TAI and GPS epoch did not start on the same date, they run in parallel with TAI ahead of GPS by (constant) 19 seconds. GPS thus can be a candidate for physics time scale.

Why not just use unix time?

The utl::TimeStamp class will not allow you to initialize a TimeStamp using a unix time_t. You may wonder why this is, or wonder why we don't just use unix time for everything, since the c time library has functions already built in for converting unix seconds to UTC.

The reason is that, in a nutshell, unix time is broken. For some reason the POSIX standard requires the time_t to count seconds since Unix epoch not including leap seconds. This means calculating time intervals by subtracting unix times across a leap second will give the wrong result. Furthermore, initializing a TimeStamp with a time_t at the leap second boundary would be ambiguous; there are two GPS seconds corresponding to the unix second at the time of the leap second. It may seem that this would only rarely pose a problem, but on the other hand it is not particularly difficult to just do it correctly.