Clean up QMediaTimeRange API

Make the Interval struct a nested type with an entirely constexpr API.
Make QMediaTimeRange movable, add documentation for respective specials.

Change-Id: I3f1864932671dd59a9d58bdb4c3c90383fc64292
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

1 files changed, 93 insertions, 144 deletions

diff --git a/src/multimedia/qmediatimerange.cpp b/src/multimedia/qmediatimerange.cpp
index 20e937dbb..0b2929c27 100644
--- a/src/multimedia/qmediatimerange.cpp
+++ b/src/multimedia/qmediatimerange.cpp
@@ -44,8 +44,9 @@
 QT_BEGIN_NAMESPACE
 
 /*!
-    \class QMediaTimeInterval
-    \brief The QMediaTimeInterval class represents a time interval with integer precision.
+    \class QMediaTimeRange::Interval
+    \brief The QMediaTimeRange::Interval class represents a time interval with
+    integer precision.
     \inmodule QtMultimedia
 
     \ingroup multimedia
@@ -71,148 +72,96 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn QMediaTimeInterval::QMediaTimeInterval()
-
-    Constructs an empty interval.
-*/
-QMediaTimeInterval::QMediaTimeInterval()
-    : s(0)
-    , e(0)
-{
-
-}
-
-/*!
-    \fn QMediaTimeInterval::QMediaTimeInterval(qint64 start, qint64 end)
+    \fn QMediaTimeRange::Interval::Interval(qint64 start, qint64 end)
 
     Constructs an interval with the specified \a start and \a end times.
 */
-QMediaTimeInterval::QMediaTimeInterval(qint64 start, qint64 end)
-    : s(start)
-    , e(end)
-{
-
-}
 
 /*!
-    \fn QMediaTimeInterval::start() const
+    \fn QMediaTimeRange::Interval::start() const
 
     Returns the start time of the interval.
 
     \sa end()
 */
-qint64 QMediaTimeInterval::start() const
-{
-    return s;
-}
 
 /*!
-    \fn QMediaTimeInterval::end() const
+    \fn QMediaTimeRange::Interval::end() const
 
     Returns the end time of the interval.
 
     \sa start()
 */
-qint64 QMediaTimeInterval::end() const
-{
-    return e;
-}
 
 /*!
-    \fn QMediaTimeInterval::contains(qint64 time) const
+    \fn QMediaTimeRange::Interval::contains(qint64 time) const
 
     Returns true if the time interval contains the specified \a time.
     That is, start() <= time <= end().
 */
-bool QMediaTimeInterval::contains(qint64 time) const
-{
-    return isNormal() ? (s <= time && time <= e)
-        : (e <= time && time <= s);
-}
 
 /*!
-    \fn QMediaTimeInterval::isNormal() const
+    \fn QMediaTimeRange::Interval::isNormal() const
 
     Returns true if this time interval is normal.
     A normal time interval has start() <= end().
 
     \sa normalized()
 */
-bool QMediaTimeInterval::isNormal() const
-{
-    return s <= e;
-}
 
 /*!
-    \fn QMediaTimeInterval::normalized() const
+    \fn QMediaTimeRange::Interval::normalized() const
 
     Returns a normalized version of this interval.
 
     If the start() time of the interval is greater than the end() time,
     then the returned interval has the start and end times swapped.
 */
-QMediaTimeInterval QMediaTimeInterval::normalized() const
-{
-    if(s > e)
-        return QMediaTimeInterval(e, s);
-
-    return *this;
-}
 
 /*!
-    \fn QMediaTimeInterval::translated(qint64 offset) const
+    \fn QMediaTimeRange::Interval::translated(qint64 offset) const
 
     Returns a copy of this time interval, translated by a value of \a offset.
     An interval can be moved forward through time with a positive offset, or backward
     through time with a negative offset.
 */
-QMediaTimeInterval QMediaTimeInterval::translated(qint64 offset) const
-{
-    return QMediaTimeInterval(s + offset, e + offset);
-}
 
 /*!
-    \relates QMediaTimeRange
+    \fn bool QMediaTimeRange::Interval::operator==(QMediaTimeRange::Interval lhs, QMediaTimeRange::Interval rhs)
 
-    Returns true if \a a is exactly equal to \a b.
+    Returns true if \a lhs is exactly equal to \a rhs.
 */
