TimePoint.h

Go to the documentation of this file.

//     ____   ______ __
//    / __ \ / ____// /
//   / /_/ // /    / /
//  / ____// /___ / /___   PixInsight Class Library
// /_/     \____//_____/   PCL 2.7.0
// ----------------------------------------------------------------------------
// pcl/TimePoint.h - Released 2024-06-18T15:48:54Z
// ----------------------------------------------------------------------------
// This file is part of the PixInsight Class Library (PCL).
// PCL is a multiplatform C++ framework for development of PixInsight modules.
//
// Copyright (c) 2003-2024 Pleiades Astrophoto S.L. All Rights Reserved.
//
// Redistribution and use in both source and binary forms, with or without
// modification, is permitted provided that the following conditions are met:
//
// 1. All redistributions of source code must retain the above copyright
//    notice, this list of conditions and the following disclaimer.
//
// 2. All redistributions in binary form must reproduce the above copyright
//    notice, this list of conditions and the following disclaimer in the
//    documentation and/or other materials provided with the distribution.
//
// 3. Neither the names "PixInsight" and "Pleiades Astrophoto", nor the names
//    of their contributors, may be used to endorse or promote products derived
//    from this software without specific prior written permission. For written
//    permission, please contact info@pixinsight.com.
//
// 4. All products derived from this software, in any form whatsoever, must
//    reproduce the following acknowledgment in the end-user documentation
//    and/or other materials provided with the product:
//
//    "This product is based on software from the PixInsight project, developed
//    by Pleiades Astrophoto and its contributors (https://pixinsight.com/)."
//
//    Alternatively, if that is where third-party acknowledgments normally
//    appear, this acknowledgment must be reproduced in the product itself.
//
// THIS SOFTWARE IS PROVIDED BY PLEIADES ASTROPHOTO AND ITS CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
// TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PLEIADES ASTROPHOTO OR ITS
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, BUSINESS
// INTERRUPTION; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; AND LOSS OF USE,
// DATA OR PROFITS) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
// CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
// POSSIBILITY OF SUCH DAMAGE.
// ----------------------------------------------------------------------------
 
#ifndef __PCL_TimePoint_h
#define __PCL_TimePoint_h
 
 
#include <pcl/Defs.h>
 
#include <pcl/Math.h>
#include <pcl/String.h>
 
/*
 * N.B.: Remove potentially conflicting names that may be defined by 3rd-party
 * packages used by some standard modules.
 */
#ifdef J2000
# undef J2000
#endif
#ifdef J2100
# undef J2100
#endif
#ifdef B1950
# undef B1950
#endif
 
namespace pcl
{
 
// ----------------------------------------------------------------------------
 
// ----------------------------------------------------------------------------
 
struct FileTime;
 
class PCL_CLASS TimePoint
{
public:
 
   TimePoint() = default;
 
   TimePoint( double jd )
      : m_jdi( TruncInt( jd ) )
      , m_jdf( Frac( jd ) )
   {
   }
 
   TimePoint( double jd1, double jd2 )
      : m_jdi( TruncInt( jd1 ) + TruncInt( jd2 ) )
      , m_jdf( Frac( jd1 ) + Frac( jd2 ) )
   {
      Normalize();
   }
 
   TimePoint( int year, int month, double days )
   {
      CalendarTimeToJD( m_jdi, m_jdf, year, month, TruncInt( days ), Frac( days ) );
   }
 
   TimePoint( int year, int month, int day, double dayFraction )
   {
      CalendarTimeToJD( m_jdi, m_jdf, year, month, day, dayFraction );
   }
 
   TimePoint( int year, int month, int day, int hour, int minute, double seconds )
   {
      CalendarTimeToJD( m_jdi, m_jdf, year, month, day, (hour + (minute + seconds/60)/60)/24 );
   }
 
   TimePoint( const IsoString& dateTime )
   {
      int year, month, day;
      double dayf, tz;
      dateTime.ParseISO8601DateTime( year, month, day, dayf, tz );
      CalendarTimeToJD( m_jdi, m_jdf, year, month, day, dayf - tz/24 );
   }
 
