timevalue.hpp

Go to the documentation of this file.

/*
  TIMEVALUE.hpp  -  basic definitions for time values and time intervals
 
   Copyright (C)
     2010,            Hermann Vosseler <Ichthyostega@web.de>
 
 **Lumiera** is free software; you can redistribute it and/or modify it
 under the terms of the GNU General Public License as published by the
 Free Software Foundation; either version 2 of the License, or (at your
 option) any later version. See the file COPYING for further details.
 
*/
 
#ifndef LIB_TIME_TIMEVALUE_H
#define LIB_TIME_TIMEVALUE_H
 
#include "lib/error.hpp"
 
#include <boost/operators.hpp>
#include <boost/rational.hpp>
#include <compare>
#include <cstdlib>
#include <string>
 
 
namespace lib {
namespace time {
  
  namespace error = lumiera::error;
  
  // forwards...
  class FrameRate;
  class Duration;
  class TimeSpan;
  class Mutation;
  
  
  using raw_time_64 = int64_t;
  
  
  class TimeValue
    {
    protected:
      raw_time_64 t_;
      
      
      TimeValue&
      operator= (TimeValue const& o)
        {
          t_ = o.t_;
          return *this;
        }
      
      friend class Mutation;
      
      static raw_time_64 limitedTime (raw_time_64 raw);
      static raw_time_64 limitedDelta (raw_time_64 origin, raw_time_64 target);
      
      TimeValue (TimeValue const& origin, TimeValue const& target)
        : t_{limitedDelta (origin.t_, target.t_)}
        { }
      
    public:
      static const raw_time_64 SCALE;
      
      
      explicit
      TimeValue (raw_time_64 val)         
        : t_{limitedTime (val)}
        { }
      
      TimeValue (TimeValue const& o)
        : t_(o.t_)
        { }
      
      friend raw_time_64 _raw (TimeValue const& time) { return time.t_; }
      friend HashVal hash_value (TimeValue const&);
      static TimeValue buildRaw_(raw_time_64);
      
      explicit operator std::string()  const;
      
      bool isRegular()  const;
      
      // Supporting strong total ordering
      std::strong_ordering operator<=> (TimeValue const&) const  =default;
      bool                 operator==  (TimeValue const&) const  =default;
      
      std::strong_ordering operator<=> (raw_time_64 tt)   const { return t_ <=> tt; }
      bool                 operator==  (raw_time_64 tt)   const { return t_ ==  tt; }
    };
  
  
  
  
  
  
  
  /* ======= specific Time entities ==================== */
  
  using FrameCnt = int64_t;
  
  using FSecs = boost::rational<int64_t>;
  
  
  
  class TimeVar
    : public TimeValue
    , boost::additive<TimeVar,
      boost::additive<TimeVar, TimeValue,
      boost::multipliable<TimeVar, int>
      > >
    {
    public:
      TimeVar (TimeValue const& time = TimeValue(0))
        : TimeValue(time)
        { }
      
      TimeVar (FSecs const&);
      
      TimeVar (TimeVar const& o)
        : TimeValue(o)
        { }
      
      TimeVar& operator= (TimeVar const&) = default;
      TimeVar& operator= (TimeValue const& o)
        {
          *this = TimeVar(o);
          return *this;
        }
      
      operator FSecs()  const { return FSecs{t_, TimeValue::SCALE}; }
      
      TimeVar& operator+= (TimeVar const& tx)  { t_ += tx.t_; return *this; }
      TimeVar& operator-= (TimeVar const& tx)  { t_ -= tx.t_; return *this; }
      
      TimeVar& operator*= (int64_t fact)       { t_ *= fact;  return *this; }
      
      TimeVar  operator-  ()         const     { return TimeVar(*this)*=-1; }
       
      // baseclass TimeValue is already totally_ordered
    };
  
  
  
  
  /**********************************************************/
  class Time
    : public TimeValue
    {
      Time& operator= (Time const);
      
      Time(int);
      
    public:
      static const Time MAX ;
      static const Time MIN ;
      static const Time ZERO;
      
      static const Time ANYTIME;  
      static const Time NEVER;   
      
      explicit
      Time (TimeValue const& val =TimeValue(0))
        : TimeValue(val)
        { }
      
      explicit
      Time (FSecs const& fractionalSeconds);
      
      Time (Time const&) = default;
      
      Time (TimeVar const& calcResult)
        : TimeValue(calcResult)
        { }
      
      Time ( long millis
           , uint secs
           , uint mins =0
           , uint hours=0
           );
      
      explicit operator std::string()  const;
      
      TimeVar operator+ (TimeValue const& tval)  const { return TimeVar(*this) + tval; }
      TimeVar operator- (TimeValue const& tval)  const { return TimeVar(*this) - tval; }
      TimeVar operator- ()                       const { return -TimeVar(*this); }
    };
  
  
  
  
  class Offset
    : public TimeValue
    {
    protected:
      Offset&
      operator= (Offset const& o)
        {
          TimeValue::operator= (o);
          return *this;
        }
      
    public:
      explicit
      Offset (TimeValue const& distance =Time::ZERO);
      
      explicit
      Offset (FSecs const& delta_in_secs);
      
      Offset (Offset const&) = default;
      
      Offset (FrameCnt count, FrameRate const& fps);
      
      Offset (TimeValue const& origin, TimeValue const& target)
        : TimeValue{origin, target}
        { }
      
      static const Offset ZERO;
      
      Duration abs()  const;
      
      Offset stretchedByRationalFactor (boost::rational<int64_t>)  const;
      Offset stretchedByFloatFactor    (double)  const;
      
      explicit operator std::string()  const;
      
      // Supporting sign flip
      Offset operator- ()  const;
    };
  