-bool operator==(const QMediaTimeInterval &a, const QMediaTimeInterval &b)
-{
-    return a.start() == b.start() && a.end() == b.end();
-}
 
 /*!
-    \relates QMediaTimeRange
+    \fn bool QMediaTimeRange::Interval::operator!=(QMediaTimeRange::Interval lhs, QMediaTimeRange::Interval rhs)
 
-    Returns true if \a a is not exactly equal to \a b.
+    Returns true if \a lhs is not exactly equal to \a rhs.
 */
-bool operator!=(const QMediaTimeInterval &a, const QMediaTimeInterval &b)
-{
-    return a.start() != b.start() || a.end() != b.end();
-}
 
 class QMediaTimeRangePrivate : public QSharedData
 {
 public:
     QMediaTimeRangePrivate() = default;
-    QMediaTimeRangePrivate(const QMediaTimeInterval &interval);
+    QMediaTimeRangePrivate(const QMediaTimeRange::Interval &interval);
 
-    QList<QMediaTimeInterval> intervals;
+    QList<QMediaTimeRange::Interval> intervals;
 
-    void addInterval(const QMediaTimeInterval &interval);
-    void removeInterval(const QMediaTimeInterval &interval);
+    void addInterval(const QMediaTimeRange::Interval &interval);
+    void removeInterval(const QMediaTimeRange::Interval &interval);
 };
 
-QMediaTimeRangePrivate::QMediaTimeRangePrivate(const QMediaTimeInterval &interval)
+QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QMediaTimeRangePrivate);
+
+QMediaTimeRangePrivate::QMediaTimeRangePrivate(const QMediaTimeRange::Interval &interval)
 {
-    if(interval.isNormal())
+    if (interval.isNormal())
         intervals << interval;
 }
 
-void QMediaTimeRangePrivate::addInterval(const QMediaTimeInterval &interval)
+void QMediaTimeRangePrivate::addInterval(const QMediaTimeRange::Interval &interval)
 {
     // Handle normalized intervals only
-    if(!interval.isNormal())
+    if (!interval.isNormal())
         return;
 
     // Find a place to insert the interval
@@ -230,7 +179,7 @@ void QMediaTimeRangePrivate::addInterval(const QMediaTimeInterval &interval)
         intervals.append(interval);
 
     // Do we need to correct the element before us?
-    if(i > 0 && intervals[i - 1].e >= interval.s - 1)
+    if (i > 0 && intervals[i - 1].e >= interval.s - 1)
         i--;
 
     // Merge trailing ranges
@@ -241,14 +190,14 @@ void QMediaTimeRangePrivate::addInterval(const QMediaTimeInterval &interval)
     }
 }
 
