Epoch Class Reference
[GPStk Time Group]

#include <Epoch.hpp>

Collaboration diagram for Epoch:

[legend]List of all members.

---

Detailed Description

Todo:

Fix these comments.

A time representation class for all common time formats, including GPS. There is a seamless conversion between dates, times, and both, as well as the ability to input and output the stored day-time in formatted strings (printf() and scanf()).

Internally, the representation of day and time uses a CommonTime object.

See also:

CommonTime

In addition, the representation includes a tolerance value which is used in CommonTime comparisons. It defaults to the value of the static gpstk::Epoch::EPOCH_TOLERANCE, but this can be modified with the static method setEpochTolerance(). Several different default tolerances have been defined and are in the Epoch-Specific Definitions section. The tolerance can also be changed on a per-object basis with the setTolerance() member function. All comparisons are done using the tolerance as a range for the comparison. So, for example, operator==() returns true if the times are within 'tolerance' seconds. Once set for each object, the tolerance is appropriately "carried forward" to new objects through the copy operator (operator=), the copy constructor, and elsewhere.

The internal representation is manipulated using four fundamental routines, two that convert between 'jday' (the integer representation of JD) and calendar date: year/month/day-of-month, and two that convert between seconds-of-day and hour/minute/second. These routines can be found in the TimeConverters.hpp file. The range of validity of the jday--calendar routines is approximately 4317 B.C. to 4317 A.D.; these limits are incorporated into constants Epoch::BEGINNING_OF_TIME and Epoch::END_OF_TIME.

* All Epoch objects that lie outside these limits are disallowed. *

This representation separates day and time-of-day cleanly. Because day and time are logically separated, it is possible to use Epoch for day only, or for time only. Thus, for example, one could instantiate a Epoch object and only manipulate the date, without reference to time-of-day; or vice-versa. [However in this regard note that the default constructor for Epoch sets the data, not to zero, but to the current (system) time.]

When constructing Epoch objects from GPS time values -- such as GPS week and seconds of weeks, or GPS week and z count -- there may be ambiguity associated with the GPS week. Many receivers and receiver processing software store the GPS week as it appears in the NAV message, as a 10-bit number. This leads to a 1024 week ambiguity when 10-bit GPS weeks are used to specify a Epoch. In general, Epoch uses the system time to disambiguate which 1024 week period to use. This is a good assumption except when processing binary data from before GPS week rollover, which occured on August 22, 1999.

Definition at line 123 of file Epoch.hpp.

Tolerance Functions
Epoch &	setTolerance (double tol) throw ()
	Sets the tolerance for output and comparisons on this object only.
double	getTolerance () throw ()
	Return the tolerance value currently in use by this object.
double	setEpochTolerance (double tol) throw ()
	Changes the EPOCH_TOLERANCE for all Epoch objects.
double	getEpochTolerance () throw ()
	Returns the current EPOCH_TOLERANCE.
Public Member Functions
Constructors and Destructor
	Epoch (const TimeTag &tt=SystemTime()) throw (EpochException)
	Default Constructor.
	Epoch (const CommonTime &ct) throw ()
	CommonTime Constructor.
	Epoch (const TimeTag &tt, short year) throw (EpochException)
	TimeTag + Year Constructor.
	Epoch (const GPSZcount &gzc) throw ()
	GPSZcount Constructor.
	~Epoch () throw ()
	Destructor.
Assignment and Copy
	Epoch (const Epoch &right) throw ()
	Copy constructor.
Epoch &	operator= (const Epoch &right) throw ()
	Assignment operator.
Arithmetic
double	operator- (const Epoch &right) const throw ()
	Epoch difference function.
Epoch	operator+ (double sec) const throw (EpochException)
	Add seconds to this time.
Epoch	operator- (double sec) const throw (EpochException)
	Subtract seconds from this time.
Epoch &	operator+= (double sec) throw (EpochException)
	Add seconds to this time.
Epoch &	operator-= (double sec) throw (EpochException)
	Subtract seconds from this time.
Epoch &	addSeconds (double seconds) throw (EpochException)
	Add (double) seconds to this time.