  //-- support linear offset chaining ---------------
  
  inline Offset
  operator+ (Offset const& start, Offset const& toChain)
  {
    TimeVar distance(start);
    distance += toChain;
    return Offset(distance);
  }
  
  inline Offset
  operator- (Offset const& start, Offset const& toSubtract)
  {
    TimeVar distance(start);
    distance -= toSubtract;
    return Offset(distance);
  }
  
  template<typename FAC>
  inline Offset
  operator* (Offset const& distance, FAC factor)
  {
    return factor*distance;
  }
  
  template<typename INT>
  inline Offset
  operator* (INT factor, Offset const& o)
  {
    TimeVar distance(o);
    distance *= factor;
    return Offset(distance);
  }
  
  template<typename INTX>
  inline Offset
  operator* (boost::rational<INTX> factor, Offset const& offset)
  {
    return offset.stretchedByRationalFactor (boost::rational<int64_t>(factor.numerator(), factor.denominator()));
  }
  
  inline Offset
  operator* (double factor, Offset const& offset)
  {
    return offset.stretchedByFloatFactor (factor);
  }
  
  
  inline Offset
  Offset::operator- ()  const
  {
    return -1 * (*this);
  }
  
  
  
  
  class Duration
    : public TimeValue
    {
      Duration& operator= (Duration const&);
      
    public:
      Duration()
        : TimeValue{Time::ZERO}
        { }
      
      Duration (Offset const& distance)
        : TimeValue{buildRaw_(llabs (_raw(distance)))}
        { }
      
      explicit
      Duration (TimeValue const& timeSpec)
        : Duration{Offset{timeSpec}}
        { }
      
      Duration (FSecs const& timeSpan_in_secs)
        : Duration{Offset{timeSpan_in_secs}}
        { }
      
      Duration (FrameCnt count, FrameRate const& fps)
        : Duration{Offset{count,fps}}
        { }
      
      Duration (TimeSpan const& interval);
      
      Duration (Duration const& o)
        : TimeValue{o}
        {// assuming that negative Duration can not be constructed....
          REQUIRE (t_ >= 0, "Copy rejected: negative Duration %lu", o.t_);
        }
      
      static const Duration NIL;
      static const Duration MAX ;
      
      void accept (Mutation const&);
      
      
      explicit operator std::string()  const;
 
      Offset operator- ()  const;
      
    };
    
  //-- support combining and Durations ---------------
  
  inline Duration
  operator+ (Duration const& base, Duration const& toAdd)
  {
    return Offset(base) + Offset(toAdd);
  }
  
  inline Duration
  operator- (Duration const& base, Duration const& toRemove)
  {
    return base > toRemove? Offset(base) - Offset(toRemove)
                          : Duration::NIL;
  }
  
  template<typename NUM>
  inline Offset
  operator* (NUM factor, Duration const& dur)
  {
    return factor * Offset(dur);
  }
  
  template<typename NUM>
  inline Offset
  operator* (Duration const& dur, NUM factor)
  {
    return factor*dur;
  }
  
  inline Offset
  Duration::operator- ()  const
  {
    return -1 * (*this);
  }
  
  
  
  class TimeSpan
    : public Time
    {
      Duration dur_;
      
    public:
      TimeSpan(TimeValue const& start, Duration const& length)
        : Time(start)
        , dur_(length)
        { }
      
      TimeSpan(TimeValue const& start, FSecs(duration_in_secs))
        : Time(start)
        , dur_(duration_in_secs)
        { }
      
      TimeSpan(TimeValue const& start, TimeValue const& end)
        : Time(start<=end? start:end)
        , dur_(Offset(start,end))
        { }
      
      TimeSpan(TimeValue const& start, Offset const& reference_distance)
        : TimeSpan{start, Time{start} + reference_distance}
        { }
      
      TimeSpan()
        : TimeSpan(Time::ZERO, Time::ZERO)
        { }
      
      TimeSpan conform()  const;  
      
      static const TimeSpan ALL;
      
      Duration&
      duration()
        {
          return dur_;
        }
      
      Duration
      duration()  const
        {
          return dur_;
        }
      
      Time
      start()  const
        {
          return *this;
        }
      
      Time
      end()  const
        {
          return TimeVar(*this) += dur_;
        }
      
      bool
      contains (TimeValue const& tp)  const
        {
          return *this <= tp
             and tp < end();
        }
      
      void accept (Mutation const&);
      
      explicit operator std::string()  const;
      
      std::strong_ordering
      operator<=> (TimeSpan const& ts)  const
        {
          auto ord{ t_ <=> ts.t_ };
          return ord != 0? ord
                         : dur_ <=> ts.dur_;
        }
      bool operator== (TimeSpan const& ts) const  =default;
    };
  
  
  class FrameRate
    : public boost::rational<uint>
    {
    public:
      FrameRate (uint fps) ;
      FrameRate (uint num, uint denom);
      FrameRate (size_t count, Duration timeReference);
      explicit
      FrameRate (boost::rational<uint> fractionalRate);
      
      static FrameRate approx(double fps);
      
      // standard copy acceptable;
      
      double asDouble()  const;
      
      static const FrameRate PAL;
      static const FrameRate NTSC;
      static const FrameRate STEP;       
      
      static const FrameRate HALTED;
      
      Duration duration() const;
      
      std::strong_ordering operator<=>(FrameRate const&) const = default;
      
      explicit operator std::string() const;
    };
  
