#pragma ident "$Id: DayTime.hpp 349 2006-12-20 15:04:03Z btolman $"/** * @file DayTime.hpp * gpstk::DayTime - encapsulates date and time-of-day in many formats */#ifndef GPSTK_DAYTIME_HPP#define GPSTK_DAYTIME_HPP//============================================================================////  This file is part of GPSTk, the GPS Toolkit.////  The GPSTk is free software; you can redistribute it and/or modify//  it under the terms of the GNU Lesser General Public License as published//  by the Free Software Foundation; either version 2.1 of the License, or//  any later version.////  The GPSTk is distributed in the hope that it will be useful,//  but WITHOUT ANY WARRANTY; without even the implied warranty of//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the//  GNU Lesser General Public License for more details.////  You should have received a copy of the GNU Lesser General Public//  License along with GPSTk; if not, write to the Free Software Foundation,//  Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA//  //  Copyright 2004, The University of Texas at Austin////============================================================================//============================================================================////This software developed by Applied Research Laboratories at the University of//Texas at Austin, under contract to an agency or agencies within the U.S. //Department of Defense. The U.S. Government retains all rights to use,//duplicate, distribute, disclose, or release this software. ////Pursuant to DoD Directive 523024 //// DISTRIBUTION STATEMENT A: This software has been approved for public //                           release, distribution is unlimited.////=============================================================================#include <string>#ifdef _MSC_VER// timeval is defined in winsock.h, which we don't want to include// because it breaks lots of this codestruct timeval {  long    tv_sec;         /* seconds */  long    tv_usec;        /* and microseconds */};#else#include <sys/time.h>#endif#include "MathBase.hpp"#include "Exception.hpp"#include "StringUtils.hpp"#include "GPSZcount.hpp"#include "CommonTime.hpp"namespace gpstk{      /** @defgroup timegroup GPStk Time Group */      //@{      /**       * 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 setToString()).       *       * Internally, the representation of day and time uses three quantities,       * (1) jday, an integer representation of Julian Date, specifically       * jday = int(JD+0.5) or jday=int(MJD+2400001). [Recall that JD = MJD +       * 2400000.5 and MJD is an integer when second-of-day==0. N.B. jday is       * NOT == JD or Julian Date, but DayTime::JD() does return JD.]       * (2) mSod, the integer part of milliseconds of the day, and       * (3) mSec, the (double) fractional part of milliseconds of the day.       *       * In addition, the representation includes a tolerance value (see below)       * and a time frame. The time frame is a simple way of denoting the       * origin or type of day-time which is stored in the object. See        * #TimeFrame for the list of possible values. The time frame of an        * object is determined in the call to a constructor (default is        * timeFrame=Unknown), and carried forward into other objects.  It may be       * read or changed using member functions setAllButTimeFrame(),        * setTimeFrame(), and getTimeFrame().       *        * The member datum 'double tolerance' is used in DayTime comparisons.       * It defaults to the value of the static        * gpstk::DayTime::DAYTIME_TOLERANCE, but this can be modified with the        * static method setDayTimeTolerance().  Several different default        * tolerances have been defined and are in the DayTime-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 (DayTime::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.       * The range of validity of the jday--calendar routines is approximately       * 4317 B.C. to 4317 A.D.; these limits are incorporated into constants       * DayTime::BEGINNING_OF_TIME and DayTime::END_OF_TIME.       *        * * All DayTime objects that lie outside these limits are disallowed. *       *       * This internal representation allows close to the maximum precision       * possible in the time-of-day. Although, note that the code uses        * FACTOR=1000 everywhere to compute milliseconds, via e.g.        * mSec=seconds/FACTOR, and thus FACTOR could be changed to give a        * different precision. (This has not been tested.)       *       * This representation separates day and time-of-day cleanly.       * Because day and time are logically separated, it is possible to use       * DayTime for day only, or for time only. Thus, for example, one       * could instantiate a DayTime 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 DayTime sets the       * data, not to zero, but to the current (system) time; because there       * is no year 0, a DayTime object with all zero data is invalid!]       *       * When constructing DayTime 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 DayTime.       * In general, DayTime 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.       *       */   class DayTime   {   public:         // ----------- Part  1: exceptions and constants --------------         /**          * @ingroup exceptionclass          * DayTime basic exception class.          */      NEW_EXCEPTION_CLASS(DayTimeException, gpstk::Exception);         /**          * @ingroup exceptionclass          * DayTime formatting ("printing") error exception class.          */      NEW_EXCEPTION_CLASS(FormatException, gpstk::Exception);         /// The various time frames      enum TimeFrame      {         Unknown,    /**< unknown time frame */         UTC,        /**< Coordinated Universal Time (e.g., from NTP) */         LocalSystem,/**< time from a local system clock */         GPS_Tx,     /**< GPS transmit Time (paper clock) (e.g., 15 smooth) */         GPS_Rx,     /**< GPS receive time (paper clock) */            // (e.g., rx data if clock bias is applied)         GPS_SV,     /**< SV time frame (e.g., 211 1.5s/6packs) */         GPS_Receiver/**< Receiver time (e.g., 30s, raw 1.5s) */      };         /**          * @name DayTime-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.          */         //@{         /// time-of-day is stored as long (seconds-of-day)*FACTOR         /// plus double (remaining seconds)/FACTOR      static const long FACTOR;         /// Conversion offset, Julian Date to Modified Julian Date.      static const double JD_TO_MJD;         /// 'Julian day' offset from MJD      static const long MJD_JDAY;         /// 'Julian day' of GPS epoch (Jan. 1, 1980).      static const long GPS_EPOCH_JDAY;         /// Modified Julian Date of GPS epoch (Jan. 1, 1980).      static const long GPS_EPOCH_MJD;         /// Modified Julian Date of UNIX epoch (Jan. 1, 1970).      static const long UNIX_MJD;         /// Seconds per half a GPS week.      static const long HALFWEEK;         /// Seconds per whole GPS week.      static const long FULLWEEK;         /// Seconds per day.      static const long SEC_DAY;         /// Milliseconds in a day.      static const long MS_PER_DAY;         /// One nanosecond tolerance.      static const double ONE_NSEC_TOLERANCE;         /// One microsecond tolerance.      static const double ONE_USEC_TOLERANCE;         /// One millisecond tolerance.      static const double ONE_MSEC_TOLERANCE;         /// One second tolerance.      static const double ONE_SEC_TOLERANCE;         /// One minute tolerance.      static const double ONE_MIN_TOLERANCE;         /// One hour tolerance.      static const double ONE_HOUR_TOLERANCE;               /// Default tolerance for time equality in days.      static double DAYTIME_TOLERANCE;         /// 'julian day' of earliest epoch expressible by DayTime:         /// 1/1/4713 B.C.      static const long BEGIN_LIMIT_JDAY;         /// 'julian day' of latest epoch expressible by DayTime:         /// 1/1/4713 A.D.      static const long END_LIMIT_JDAY;         /// earliest representable DayTime      static const DayTime BEGINNING_OF_TIME;         /// latest representable DayTime      static const DayTime END_OF_TIME;         /// If true, check the validity of inputs.          /// Throw DayTimeException on failure.      static bool DAYTIME_TEST_VALID;         //@}               // ----------- Part  2: member functions: tolerance ------------         //         /// Changes the DAYTIME_TOLERANCE for all DayTime objects      static double setDayTimeTolerance(const double tol)         throw()      { DAYTIME_TOLERANCE = tol; return DAYTIME_TOLERANCE; }         /// Returns the current DAYTIME_TOLERANCE.      static double getDayTimeTolerance()          throw()      { return DAYTIME_TOLERANCE; }            /**          * 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.          * @param tol Tolerance in days to be used by comparison operators.          * @sa DayTime-Specific Definitions          */      DayTime& setTolerance(const double tol) throw();         /**           * Return the tolerance value currently in use by this object.          * @return the current tolerance value (in seconds, of course)          */      double getTolerance() throw()      { return tolerance; }         // ----------- Part  3: member functions: constructors ------------         //         /**          * Default constructor.          * Initializes to current system time.          */      DayTime()         throw(DayTimeException);         /**          * GPS time with full week constructor.          * @param GPSWeek full week number          * @param GPSSecond seconds of week.          * @param f Time frame (see #TimeFrame)          */      DayTime(short GPSWeek,              double GPSSecond,              TimeFrame f = Unknown)         throw(DayTimeException);         /**          * GPS time constructor. In the case of 10-bit week input,          * the year and week are used to deduce the number of GPS          * week rollovers and thus the full GPS week.          * @param GPSWeek week number.          * @param GPSSecond Seconds of week.          * @param year Four-digit year consistent with GPS input.          * @param f Time frame (see #TimeFrame)          */      DayTime(short GPSWeek,              double GPSSecond,              short year,               TimeFrame f = Unknown)         throw(DayTimeException);         /**          * GPS time constructor. In the case of 10-bit week input,          * the year and week are used to deduce the number of GPS          * week rollovers and thus the full GPS week.          * @param GPSWeek GPS week number.          * @param zcount Z-count (seconds of week / 1.5)          * @param year Four-digit year consistent with GPS input.          * @param f Time frame (see #TimeFrame)          */      DayTime(short GPSWeek,               long zcount,              short year,              TimeFrame f = Unknown)         throw(DayTimeException);         /**          * GPS time constructor given the full Z count.          * @warn The number of GPS week rollovers, and therefore the          * full GPS week, is determined from the current system time.          * @param fullZcount Full z-count (3 MSB unused, mid 10 bits -          *   week number, 19 LSB "normal" z-count).          * @param f Time frame (see #TimeFrame)          */      DayTime(unsigned long fullZcount,               TimeFrame f = Unknown)         throw(DayTimeException);         /**          * GPS Zcount constructor.          * @warn The number of GPS week rollovers, and therefore the          * full GPS week, is determined from the current system time.          * @param z GPSZcount object to set to          * @param f Time frame (see #TimeFrame)          */      DayTime(const GPSZcount& z,              TimeFrame f = Unknown)         throw(DayTimeException);         /**          * CommonTime constructor.          * @param c CommonTime object to set to          * @param f Time frame (see #TimeFrame)          */      DayTime(const CommonTime& c,              TimeFrame f = Unknown)         throw(DayTimeException);         /**          * Calendar time constructor.          * @param year four-digit year.          * @param month month of year (1-based).          * @param day day of month (1-based).          * @param hour hour of day.          * @param minute minutes of hour.          * @param second seconds of minute.          * @param f Time frame (see #TimeFrame)          */      DayTime(short year,              short month,              short day,              short hour,              short minute,              double second,              TimeFrame f = Unknown)         throw(DayTimeException);         /**          * Modified Julian date time constructor.          * @warn For some compilers, this result may have diminished accuracy.          * @param MJD Modified Julian date as long double.          * @param f Time frame (see #TimeFrame)          */      DayTime(long double MJD,               TimeFrame f = Unknown)         throw(DayTimeException);         /**          * Modified Julian date time constructor.          * @warn For some compilers, this result may have diminished accuracy.          * @param MJD Modified Julian date as double.          * @param f Time frame (see #TimeFrame)          */      DayTime(double MJD,               TimeFrame f = Unknown)         throw(DayTimeException);         /**          * Day of year time constructor.          * @param year Four-digit year.          * @param DOY Day of year.          * @param SOD Seconds of day.          * @param f Time frame (see #TimeFrame)          */      DayTime(short year,              short doy,              double sod,               TimeFrame f = Unknown)         throw(DayTimeException);         /**