Epoch &	addSeconds (long seconds) throw (EpochException)
	Add (integer) seconds to this time.
Epoch &	addMilliSeconds (long msec) throw (EpochException)
	Add (integer) milliseconds to this time.
Epoch &	addMicroSeconds (long usec) throw (EpochException)
	Add (integer) microseconds to this time.
Comparisons
bool	operator== (const Epoch &right) const throw ()
bool	operator!= (const Epoch &right) const throw ()
bool	operator< (const Epoch &right) const throw ()
bool	operator> (const Epoch &right) const throw ()
bool	operator<= (const Epoch &right) const throw ()
bool	operator>= (const Epoch &right) const throw ()
Accessor Methods (get and set)
template<class TimeTagType>
TimeTagType	get () const throw (EpochException)
	Get the specified TimeTag.
long double	JD () const throw (EpochException)
	Get Julian Date JD.
long double	MJD () const throw (EpochException)
	Get Modified Julian Date MJD.
short	year () const throw (EpochException)
	Get year.
short	month () const throw (EpochException)
	Get month of year.
short	day () const throw (EpochException)
	Get day of month.
short	dow () const throw (EpochException)
	Get day of week.
short	hour () const throw (EpochException)
	Get hour of day.
short	minute () const throw (EpochException)
	Get minutes of hour.
double	second () const throw (EpochException)
	Get seconds of minute.
double	sod () const throw (EpochException)
	Get seconds of day.
short	GPSweek10 () const throw (EpochException)
	Get 10-bit GPS week.
long	GPSzcount () const throw (EpochException)
	Get normal (19 bit) zcount.
long	GPSzcountFloor () const throw (EpochException)
	Same as GPSzcount() but without rounding to nearest zcount.
unsigned long	GPSzcount32 () const throw (EpochException)
	Get time as 32 bit Z count.
unsigned long	GPSzcount32Floor () const throw (EpochException)
	Same as fullZcount() but without rounding to nearest zcount.
double	GPSsow () const throw (EpochException)
	Get GPS second of week.
short	GPSweek () const throw (EpochException)
	Get full (>10 bits) week.
short	doy () const throw (EpochException)
	Get day of year.
long double	getMJDasLongDouble () const throw (EpochException)
	Get object time as a (long double) modified Julian date.
timeval	unixTime () const throw (EpochException)
	Get object time in UNIX timeval structure.
	operator GPSZcount () const throw (EpochException)
	Convert this object to a GPSZcount object.
	operator CommonTime () const throw ()
	Convert this object to a CommonTime object.
Epoch &	set (const TimeTag &tt=SystemTime()) throw (EpochException)
	Set the object using a TimeTag object.
Epoch &	set (const TimeTag &tt, short year) throw (EpochException)
	Set the object using a TimeTag and a year as a hint.
Epoch &	set (const CommonTime &c) throw ()
	Set the object using the give CommonTime.
Epoch &	set (const GPSZcount &z) throw (EpochException)
	Set the object using a GPSZcount object.
Epoch &	setTime (const CommonTime &ct) throw (EpochException)
	Set the object's time using a CommonTime object.
Epoch &	setDate (const CommonTime &ct) throw (EpochException)
	Set the object's date using a CommonTime object.
Epoch &	setLocalTime () throw (EpochException)
	Set the object time to the current local time.
Printing and Scanning Methods
Epoch &	scanf (const std::string &str, const std::string &fmt) throw (StringUtils::StringException, InvalidRequest)
	Similar to scanf, this function takes a string and a format describing string in order to read in values.
std::string	printf (const std::string &fmt=PRINT_FORMAT) const throw (StringUtils::StringException)
	Format this time into a string.
Static Public Attributes
Epoch-Specific Definitions
All of these tolerances are 1/2 of the tolerance they specify. So one nsec tolerance is actually 1/2 an ns added to the time in units of days.
const double	ONE_NSEC_TOLERANCE = 1e-9
	One nanosecond tolerance.
const double	ONE_USEC_TOLERANCE = 1e-6
	One microsecond tolerance.
const double	ONE_MSEC_TOLERANCE = 1e-3
	One millisecond tolerance.