   TimePoint( const String& dateTime )
   {
      int year, month, day;
      double dayf, tz;
      dateTime.ParseISO8601DateTime( year, month, day, dayf, tz );
      CalendarTimeToJD( m_jdi, m_jdf, year, month, day, dayf - tz/24 );
   }
 
   TimePoint( time_t time );
 
   TimePoint( const FileTime& fileTime );
 
   TimePoint( const TimePoint& ) = default;
 
   TimePoint& operator =( const TimePoint& ) = default;
 
   constexpr bool IsValid() const
   {
      return ((m_jdi > 0) ? m_jdi : -m_jdi) < 2147438065;
   }
 
   void GetCalendarTime( int& year, int& month, int& day ) const
   {
      double dum;
      JDToCalendarTime( year, month, day, dum, m_jdi, m_jdf );
   }
 
   void GetCalendarTime( int& year, int& month, int& day, double& dayf ) const
   {
      JDToCalendarTime( year, month, day, dayf, m_jdi, m_jdf );
   }
 
   void GetCalendarTime( int& year, int& month, int& day, int& hour, int& minute, double& seconds ) const
   {
      double dayf;
      JDToCalendarTime( year, month, day, dayf, m_jdi, m_jdf );
      double h = Frac( dayf )*24;
      double m = Frac( h )*60;
      seconds = Frac( m )*60;
      minute = TruncInt( m );
      hour = TruncInt( h );
   }
 
   int Year() const
   {
      int year, foo; double bar;
      JDToCalendarTime( year, foo, foo, bar, m_jdi, m_jdf );
      return year;
   }
 
   int Month() const
   {
      int foo, month; double bar;
      JDToCalendarTime( foo, month, foo, bar, m_jdi, m_jdf );
      return month;
   }
 
   int Day() const
   {
      int foo, day; double bar;
      JDToCalendarTime( foo, foo, day, bar, m_jdi, m_jdf );
      return day;
   }
 
   double DayFraction() const
   {
      int foobar; double dayf;
      JDToCalendarTime( foobar, foobar, foobar, dayf, m_jdi, m_jdf );
      return dayf;
   }
 
   String ToString( const ISO8601ConversionOptions& options = ISO8601ConversionOptions(), double tz = 0 ) const
   {
      return ToString( options, tz, (String*)0 );
   }
 
   String ToString( unsigned timeItems, unsigned precision = 3, double tz = 0, bool timeZone = true, bool zuluTime = true ) const
   {
      return ToString( ISO8601ConversionOptions( timeItems, precision, timeZone, zuluTime ), tz );
   }
 
   IsoString ToIsoString( const ISO8601ConversionOptions& options = ISO8601ConversionOptions(), double tz = 0 ) const
   {
      return ToString( options, tz, (IsoString*)0 );
   }
 
   IsoString ToIsoString( unsigned timeItems, unsigned precision = 3, double tz = 0, bool timeZone = true, bool zuluTime = true ) const
   {
      return ToIsoString( ISO8601ConversionOptions( timeItems, precision, timeZone, zuluTime ), tz );
   }
 
   String ToString( const String& format ) const;
 
   IsoString ToIsoString( const IsoString& format ) const;
 
   IsoString ToIsoString( const char* format ) const
   {
      return ToIsoString( IsoString( format ) );
   }
 
   explicit operator String() const
   {
      return ToString();
   }
 
   explicit operator IsoString() const
   {
      return ToIsoString();
   }
 
   constexpr int JDI() const
   {
      return m_jdi;
   }
 
   constexpr double JDF() const
   {
      return m_jdf;
   }
 
   constexpr double JD() const
   {
      return m_jdi + m_jdf;
   }
 
   constexpr double MJD() const
   {
      return (m_jdi-2400000) + (m_jdf-0.5);
   }
 
   double DeltaT() const;
 
   static bool IsDeltaTExtrapolationEnabled();
 
   static void EnableDeltaTExtrapolation( bool enable = true );
 
   static void DisableDeltaTExtrapolation( bool disable = true )
   {
      EnableDeltaTExtrapolation( !disable );
   }
 
   double DeltaAT() const;
 
   TimePoint& operator +=( double days )
   {
      m_jdf += days;
      Normalize();
      return *this;
   }
 
