Add convenience functions (#1825)

* Add convenience functions

Signed-off-by: Darby Johnston <darbyjohnston@yahoo.com>

* Check for negative duration

Signed-off-by: Darby Johnston <darbyjohnston@yahoo.com>

* Add comments about the time range duration

Signed-off-by: Darby Johnston <darbyjohnston@yahoo.com>

---------

Signed-off-by: Darby Johnston <darbyjohnston@yahoo.com>

Author: darbyjohnston

src/opentime/rationalTime.h

@@ -54,6 +54,15 @@ class RationalTime
         return (std::isnan(_rate) || std::isnan(_value)) ? true : (_rate <= 0);
     }
 
+    /// @brief Returns true if the time is valid.
+    ///
+    /// The time is considered valid if the value and rate are not NaN values,
+    /// and the rate is greater than zero.
+    bool is_valid_time() const noexcept
+    {
+        return !std::isnan(_rate) && !std::isnan(_value) && (_rate > 0);
+    }
+
     /// @brief Returns the time value.
     constexpr double value() const noexcept { return _value; }
 

src/opentime/timeRange.h

@@ -30,7 +30,7 @@ constexpr double DEFAULT_EPSILON_s = 1.0 / (2 * 192000.0);
 class TimeRange
 {
 public:
-    explicit constexpr TimeRange() noexcept
+    constexpr TimeRange() noexcept
         : _start_time{}
         , _duration{}
     {}
@@ -40,13 +40,40 @@ class TimeRange
         , _duration{ RationalTime{ 0, start_time.rate() } }
     {}
 
-    explicit constexpr TimeRange(
+    constexpr TimeRange(
         RationalTime start_time,
         RationalTime duration) noexcept
         : _start_time{ start_time }
         , _duration{ duration }
     {}
 
+    constexpr TimeRange(
+        double start_time,
+        double duration,
+        double rate) noexcept
+        : _start_time{ start_time, rate }
+        , _duration{ duration, rate }
+    {}
+
+    /// @brief Returns true if the time range is invalid.
+    ///
+    /// The time range is considered invalid if either the start time or
+    /// duration is invalid, or if the duration is less than zero.
+    bool is_invalid_range() const noexcept
+    {
+        return _start_time.is_invalid_time() || _duration.is_invalid_time() || _duration.value() < 0.0;
+    }
+
+    /// @brief Returns true if the time range is valid.
+    ///
+    /// The time range is considered valid if both the start time and
+    /// duration are valid, and the duration is greater than or equal to
+    /// zero.
+    bool is_valid_range() const noexcept
+    {
+        return _start_time.is_valid_time() && _duration.is_valid_time() && _duration.value() >= 0.0;
+    }
+
     constexpr RationalTime start_time() const noexcept { return _start_time; }
 
     constexpr RationalTime duration() const noexcept { return _duration; }

src/py-opentimelineio/opentime-bindings/opentime_rationalTime.cpp

@@ -68,6 +68,10 @@ It can be rescaled into another :class:`~RationalTime`'s rate.
         .def("is_invalid_time", &RationalTime::is_invalid_time, R"docstring(
 Returns true if the time is invalid. The time is considered invalid if the value or the rate are a NaN value
 or if the rate is less than or equal to zero.
+)docstring")
+        .def("is_valid_time", &RationalTime::is_valid_time, R"docstring(
+Returns true if the time is valid. The time is considered valid if the value and rate are not NaN values
+and the rate is greater than zero.
 )docstring")
         .def_property_readonly("value", &RationalTime::value)
         .def_property_readonly("rate", &RationalTime::rate)

src/py-opentimelineio/opentime-bindings/opentime_timeRange.cpp

@@ -42,6 +42,15 @@ meaning that :meth:`end_time_inclusive` (last portion of a sample in the time ra
                         return TimeRange(*start_time, *duration);
                     }
         }), "start_time"_a=nullptr, "duration"_a=nullptr)