const double	ONE_SEC_TOLERANCE = 1
	One second tolerance.
const double	ONE_MIN_TOLERANCE = 60
	One minute tolerance.
const double	ONE_HOUR_TOLERANCE = 3600
	One hour tolerance.
double	EPOCH_TOLERANCE = ONE_NSEC_TOLERANCE
	Default tolerance for time equality in days.
const Epoch	BEGINNING_OF_TIME
	Earliest representable Epoch.
const Epoch	END_OF_TIME
	Latest Representable Epoch.
std::string	PRINT_FORMAT
	This is how an Epoch is printed by default.

---

Constructor & Destructor Documentation

Epoch (  const TimeTag &  tt = SystemTime()  )  throw (EpochException)

Default Constructor. Initializes to current system time or to the given TimeTag. TimeTag-covered constructors: year, month, day, hour, minute, second (CivilTime) long double mjd (MJD) double mjd (MJD) year, doy, sod (YDSTime) Unix struct timeval (UnixTime) gps full week and second (GPSWeekSecond) Definition at line 95 of file Epoch.cpp.

Epoch (  const CommonTime &  ct  )  throw ()

CommonTime Constructor. Set the time using the given CommonTime object. Definition at line 102 of file Epoch.cpp.

Epoch (  const TimeTag &  tt, short  year )  throw (EpochException)

TimeTag + Year Constructor. Set the current time using the given year as a hint. For example, when one only knows the 10-bit GPS week, one could could use a "hint" year to figure out which Epoch the week was in. TimeTag + year -covered constructors: gps 10-bit week and second and year (GPSEpochWeekSecond + year) gps week and zcount and year (GPSWeekZcount + year) Definition at line 112 of file Epoch.cpp.

Epoch (  const GPSZcount &  gzc  )  throw ()

GPSZcount Constructor. Set the current time using the given GPSZcount. Definition at line 123 of file Epoch.cpp.

~Epoch (   )  throw () [inline]

Destructor. Definition at line 269 of file Epoch.hpp.

Epoch (  const Epoch &  right  )  throw ()

Copy constructor. Definition at line 148 of file Epoch.cpp.

---

Member Function Documentation

Epoch & addMicroSeconds (  long  usec  )  throw (EpochException)

Add (integer) microseconds to this time. Parameters: usec  Number of microseconds to increase this time by. Exceptions: EpochException  on over/under-flow Definition at line 259 of file Epoch.cpp. References CommonTime::addMilliseconds(), CommonTime::addSeconds(), and GPSTK_THROW.

Epoch & addMilliSeconds (  long  msec  )  throw (EpochException)

Add (integer) milliseconds to this time. Parameters: msec  Number of milliseconds to increase this time by. Exceptions: EpochException  on over/under-flow Definition at line 242 of file Epoch.cpp. References CommonTime::addMilliseconds(), and GPSTK_THROW.

Epoch & addSeconds (  long  seconds  )  throw (EpochException)

Add (integer) seconds to this time. Parameters: seconds  Number of seconds to increase this time by. Exceptions: EpochException  on over/under-flow Definition at line 225 of file Epoch.cpp. References CommonTime::addSeconds(), and GPSTK_THROW.

Epoch & addSeconds (  double  seconds  )  throw (EpochException)

Add (double) seconds to this time. Parameters: seconds  Number of seconds to increase this time by. Exceptions: EpochException  on over/under-flow Definition at line 208 of file Epoch.cpp. References CommonTime::addSeconds(), and GPSTK_THROW. Referenced by CommonTime::operator+(), and CommonTime::operator-().

short day (   )  const throw (EpochException) [inline]

Get day of month. Definition at line 746 of file Epoch.hpp.

short dow (   )  const throw (EpochException) [inline]

Get day of week. Definition at line 753 of file Epoch.hpp.

short doy (   )  const throw (EpochException) [inline]

Get day of year. Definition at line 843 of file Epoch.hpp.

TimeTagType get (   )  const throw (EpochException)

Get the specified TimeTag. This function converts the internal store into the requested TimeTag type. Definition at line 703 of file Epoch.hpp. Referenced by Epoch::GPSzcountFloor().