   TimePoint& operator -=( double days )
   {
      m_jdf -= days;
      Normalize();
      return *this;
   }
 
   constexpr double DaysSince( const TimePoint& t ) const
   {
      return m_jdi-t.m_jdi + m_jdf-t.m_jdf;
   }
 
   constexpr double YearsSince( const TimePoint& t ) const
   {
      return DaysSince( t )/365.25;
   }
 
   constexpr double CenturiesSince( const TimePoint& t ) const
   {
      return DaysSince( t )/36525;
   }
 
   constexpr double SecondsSince( const TimePoint& t ) const
   {
      return DaysSince( t )*86400;
   }
 
   constexpr double DaysSinceReferenceEpoch() const
   {
      return DaysSinceJ2000();
   }
 
   constexpr double YearsSinceReferenceEpoch() const
   {
      return YearsSinceJ2000();
   }
 
   constexpr double CenturiesSinceReferenceEpoch() const
   {
      return CenturiesSinceJ2000();
   }
 
   constexpr double SecondsSinceReferenceEpoch() const
   {
      return SecondsSinceJ2000();
   }
 
   constexpr double DaysSinceJ2000() const
   {
      return m_jdi-2451545 + m_jdf;
   }
 
   constexpr double YearsSinceJ2000() const
   {
      return DaysSinceJ2000()/365.25;
   }
 
   constexpr double CenturiesSinceJ2000() const
   {
      return DaysSinceJ2000()/36525;
   }
 
   constexpr double SecondsSinceJ2000() const
   {
      return DaysSinceJ2000()*86400;
   }
 
   constexpr double DaysSinceUNIXEpoch() const
   {
      return m_jdi-2440587 + m_jdf-0.5;
   }
 
   constexpr double YearsSinceUNIXEpoch() const
   {
      return DaysSinceUNIXEpoch()/365.25;
   }
 
   constexpr double CenturiesSinceUNIXEpoch() const
   {
      return DaysSinceUNIXEpoch()/36525;
   }
 
   constexpr double SecondsSinceUNIXEpoch() const
   {
      return DaysSinceUNIXEpoch()*86400;
   }
 
   constexpr double MillisecondsSinceUNIXEpoch() const
   {
      return DaysSinceUNIXEpoch()*86400000;
   }
 
   double SystemOffsetFromUTC() const;
 
   TimePoint UTCToLocalTime() const
   {
      return TimePoint( m_jdi, m_jdf + SystemOffsetFromUTC()/24 );
   }
 
   TimePoint LocalTimeToUTC() const
   {
      return TimePoint( m_jdi, m_jdf - SystemOffsetFromUTC()/24 );
   }
 
   static TimePoint Now();
 
   static TimePoint ReferenceEpoch()
   {
      return J2000();
   }
 
   static TimePoint J2000()
   {
      TimePoint t;
      t.m_jdi = 2451545;
      t.m_jdf = 0;
      return t;
   }
 
   static TimePoint J2100()
   {
      TimePoint t;
      t.m_jdi = 2488070;
      t.m_jdf = 0;
      return t;
   }
 
   static TimePoint B1950()
   {
      TimePoint t;
      t.m_jdi = 2433282;
      t.m_jdf = 0.42345905;
      return t;
   }
 
   static TimePoint UNIXEpoch()
   {
      TimePoint t;
      t.m_jdi = 2440587;
      t.m_jdf = 0.5;
      return t;
   }
 
   static TimePoint FromString( double& tz, const IsoString& dateTime )
   {
      int year, month, day;
      double dayf;
      dateTime.ParseISO8601DateTime( year, month, day, dayf, tz );
      return TimePoint( year, month, day, dayf - tz/24 );
   }
 
   static TimePoint FromString( double& tz, const String& dateTime )
   {
      int year, month, day;
      double dayf;
      dateTime.ParseISO8601DateTime( year, month, day, dayf, tz );
      return TimePoint( year, month, day, dayf - tz/24 );
   }
 
   static TimePoint FromString( const IsoString& dateTime )
   {
      return TimePoint( dateTime );
   }
 
   static TimePoint FromString( const String& dateTime )
   {
      return TimePoint( dateTime );
   }
 
