Fix various bugs in subtitle/ccap verification.

[libdcp.git] / src / dcp_time.h

diff --git a/src/dcp_time.h b/src/dcp_time.h
index e872461487382b6ae4ca6d073bd9bc27190e597e..dbfdb7f0c060c0e3dd4309091137be61f268e182 100644 (file)
--- a/src/dcp_time.h
+++ b/src/dcp_time.h
@@ -1,5 +1,5 @@
 /*
-    Copyright (C) 2012-2015 Carl Hetherington <cth@carlh.net>
+    Copyright (C) 2012-2021 Carl Hetherington <cth@carlh.net>
 
     This file is part of libdcp.
 
@@ -31,20 +31,41 @@
     files in the program, then also delete it here.
 */
 
+
 /** @file  src/dcp_time.h
- *  @brief Time class.
+ *  @brief Time class
  */
 
+
 #ifndef LIBDCP_TIME_H
 #define LIBDCP_TIME_H
 
+
 #include "types.h"
+#include <boost/optional.hpp>
 #include <stdint.h>
 #include <string>
 #include <iostream>
 
+
 namespace dcp {
 
+
+class Time;
+
+
+extern bool operator== (Time const & a, Time const & b);
+extern bool operator!= (Time const & a, Time const & b);
+extern bool operator<= (Time const & a, Time const & b);
+extern bool operator< (Time const & a, Time const & b);
+extern bool operator> (Time const & a, Time const & b);
+extern bool operator>= (Time const & a, Time const & b);
+extern std::ostream & operator<< (std::ostream & s, Time const & t);
+extern Time operator+ (Time a, Time b);
+extern Time operator- (Time a, Time b);
+extern float operator/ (Time a, Time const & b);
+
+
 /** @class Time
  *  @brief A representation of time within a DCP.
  */
@@ -52,10 +73,10 @@ class Time
 {
 public:
        /** Construct a zero Time */
-       Time () : h (0), m (0), s (0), e (0), tcr (1) {}
+       Time () {}
 
        /** Construct a Time.
-        *  @param Frame index (starting from 0).
+        *  @param frame Frame index (starting from 0).
         *  @param frames_per_second Frames per second.
         *  @param tcr Timecode rate.
         */
@@ -76,36 +97,68 @@ public:
                , tcr (tcr_)
        {}
 
+       /** Construct a Time from a number of seconds and a timecode rate
+        *
+        *  @param seconds A number of seconds
+        *  @param tcr_ Timecode rate
+        */
        Time (double seconds, int tcr);
 
-       Time (std::string time, int tcr);
+       /** @param time String of the form
+        *     HH:MM:SS:EE                          for SMPTE
+        *     HH:MM:SS:E[E[E]] or HH:MM:SS.s[s[s]] for Interop
+        *  where HH are hours, MM minutes, SS seconds, EE editable units and
+        *  sss millseconds.
+        *
+        *  @param tcr_ Timecode rate if this is a SMPTE time, otherwise empty for an Interop time
+        */
+       Time (std::string time, boost::optional<int> tcr);
 
-       int h; ///<   hours
-       int m; ///<   minutes
-       int s; ///<   seconds
-       int e; ///<   editable units (where 1 editable unit is 1 / tcr_ seconds)
-       int tcr; ///< timecode rate: the number of editable units per second.
+       int h = 0; ///<   hours
+       int m = 0; ///<   minutes
+       int s = 0; ///<   seconds
+       int e = 0; ///<   editable units (where 1 editable unit is 1 / tcr_ seconds)
+       int tcr = 1; ///< timecode rate: the number of editable units per second.
 
+       /** @return A string of the form h:m:s:e padded as in 00:00:00:000 (for Interop) or 00:00:00:00 (for SMPTE) */
        std::string as_string (Standard standard) const;
+
+       /** @return the total number of seconds that this time consists of */
        double as_seconds () const;
-       int64_t as_editable_units (int tcr_) const;
+
+       /** @param tcr_ Timecode rate with which the return value should be counted
+        *  @return the total number of editable units that this time consists of at the specified timecode rate, rounded down
+        *  to the nearest editable unit. For example, as_editable_units_floor(24) returns the total time in frames at 24fps.
+        */
+       int64_t as_editable_units_floor (int tcr_) const;
+
+       /** @param tcr_ Timecode rate with which the return value should be counted
+        *  @return the total number of editable units that this time consists of at the specified timecode rate, rounded up
+        *  to the nearest editable unit. For example, as_editable_units_ceil(24) returns the total time in frames at 24fps.
+        */
+       int64_t as_editable_units_ceil (int tcr_) const;
+
+       /** @param tcr_ New timecode rate
+        *  @return A new Time which is this time at the spcified new timecode rate
+        */
        Time rebase (int tcr_) const;
 
+       Time& operator+= (Time const & o) {
+               *this = *this + o;
+               return *this;
+       }
+
+       Time& operator-= (Time const & o) {
+               *this = *this - o;
+               return *this;
+       }
+
 private:
        void set (double seconds, int tcr);
 };
 
-extern bool operator== (Time const & a, Time const & b);
-extern bool operator!= (Time const & a, Time const & b);
-extern bool operator<= (Time const & a, Time const & b);
-extern bool operator< (Time const & a, Time const & b);
-extern bool operator> (Time const & a, Time const & b);
-extern bool operator>= (Time const & a, Time const & b);
-extern std::ostream & operator<< (std::ostream & s, Time const & t);
-extern Time operator+ (Time a, Time b);
-extern Time operator- (Time a, Time b);
-extern float operator/ (Time a, Time const & b);
 
 }
 
+
 #endif