-void QMediaTimeRangePrivate::removeInterval(const QMediaTimeInterval &interval)
+void QMediaTimeRangePrivate::removeInterval(const QMediaTimeRange::Interval &interval)
 {
     // Handle normalized intervals only
-    if(!interval.isNormal())
+    if (!interval.isNormal())
         return;
 
     for (int i = 0; i < intervals.count(); i++) {
-        QMediaTimeInterval r = intervals[i];
+        const QMediaTimeRange::Interval r = intervals.at(i);
 
         if (r.e < interval.s) {
             // Before the removal interval
@@ -259,7 +208,7 @@ void QMediaTimeRangePrivate::removeInterval(const QMediaTimeInterval &interval)
         } else if (r.s < interval.s && interval.e < r.e) {
             // Split case - a single range has a chunk removed
             intervals[i].e = interval.s -1;
-            addInterval(QMediaTimeInterval(interval.e + 1, r.e));
+            addInterval(QMediaTimeRange::Interval(interval.e + 1, r.e));
             break;
         } else if (r.s < interval.s) {
             // Trimming Tail Case
@@ -295,14 +244,12 @@ void QMediaTimeRangePrivate::removeInterval(const QMediaTimeInterval &interval)
     within the range may be expanded, trimmed, deleted, merged or split to ensure
     that all intervals within the time range remain distinct and disjoint. As a
     consequence, all intervals added or removed from a time range must be
-    \l{QMediaTimeInterval::isNormal()}{normal}.
+    \l{QMediaTimeRange::Interval::isNormal()}{normal}.
 
-    \sa QMediaTimeInterval
+    \sa QMediaTimeRange::Interval
 */
 
 /*!
-    \fn QMediaTimeRange::QMediaTimeRange()
-
     Constructs an empty time range.
 */
 QMediaTimeRange::QMediaTimeRange()
@@ -312,44 +259,41 @@ QMediaTimeRange::QMediaTimeRange()
 }
 
 /*!
-    \fn QMediaTimeRange::QMediaTimeRange(qint64 start, qint64 end)
-
     Constructs a time range that contains an initial interval from
     \a start to \a end inclusive.
 
-    If the interval is not \l{QMediaTimeInterval::isNormal()}{normal},
+    If the interval is not \l{QMediaTimeRange::Interval::isNormal()}{normal},
     the resulting time range will be empty.
 
     \sa addInterval()
 */
 QMediaTimeRange::QMediaTimeRange(qint64 start, qint64 end)
-    : d(new QMediaTimeRangePrivate(QMediaTimeInterval(start, end)))
+    : QMediaTimeRange(Interval(start, end))
 {
-
 }
 
 /*!
-    \fn QMediaTimeRange::QMediaTimeRange(const QMediaTimeInterval &interval)
-
     Constructs a time range that contains an initial interval, \a interval.
 
-    If \a interval is not \l{QMediaTimeInterval::isNormal()}{normal},
+    If \a interval is not \l{QMediaTimeRange::Interval::isNormal()}{normal},
     the resulting time range will be empty.
 
     \sa addInterval()
 */
-QMediaTimeRange::QMediaTimeRange(const QMediaTimeInterval &interval)
+QMediaTimeRange::QMediaTimeRange(const QMediaTimeRange::Interval &interval)
     : d(new QMediaTimeRangePrivate(interval))
 {
-
 }
 
 /*!
-    \fn QMediaTimeRange::QMediaTimeRange(const QMediaTimeRange &range)
-
     Constructs a time range by copying another time \a range.
 */
-QMediaTimeRange::QMediaTimeRange(const QMediaTimeRange &range) = default;
+QMediaTimeRange::QMediaTimeRange(const QMediaTimeRange &range) noexcept = default;
+
+/*! \fn QMediaTimeRange::QMediaTimeRange(QMediaTimeRange &&other)
+
+    Constructs a time range by moving from \a other.
+*/
 
 /*!
     \fn QMediaTimeRange::~QMediaTimeRange()
@@ -361,20 +305,24 @@ QMediaTimeRange::~QMediaTimeRange() = default;
 /*!
     Takes a copy of the \a other time range and returns itself.
 */
-QMediaTimeRange &QMediaTimeRange::operator=(const QMediaTimeRange &other) = default;
+QMediaTimeRange &QMediaTimeRange::operator=(const QMediaTimeRange &other) noexcept = default;
+
+/*!
+    \fn QMediaTimeRange &QMediaTimeRange::operator=(QMediaTimeRange &&other)
+
+    Moves \a other into this time range.
+*/
 
 /*!
     Sets the time range to a single continuous interval, \a interval.
 */
-QMediaTimeRange &QMediaTimeRange::operator=(const QMediaTimeInterval &interval)
+QMediaTimeRange &QMediaTimeRange::operator=(const QMediaTimeRange::Interval &interval)
 {
     d = new QMediaTimeRangePrivate(interval);
     return *this;
 }
 
 /*!
-    \fn QMediaTimeRange::earliestTime() const
-
     Returns the earliest time within the time range.
 
     For empty time ranges, this value is equal to zero.
@@ -384,14 +332,12 @@ QMediaTimeRange &QMediaTimeRange::operator=(const QMediaTimeInterval &interval)
 qint64 QMediaTimeRange::earliestTime() const
 {
     if (!d->intervals.isEmpty())
-        return d->intervals[0].s;
+        return d->intervals[0].start();
 
     return 0;
 }
 
 /*!
-    \fn QMediaTimeRange::latestTime() const
-
     Returns the latest time within the time range.
 
     For empty time ranges, this value is equal to zero.
@@ -401,13 +347,12 @@ qint64 QMediaTimeRange::earliestTime() const
 qint64 QMediaTimeRange::latestTime() const
 {
     if (!d->intervals.isEmpty())
-        return d->intervals[d->intervals.count() - 1].e;
+        return d->intervals[d->intervals.count() - 1].end();
 
     return 0;
 }
 
 /*!
-    \fn QMediaTimeRange::addInterval(qint64 start, qint64 end)
     \overload
 
     Adds the interval specified by \a start and \a end
@@ -417,15 +362,14 @@ qint64 QMediaTimeRange::latestTime() const
 */
 void QMediaTimeRange::addInterval(qint64 start, qint64 end)
 {
-    d->addInterval(QMediaTimeInterval(start, end));
+    detach();
+    d->addInterval(Interval(start, end));
 }
 
 /*!
-    \fn QMediaTimeRange::addInterval(const QMediaTimeInterval &interval)
-
     Adds the specified \a interval to the time range.
 
-    Adding intervals which are not \l{QMediaTimeInterval::isNormal()}{normal}
+    Adding intervals which are not \l{QMediaTimeRange::Interval::isNormal()}{normal}
     is invalid, and will be ignored.
 
     If the specified interval is adjacent to, or overlaps existing
@@ -435,8 +379,9 @@ void QMediaTimeRange::addInterval(qint64 start, qint64 end)
 
     \sa removeInterval()
 */
-void QMediaTimeRange::addInterval(const QMediaTimeInterval &interval)
+void QMediaTimeRange::addInterval(const QMediaTimeRange::Interval &interval)
 {
+    detach();
     d->addInterval(interval);
 }
 
@@ -447,14 +392,14 @@ void QMediaTimeRange::addInterval(const QMediaTimeInterval &interval)
 */
 void QMediaTimeRange::addTimeRange(const QMediaTimeRange &range)
 {
+    detach();
     const auto intervals = range.intervals();
-    for (const QMediaTimeInterval &i : intervals) {
+    for (const Interval &i : intervals) {
         d->addInterval(i);
     }
 }
 
 /*!
-    \fn QMediaTimeRange::removeInterval(qint64 start, qint64 end)
     \overload
 
     Removes the interval specified by \a start and \a end
@@ -464,15 +409,16 @@ void QMediaTimeRange::addTimeRange(const QMediaTimeRange &range)
 */
 void QMediaTimeRange::removeInterval(qint64 start, qint64 end)
 {
-    d->removeInterval(QMediaTimeInterval(start, end));
+    detach();
+    d->removeInterval(Interval(start, end));
 }
 
 /*!
-    \fn QMediaTimeRange::removeInterval(const QMediaTimeInterval &interval)
+    \fn QMediaTimeRange::removeInterval(const QMediaTimeRange::Interval &interval)
 
     Removes the specified \a interval from the time range.
 
-    Removing intervals which are not \l{QMediaTimeInterval::isNormal()}{normal}
+    Removing intervals which are not \l{QMediaTimeRange::Interval::isNormal()}{normal}
     is invalid, and will be ignored.
 
     Intervals within the time range will be trimmed, split or deleted
@@ -483,8 +429,9 @@ void QMediaTimeRange::removeInterval(qint64 start, qint64 end)
 
     \sa addInterval()
 */
-void QMediaTimeRange::removeInterval(const QMediaTimeInterval &interval)
+void QMediaTimeRange::removeInterval(const QMediaTimeRange::Interval &interval)
 {
+    detach();
     d->removeInterval(interval);
 }
 
@@ -495,8 +442,9 @@ void QMediaTimeRange::removeInterval(const QMediaTimeInterval &interval)
 */
 void QMediaTimeRange::removeTimeRange(const QMediaTimeRange &range)
 {
+    detach();
     const auto intervals = range.intervals();
-    for (const QMediaTimeInterval &i : intervals) {
+    for (const Interval &i : intervals) {
         d->removeInterval(i);
     }
 }
@@ -513,7 +461,7 @@ QMediaTimeRange& QMediaTimeRange::operator+=(const QMediaTimeRange &other)
 /*!
     Adds the specified \a interval to the time range and returns the result.
 */
-QMediaTimeRange& QMediaTimeRange::operator+=(const QMediaTimeInterval &interval)
+QMediaTimeRange& QMediaTimeRange::operator+=(const QMediaTimeRange::Interval &interval)
 {
     addInterval(interval);
     return *this;
@@ -531,7 +479,7 @@ QMediaTimeRange& QMediaTimeRange::operator-=(const QMediaTimeRange &other)
 /*!
     Removes the specified \a interval from the time range and returns the result.
 */
-QMediaTimeRange& QMediaTimeRange::operator-=(const QMediaTimeInterval &interval)
+QMediaTimeRange& QMediaTimeRange::operator-=(const QMediaTimeRange::Interval &interval)
 {
     removeInterval(interval);
     return *this;
@@ -546,15 +494,24 @@ QMediaTimeRange& QMediaTimeRange::operator-=(const QMediaTimeInterval &interval)
 */
 void QMediaTimeRange::clear()
 {
+    detach();
     d->intervals.clear();
 }
 
 /*!
+    \internal
+*/
+void QMediaTimeRange::detach()
+{
+    d.detach();
+}
+
+/*!
     \fn QMediaTimeRange::intervals() const
 
     Returns the list of intervals covered by this time range.
 */
-QList<QMediaTimeInterval> QMediaTimeRange::intervals() const
+QList<QMediaTimeRange::Interval> QMediaTimeRange::intervals() const
 {
     return d->intervals;
 }
@@ -593,7 +550,7 @@ bool QMediaTimeRange::contains(qint64 time) const
         if (d->intervals[i].contains(time))
             return true;
 
-        if (time < d->intervals[i].s)
+        if (time < d->intervals[i].start())
             break;
     }
 
@@ -601,53 +558,46 @@ bool QMediaTimeRange::contains(qint64 time) const
 }
 
 /*!
+    \fn bool QMediaTimeRange::operator==(const QMediaTimeRange &lhs, const QMediaTimeRange &rhs)
     \relates QMediaTimeRange
 
-    Returns true if all intervals in \a a are present in \a b.
+    Returns true if all intervals in \a lhs are present in \a rhs.
 */
-bool operator==(const QMediaTimeRange &a, const QMediaTimeRange &b)
-{
-    return a.intervals() == b.intervals();
-}
 
 /*!
-    \relates QMediaTimeRange
+    \fn bool QMediaTimeRange::operator!=(const QMediaTimeRange &lhs, const QMediaTimeRange &rhs)
 
-    Returns true if one or more intervals in \a a are not present in \a b.
+    Returns true if one or more intervals in \a lhs are not present in \a rhs.
 */
-bool operator!=(const QMediaTimeRange &a, const QMediaTimeRange &b)
-{
-    return !(a == b);
-}
 
 /*!
-    \relates QMediaTimeRange
+    \fn QMediaTimeRange QMediaTimeRange::operator+(const QMediaTimeRange &r1, const QMediaTimeRange &r2)
 
     Returns a time range containing the union between \a r1 and \a r2.
  */
-QMediaTimeRange operator+(const QMediaTimeRange &r1, const QMediaTimeRange &r2)
-{
-    return (QMediaTimeRange(r1) += r2);
-}
 
 /*!
-    \relates QMediaTimeRange
+    \fn QMediaTimeRange QMediaTimeRange::operator-(const QMediaTimeRange &r1, const QMediaTimeRange &r2)
 
     Returns a time range containing \a r2 subtracted from \a r1.
  */
-QMediaTimeRange operator-(const QMediaTimeRange &r1, const QMediaTimeRange &r2)
+
+#ifndef QT_NO_DEBUG_STREAM
+QDebug operator<<(QDebug dbg, const QMediaTimeRange::Interval &interval)
 {
-    return (QMediaTimeRange(r1) -= r2);
+    QDebugStateSaver saver(dbg);
+    dbg.nospace();
+    dbg << "QMediaTimeRange::Interval( " << interval.start() << ", " << interval.end() << " )";
+    return dbg;
 }
 
-#ifndef QT_NO_DEBUG_STREAM
 QDebug operator<<(QDebug dbg, const QMediaTimeRange &range)
 {
     QDebugStateSaver saver(dbg);
     dbg.nospace();
     dbg << "QMediaTimeRange( ";
     const auto intervals = range.intervals();
-    for (const QMediaTimeInterval &interval : intervals)
+    for (const auto &interval : intervals)
         dbg << '(' <<  interval.start() << ", " << interval.end() << ") ";
     dbg.space();
     dbg << ')';
@@ -656,4 +606,3 @@ QDebug operator<<(QDebug dbg, const QMediaTimeRange &range)
 #endif
 
 QT_END_NAMESPACE
-