   static bool TryFromString( TimePoint& t, double& tz, const IsoString& dateTime )
   {
      int year, month, day;
      double dayf;
      if ( dateTime.TryParseISO8601DateTime( year, month, day, dayf, tz ) )
      {
         t = TimePoint( year, month, day, dayf - tz/24 );
         return true;
      }
      return false;
   }
 
   static bool TryFromString( TimePoint& t, double& tz, const String& dateTime )
   {
      int year, month, day;
      double dayf;
      if ( dateTime.TryParseISO8601DateTime( year, month, day, dayf, tz ) )
      {
         t = TimePoint( year, month, day, dayf - tz/24 );
         return true;
      }
      return false;
   }
 
   static bool TryFromString( TimePoint& t, const IsoString& dateTime )
   {
      double tz;
      return TryFromString( t, tz, dateTime );
   }
 
   static bool TryFromString( TimePoint& t, const String& dateTime )
   {
      double tz;
      return TryFromString( t, tz, dateTime );
   }
 
private:
 
   int32  m_jdi = int32_max; // invalid by default
   double m_jdf = 0.0;
 
   void Normalize()
   {
      m_jdi += TruncInt( m_jdf );
      m_jdf = Frac( m_jdf );
      if ( m_jdf != 0 )
         if ( m_jdf < 0 )
         {
            if ( m_jdi > 0 )
            {
               --m_jdi;
               m_jdf += 1;
            }
         }
         else if ( m_jdi < 0 )
         {
            ++m_jdi;
            m_jdf -= 1;
         }
   }
 
   template <class S>
   S ToString( const ISO8601ConversionOptions& options, double tz, S* ) const
   {
      if ( IsValid() )
      {
         int year, month, day;
         double dayf;
         JDToCalendarTime( year, month, day, dayf, m_jdi, m_jdf );
         return S::ToISO8601DateTime( year, month, day, dayf, tz, options );
      }
      return S();
   }
};
 
/*
 * ### N.B.: TimePoint cannot have virtual member functions.
 *     This is because sizeof( TimePoint ) _must_ be equal to
 *     sizeof( uint32 ) + sizeof( uint64 ).
 */
struct PCL_AssertTimePointSize
{
   struct TestData { uint32 x; uint64 y; };
   static_assert( sizeof( TimePoint ) == sizeof( TestData ), "Invalid sizeof( TimePoint )" );
};
 
inline constexpr bool operator ==( const TimePoint& t1, const TimePoint& t2 )
{
   return t1.JDI() == t2.JDI() && t1.JDF() == t2.JDF();
}
 
inline constexpr bool operator ==( const TimePoint& t1, double jd2 )
{
   return t1.JD() == jd2;
}
 
inline constexpr bool operator ==( double jd1, const TimePoint& t2 )
{
   return t2.JD() == jd1;
}
 
inline constexpr bool operator <( const TimePoint& t1, const TimePoint& t2 )
{
   return !t1.IsValid() || t2.IsValid() && ((t1.JDI() != t2.JDI()) ? t1.JDI() < t2.JDI() : t1.JDF() < t2.JDF());
}
 
inline constexpr bool operator <( const TimePoint& t1, double jd2 )
{
   return !t1.IsValid() || t1.JD() < jd2;
}
 
inline constexpr bool operator <( double jd1, const TimePoint& t2 )
{
   return t2.IsValid() && jd1 < t2.JD();
}
 
inline constexpr double operator -( const TimePoint& t1, const TimePoint& t2 )
{
   return (t1.JDI() - t2.JDI()) + (t1.JDF() - t2.JDF());
}
 
inline TimePoint operator +( const TimePoint& t, double d )
{
   return TimePoint( t.JDI(), t.JDF()+d );
}
 
inline TimePoint operator +( double d, const TimePoint& t )
{
   return t + d;
}
 
inline TimePoint operator -( const TimePoint& t, double d )
{
   return TimePoint( t.JDI(), t.JDF()-d );
}
 
// ----------------------------------------------------------------------------
 
} // pcl
 
#endif   // __PCL_TimePoint_h
 
// ----------------------------------------------------------------------------
// EOF pcl/TimePoint.h - Released 2024-06-18T15:48:54Z