double getEpochTolerance (   )  throw () [inline, static]

Returns the current EPOCH_TOLERANCE. Definition at line 200 of file Epoch.hpp.

long double getMJDasLongDouble (   )  const throw (EpochException) [inline]

Get object time as a (long double) modified Julian date. For some compilers, this result may have diminished accuracy.

double getTolerance (   )  throw () [inline]

Return the tolerance value currently in use by this object. Returns: the current tolerance value (in seconds, of course) Definition at line 218 of file Epoch.hpp.

double GPSsow (   )  const throw (EpochException) [inline]

Get GPS second of week. Definition at line 829 of file Epoch.hpp.

short GPSweek (   )  const throw (EpochException) [inline]

Get full (>10 bits) week. Definition at line 836 of file Epoch.hpp.

short GPSweek10 (   )  const throw (EpochException) [inline]

Get 10-bit GPS week. Definition at line 788 of file Epoch.hpp.

long GPSzcount (   )  const throw (EpochException) [inline]

Get normal (19 bit) zcount. Definition at line 795 of file Epoch.hpp.

unsigned long GPSzcount32 (   )  const throw (EpochException) [inline]

Get time as 32 bit Z count. The 13 MSBs are week modulo 1024, 19 LSBs are seconds of week in Zcounts. Definition at line 814 of file Epoch.hpp.

unsigned long GPSzcount32Floor (   )  const throw (EpochException) [inline]

Same as fullZcount() but without rounding to nearest zcount. Definition at line 821 of file Epoch.hpp.

long GPSzcountFloor (   )  const throw (EpochException) [inline]

Same as GPSzcount() but without rounding to nearest zcount. Definition at line 802 of file Epoch.hpp. References Epoch::get().

short hour (   )  const throw (EpochException) [inline]

Get hour of day. Definition at line 760 of file Epoch.hpp.

long double JD (   )  const throw (EpochException) [inline]

Get Julian Date JD. Warning: For some compilers, this result may have diminished accuracy. Definition at line 716 of file Epoch.hpp.

short minute (   )  const throw (EpochException) [inline]

Get minutes of hour. Definition at line 767 of file Epoch.hpp.

long double MJD (   )  const throw (EpochException) [inline]

Get Modified Julian Date MJD. Warning: For some compilers, this result may have diminished accuracy. Definition at line 725 of file Epoch.hpp. Referenced by UTCTime::asTDB().

short month (   )  const throw (EpochException) [inline]

Get month of year. Definition at line 739 of file Epoch.hpp.

operator CommonTime (   )  const throw ()

Convert this object to a CommonTime object. Definition at line 324 of file Epoch.cpp.

operator GPSZcount (   )  const throw (EpochException)

Convert this object to a GPSZcount object. Definition at line 130 of file Epoch.cpp. References GPSTK_THROW, GPSWeek::week, and GPSWeekZcount::zcount.

bool operator!= (  const Epoch &  right  )  const throw ()

Definition at line 288 of file Epoch.cpp. References gpstk::operator==().

Epoch operator+ (  double  sec  )  const throw (EpochException)

Add seconds to this time. Parameters: sec  Number of seconds to increase this time by. Returns: The new time incremented by sec. Definition at line 175 of file Epoch.cpp. References CommonTime::addSeconds().

Epoch & operator+= (  double  sec  )  throw (EpochException)

Add seconds to this time. Parameters: sec  Number of seconds to increase this time by. Exceptions: EpochException  on over/under-flow Definition at line 192 of file Epoch.cpp.

Epoch operator- (  double  sec  )  const throw (EpochException)

Subtract seconds from this time. Parameters: sec  Number of seconds to decrease this time by. Returns: The new time decremented by sec. Definition at line 184 of file Epoch.cpp. References CommonTime::addSeconds().

double operator- (  const Epoch &  right  )  const throw ()

Epoch difference function. Parameters: right  Epoch to subtract from this one. Returns: difference in seconds. Definition at line 166 of file Epoch.cpp.

Epoch & operator-= (  double  sec  )  throw (EpochException)

