//
// File   : TimeConvert.hh
//
// Purpose: Provide some functions to convert between different time scales.
//
// $Id: TimeConvert.hh 8758 2010-09-27 12:16:24Z mathes $
//



/** @file TimeConvert.hh
  * Provide some functions to convert between different time scales.
  * @author H.-J. Mathes, FzK
  */

#ifndef _FdUtil_TimeConvert_hh_
#define _FdUtil_TimeConvert_hh_

#include <iostream>
#include <string>
#include <vector>
#include <ctime>

#ifndef NO_VERSION
# include <FdUtilVersion.hh>
#endif // NO_VERSION

#include <ctime>

// --- forward declaration(s)

namespace FdUtil {
  class InifileChain;
}

namespace FdUtil {
    
/** @section time Time coordinates
  * 
  * The shift between the begin of the UTC epoch (1.1.1972 0:00) and the
  * begin of the GPS epoch (6.1.1980 0:00 UTC). UTC counts the number of seconds
  * since the begin of its epoch including the leap seconds which are usually
  * inserted at 06-30 0:00 UTC or 12-31 0:00 UTC. These leap seconds are
  * announced at least 6 months in advance. GPS time standard counts also the
  * number of leap seconds.
  *
  * The Unix system time available via the time() and gettimeofday() functions
  * however, do not take into account the leap seconds which have been 
  * introduced since 1970. In addition they assume a simple rule for the leap 
  * years which until now did not have any effect.
  *
  * For 2001-12-31 no leap second is announced !
  *
  * <b>IMPORTANT !!!</b>
  * As the times are stored everywhere in the FD system as UTC it is necessary
  * that the software is updated after a leap second has occurred.
  * @see FdRoot::TTimeStamp
  */

/** A class with methods to convert between different time scales.
  */
class TimeConvert {
public:
    /** Get the current time in GPS stime scale. */
    static unsigned int GetGPSTime()
     { return GetGPSTimeFromUnixTime( GetUnixTime() ); }

    /** Calculate the GPS time from the systems time. */
    static unsigned int GetGPSTimeFromUnixTime(unsigned int);

    /** Get the date formatted in ISO 8601 compliant format. */
    static std::string GetISODate(const struct tm&);

    /** Get the time formatted in ISO ???? compliant format. 
      *
      * The optional parameter 'seconds' is to switch off the seconds value
      * in the returned string.
      */
    static std::string GetISOTime(const struct tm&,bool=true);
    
    /** Get a string for the ASCII representation of the GPS time. */
    static std::string GetTimeStringFromGPSTime(unsigned int,
                                                const std::string="");

    /** Get a string for the ASCII representation of the Unix time. */
    static std::string GetTimeStringFromUnixTime(unsigned int,
                                                 const std::string="");

    /** Retrieve the current unix time. */
    static unsigned int GetUnixTime()
     { return std::time(NULL); }

    /** Retrieve the GPS time converted back into Unix time. */
    static unsigned int GetUnixTimeFromGPSTime(unsigned int);
    
    /** Print a table of leap seconds. */
    static void PrintLeapSecondTable(std::ostream& ostr=std::cout);

    /** Read the table of leap seconds from a file.
      *
      * The leap seconds which are initialized already by the static
      * table cannot be overwritten by (possibly) faulty entries in
      * the file - but we will print a warning.
      *
      * Note: Please note that this method is not called within this class
      *       but it might be called by some application if needed.
      */
    static void ReadLeapSecondTable(std::string filename="FDcommon.ini");
    
    /** Read the table of leap seconds from a chain of ini-files. */
    static void ReadLeapSecondTable(FdUtil::InifileChain&);
    
protected:

    /** Struct containing one entry for a leap second. */
    typedef struct _LeapSecondEntryRec {
    
      unsigned int fGPSTime;
      unsigned int fNLeapSeconds;
      
    } LeapSecondEntryRec;
    
    /** Calculate number of leap seconds since GPS epoch. */
    static unsigned int GetLeapSeconds(unsigned int);
    
    /** Get a string for the ASCII representation of the Unix time. 
      *
      * A format string might be specified which is interpreted according to
      * C-function stftime() (@see man strftime).
      */
    static std::string GetFormattedFromTm(const struct tm *tm_struct,
                                          const std::string ="");

    /** Check if the time sits directly on a leap second. */
    static bool IsLeapBoundary(unsigned int);
    
    /** Init the leap second table. */
    static void InitLeapSecondTable();
    
    /** Used to sort a STL container with LeapSecondEntryRec. */
    static bool LeapSecondEntryLess(const LeapSecondEntryRec&,
                                    const LeapSecondEntryRec&);
    
    /** Table of leap seconds. */
    static std::vector<LeapSecondEntryRec> fLeapSecondTable;
};

}  // namespace FdUtil

#endif  // _FdUtil_TimeConvert_hh_