daytime.hpp

gps源代码

#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 code
struct 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);

         /**