Subtract seconds from this time. Parameters: sec  Number of seconds to decrease this time by. Exceptions: EpochException  on over/under-flow Definition at line 200 of file Epoch.cpp.

bool operator< (  const Epoch &  right  )  const throw ()

Definition at line 295 of file Epoch.cpp. References gpstk::operator-().

bool operator<= (  const Epoch &  right  )  const throw ()

Definition at line 311 of file Epoch.cpp. References gpstk::operator>().

Epoch & operator= (  const Epoch &  right  )  throw ()

Assignment operator. Definition at line 155 of file Epoch.cpp. References Epoch::core.

bool operator== (  const Epoch &  right  )  const throw ()

Definition at line 279 of file Epoch.cpp. References ABS.

bool operator> (  const Epoch &  right  )  const throw ()

Definition at line 303 of file Epoch.cpp. References gpstk::operator-().

bool operator>= (  const Epoch &  right  )  const throw ()

Definition at line 318 of file Epoch.cpp. References gpstk::operator<().

string printf (  const std::string &  fmt = PRINT_FORMAT  )  const throw (StringUtils::StringException)

Format this time into a string. Note: Whenever a format is added or removed from the Epoch class, it more than likely should also be added or removed from the FileSpec class. Additionally, the format character must not conflict with any of the existing format characters in Epoch or FileSpec. Generate and return a string containing a formatted date, formatted by the specification fmt. %Y year() %y year() 100 %m month() %d day() %H hour() %M minute() %S (short)second() %f second() %G GPS10bitweek() %F GPSfullweek() %g GPSsecond() or GPSsow() %s DOYsecond() %Q MJDdate() %w dayOfWeek() or GPSday() %b MonthAbbrevName[month()] %B MonthName[month()] %a DayOfWeekAbbrevName[dayOfWeek()] %A DayOfWeekName[dayOfWeek()] %j DOYday() or DOY() %Z GPSzcount() %z GPSzcountFloor() %U unixTime().tv_sec %u unixTime().tv_usec %C fullZcount() %c fullZcountFloor() Warning: See above note. Parameters: fmt  format to use for this time. Returns: a string containing this time in the representation specified by fmt. Definition at line 464 of file Epoch.cpp. References GPSTK_RETHROW, and gpstk::printTime(). Referenced by gpstk::operator<<().

Epoch & scanf (  const std::string &  str, const std::string &  fmt )  throw (StringUtils::StringException, InvalidRequest)

Similar to scanf, this function takes a string and a format describing string in order to read in values. The parameters it can take are listed below and described above with the printf() function. The specification must resolve to a day at a minimum level. The following table lists combinations that give valid times. Anything more or other combinations will give unknown (read as: "bad") results so don't try it. Anything less will throw an exception. If nothing changes the time of day, it will default to midnight. Also, the year defaults to the current year if a year isn't specified or can't be determined. 1 of... and 1 of.... optional... %C %G %w %g %Z %Y %y %F %w %g %Z %m %B %b %a %A %d %Y %y %H %M %S %Q %j %Y %y %s So time.setToString("Aug 1, 2000 20:20:20", "%b %d, %Y %H:%M:%S") works but time.setToString("Aug 2000", "%b %Y") doesn't work (incomplete specification because it doesn't specify a day). Don't worry about counting whitespace - this function will take care of that. Just make sure that the extra stuff in the format string (ie '.' ',') are in the same relative location as they are in the actual string. (see in the example above)) Parameters: str  string to get date/time from. fmt  format to use to parse str. Exceptions: EpochException  if fmt is an incomplete specification FormatException  if unable to scan str. StringException  if an error occurs manipulating the str or fmt strings. Returns: a reference to this object. Definition at line 448 of file Epoch.cpp. References GPSTK_RETHROW, and gpstk::scanTime().

double second (   )  const throw (EpochException) [inline]

Get seconds of minute. Definition at line 774 of file Epoch.hpp.

Epoch & set (  const GPSZcount &  z  )  throw (EpochException)

Set the object using a GPSZcount object. Definition at line 376 of file Epoch.cpp. References GPSTK_THROW, GPSWeek::week, and GPSWeekZcount::zcount.

Epoch & set (  const CommonTime &  c  )  throw ()