+        .def(py::init<double, double, double>(), "start_time"_a, "duration"_a, "rate"_a)
+        .def("is_invalid_range", &TimeRange::is_invalid_range, R"docstring(
+Returns true if the time range is invalid. The time range is considered invalid if either the start time or
+duration is invalid, or if the duration is less than zero.
+)docstring")
+        .def("is_valid_range", &TimeRange::is_valid_range, R"docstring(
+Returns true if the time range is valid. The time range is considered valid if both the start time and
+duration are valid, and the duration is greater than or equal to zero.
+)docstring")
         .def_property_readonly("start_time", &TimeRange::start_time)
         .def_property_readonly("duration", &TimeRange::duration)
         .def("end_time_inclusive", &TimeRange::end_time_inclusive, R"docstring(

tests/test_opentime.cpp

@@ -4,6 +4,7 @@
 #include "utils.h"
 
 #include <opentime/rationalTime.h>
+#include <opentime/timeRange.h>
 
 namespace otime = opentime::OPENTIME_VERSION;
 
@@ -22,6 +23,15 @@ main(int argc, char** argv)
         assertEqual(t.rate(), 1.0);
     });
 
+    tests.add_test("test_valid", [] {
+        otime::RationalTime t1(0.0, 0.0);
+        assertTrue(t1.is_invalid_time());
+        assertFalse(t1.is_valid_time());
+        otime::RationalTime t2(0.0, 24.0);
+        assertTrue(t2.is_valid_time());
+        assertFalse(t2.is_invalid_time());
+    });
+
     tests.add_test("test_equality", [] {
         otime::RationalTime t1(30.2);
         assertEqual(t1, t1);
@@ -129,6 +139,34 @@ main(int argc, char** argv)
         assertTrue(t.almost_equal(time_obj, 0.001));
     });
 
+    tests.add_test("test_create_range", [] {
+        otime::RationalTime start(0.0, 24.0);
+        otime::RationalTime duration(24.0, 24.0);
+        otime::TimeRange r(start, duration);
+        assertEqual(r.start_time(), start);
+        assertEqual(r.duration(), duration);
+
+        r = otime::TimeRange(0.0, 24.0, 24.0);
+        assertEqual(r.start_time(), start);
+        assertEqual(r.duration(), duration);
+
+        r = otime::TimeRange();
+        assertEqual(r.start_time(), otime::RationalTime());
+        assertEqual(r.duration(), otime::RationalTime());
+    });
+
+    tests.add_test("test_valid_range", [] {
+        otime::TimeRange r1(0.0, 0.0, 0.0);
+        assertTrue(r1.is_invalid_range());
+        assertFalse(r1.is_valid_range());
+        otime::TimeRange r2(0.0, 24.0, 24.0);
+        assertTrue(r2.is_valid_range());
+        assertFalse(r2.is_invalid_range());
+        otime::TimeRange r3(0.0, -24.0, 24.0);
+        assertFalse(r3.is_valid_range());
+        assertTrue(r3.is_invalid_range());
+    });
+
     tests.run(argc, argv);
     return 0;
 }

tests/test_opentime.py

@@ -26,6 +26,14 @@ def test_create(self):
         self.assertEqual(t.value, 0)
         self.assertEqual(t.rate, 1.0)
 
+    def test_valid(self):
+        t1 = otio.opentime.RationalTime(0, 0)
+        self.assertTrue(t1.is_invalid_time())
+        self.assertFalse(t1.is_valid_time())
+        t2 = otio.opentime.RationalTime(24)
+        self.assertTrue(t2.is_valid_time())
+        self.assertFalse(t2.is_invalid_time())
+
     def test_equality(self):
         t1 = otio.opentime.RationalTime(30.2)
         self.assertEqual(t1, t1)
@@ -870,6 +878,21 @@ def test_create(self):
         )
         self.assertEqual(tr2.start_time.rate, tr2.duration.rate)
 
+        tr3 = otio.opentime.TimeRange(0, 48, 24)
+        self.assertEqual(tr3.start_time, otio.opentime.RationalTime(0, 24))
+        self.assertEqual(tr3.duration, otio.opentime.RationalTime(48, 24))
+
+    def test_valid(self):
+        tr = otio.opentime.TimeRange(0, 0, 0)
+        self.assertTrue(tr.is_invalid_range())
+        self.assertFalse(tr.is_valid_range())
+        tr2 = otio.opentime.TimeRange(0, 48, 24)
+        self.assertTrue(tr2.is_valid_range())
+        self.assertFalse(tr2.is_invalid_range())
+        tr3 = otio.opentime.TimeRange(0, -48, 24)
+        self.assertFalse(tr3.is_valid_range())
+        self.assertTrue(tr3.is_invalid_range())
+
     def test_duration_validation(self):
         tr = otio.opentime.TimeRange()
         with self.assertRaises(AttributeError):