  inline FSecs
  operator/ (int n, FrameRate rate)
  {
    return FSecs{ n*rate.denominator(), rate.numerator()};
  }
  
  
  
  
  /* == implementations == */
    
  namespace { // implementation helpers...
    
    template<typename NUM>
    inline NUM
    __ensure_nonzero (NUM n)
    {
      if (n == NUM{0})
        throw error::Logic ("Degenerated frame grid not allowed"
                           , LERR_(BOTTOM_VALUE));
      return n;
    }
    
    inline raw_time_64
    symmetricLimit (raw_time_64 raw, TimeValue lim)
    {
      return  raw > lim?  _raw(lim)
           : -raw > lim? -_raw(lim)
           :               raw;
    }
  }//(End) implementation helpers
  
  
  
  
  inline HashVal
  hash_value (TimeValue const& time)
  {
    HashVal x = _raw(time);                 // possibly cap to size of hash
    const uint width = sizeof(HashVal) * CHAR_BIT;
    const uint mask = width-1;
    const uint n = width / 2;
    
    static_assert (0 < n  and n <= mask);
    return (x<<n) | (x>>((-n)&mask ));
  }
  
  
  inline raw_time_64
  TimeValue::limitedTime (raw_time_64 raw)
  {
    return symmetricLimit (raw, Time::MAX);
  }
  
  inline raw_time_64
  TimeValue::limitedDelta (raw_time_64 origin, raw_time_64 target)
  {
    if (0 > (origin^target))
      {// prevent possible numeric wrap
        origin = symmetricLimit (origin, Duration::MAX);
        target = symmetricLimit (target, Duration::MAX);
      }
    raw_time_64 res = target - origin;
    return symmetricLimit (res, Duration::MAX);
  }
  
  inline TimeSpan
  TimeSpan::conform()  const          
  {
    Offset extension{dur_};
    TimeValue start{_raw(*this)};
    return Offset{start} + extension > Time::MAX? TimeSpan{Time::MAX-extension, Time::MAX}
                                                : TimeSpan{start, extension};
  }
  
  inline bool
  TimeValue::isRegular()  const
  {
    return Time::MIN < *this
       and *this < Time::MAX;
  }
  
  
  inline
  TimeVar::TimeVar (FSecs const& fractionalSeconds)
    : TimeVar{Time(fractionalSeconds)}
    { }
  
  inline
  Offset::Offset (TimeValue const& distance)
    : TimeValue{buildRaw_(symmetricLimit(_raw(distance)
                                        , Duration::MAX))}
    { }
  
  inline
  Duration::Duration (TimeSpan const& interval)
    : Duration{interval.duration()}
    { }
  
  inline
  FrameRate::FrameRate (uint fps)
    : boost::rational<uint> (__ensure_nonzero(fps))
    { }
  
  inline
  FrameRate::FrameRate (uint num, uint denom)
    : boost::rational<uint> (__ensure_nonzero(num), denom)
    { }
  
  inline
  FrameRate::FrameRate (boost::rational<uint> fractionalRate)
    : boost::rational<uint> (__ensure_nonzero(fractionalRate))
    { }
  
  boost::rational<uint> __framerate_approximation (size_t, Duration);
  boost::rational<uint> __framerate_approximation (double);
  
  inline
  FrameRate::FrameRate (size_t count, Duration timeReference)
    : FrameRate{__framerate_approximation (count, timeReference)}
    { }
  
  inline FrameRate
  FrameRate::approx (double fps)
  {
    return FrameRate{__framerate_approximation (fps)};
  }
  
  
  inline double
  FrameRate::asDouble()  const
  {
    return boost::rational_cast<double> (*this);
  }
  
  inline Duration
  Offset::abs()  const
  {
    return Duration{*this};
  }
  
  
  
}} // lib::time
 
 
namespace util {
  
  inline bool
  isnil (lib::time::Duration const& dur)
  {
    return 0 == dur;
  }
 
  // repeated or forward declaration, see meta/util.hpp
  template<typename X, typename COND>
  struct StringConv;
  
  template<>
  struct StringConv<lib::time::FSecs, void>
    {
      static std::string
      invoke (lib::time::FSecs) noexcept;
    };
}
#endif /*LIB_TIME_TIMEVALUE_H*/