Set the object using the give CommonTime. Parameters: c  the CommonTime object to set to Returns: a reference to this object. Definition at line 363 of file Epoch.cpp.

Epoch & set (  const TimeTag &  tt, short  year )  throw (EpochException)

Set the object using a TimeTag and a year as a hint. Parameters: tt  the TimeTag to which to set this object. year  the "hint" year Returns: a reference to this object. Definition at line 345 of file Epoch.cpp. References GPSWeek::getWeek10(), GPSTK_THROW, and GPSWeek::setEpoch().

Epoch & set (  const TimeTag &  tt = SystemTime()  )  throw (EpochException)

Set the object using a TimeTag object. Parameters: tt  the TimeTag to which to set this object (Defaults to SystemTime()). Returns: a reference to this object. Definition at line 330 of file Epoch.cpp. References GPSTK_THROW. Referenced by Epoch::setLocalTime().

Epoch & setDate (  const CommonTime &  ct  )  throw (EpochException)

Set the object's date using a CommonTime object. This operation leaves the object's time unchanged. Note: as TimeTags can be implicitly converted to CommonTime objects, this method works for them as well. Definition at line 413 of file Epoch.cpp. References GPSTK_THROW.

double setEpochTolerance (  double  tol  )  throw () [inline, static]

Changes the EPOCH_TOLERANCE for all Epoch objects. Definition at line 195 of file Epoch.hpp.

Epoch & setLocalTime (   )  throw (EpochException)

Set the object time to the current local time. Todo: What is this? Definition at line 433 of file Epoch.cpp. References Epoch::set().

Epoch & setTime (  const CommonTime &  ct  )  throw (EpochException)

Set the object's time using a CommonTime object. This operation leaves the object's date unchanged. Note: as TimeTags can be implicitly converted to CommonTime objects, this method works for them as well. Definition at line 394 of file Epoch.cpp. References GPSTK_THROW.

Epoch & setTolerance (  double  tol  )  throw ()

Sets the tolerance for output and comparisons on this object only. See the constants in this file (e.g. ONE_NSEC_TOLERANCE) for some easy to use tolerance values. Parameters: tol  Tolerance in days to be used by comparison operators. See also: Epoch-Specific Definitions Definition at line 87 of file Epoch.cpp.

double sod (   )  const throw (EpochException) [inline]

Get seconds of day. Definition at line 781 of file Epoch.hpp.

struct timeval unixTime (   )  const throw (EpochException) [inline]

Get object time in UNIX timeval structure. Definition at line 850 of file Epoch.hpp.

short year (   )  const throw (EpochException) [inline]

Get year. Definition at line 732 of file Epoch.hpp.

---

Member Data Documentation

const Epoch BEGINNING_OF_TIME [static]

Earliest representable Epoch. Definition at line 184 of file Epoch.hpp.

const Epoch END_OF_TIME [static]

Latest Representable Epoch. Definition at line 186 of file Epoch.hpp.

double EPOCH_TOLERANCE = ONE_NSEC_TOLERANCE [static]

Default tolerance for time equality in days. Definition at line 77 of file Epoch.cpp.

const double ONE_HOUR_TOLERANCE = 3600 [static]

One hour tolerance. Definition at line 71 of file Epoch.cpp.

const double ONE_MIN_TOLERANCE = 60 [static]

One minute tolerance. Definition at line 69 of file Epoch.cpp.

const double ONE_MSEC_TOLERANCE = 1e-3 [static]

One millisecond tolerance. Definition at line 65 of file Epoch.cpp.

const double ONE_NSEC_TOLERANCE = 1e-9 [static]

One nanosecond tolerance. Definition at line 61 of file Epoch.cpp.

const double ONE_SEC_TOLERANCE = 1 [static]

One second tolerance. Definition at line 67 of file Epoch.cpp.

const double ONE_USEC_TOLERANCE = 1e-6 [static]

One microsecond tolerance. Definition at line 63 of file Epoch.cpp.

std::string PRINT_FORMAT [static]

This is how an Epoch is printed by default.

---

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

• Epoch.hpp
• Epoch.cpp

---