Revision control
Copy as Markdown
// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
#include <QtCore/qdebug.h>
#include "qmediatimerange.h"
QT_BEGIN_NAMESPACE
/*!
\class QMediaTimeRange::Interval
\brief The QMediaTimeRange::Interval class represents a time interval with
integer precision.
\inmodule QtMultimedia
\ingroup multimedia
\ingroup multimedia_core
An interval is specified by an inclusive start() and end() time. These
must be set in the constructor, as this is an immutable class. The
specific units of time represented by the class have not been defined - it
is suitable for any times which can be represented by a signed 64 bit
integer.
The isNormal() method determines if a time interval is normal (a normal
time interval has start() <= end()). A normal interval can be received
from an abnormal interval by calling the normalized() method.
The contains() method determines if a specified time lies within the time
interval.
The translated() method returns a time interval which has been translated
forwards or backwards through time by a specified offset.
\sa QMediaTimeRange
*/
/*!
\fn QMediaTimeRange::Interval::Interval(qint64 start, qint64 end)
Constructs an interval with the specified \a start and \a end times.
*/
/*!
\fn QMediaTimeRange::Interval::start() const
Returns the start time of the interval.
\sa end()
*/
/*!
\fn QMediaTimeRange::Interval::end() const
Returns the end time of the interval.
\sa start()
*/
/*!
\fn QMediaTimeRange::Interval::contains(qint64 time) const
Returns true if the time interval contains the specified \a time.
That is, start() <= time <= end().
*/
/*!
\fn QMediaTimeRange::Interval::isNormal() const
Returns true if this time interval is normal.
A normal time interval has start() <= end().
\sa normalized()
*/
/*!
\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.
*/
/*!
\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.
*/
/*!
\fn bool QMediaTimeRange::Interval::operator==(QMediaTimeRange::Interval lhs, QMediaTimeRange::Interval rhs)
Returns true if \a lhs is exactly equal to \a rhs.
*/
/*!
\fn bool QMediaTimeRange::Interval::operator!=(QMediaTimeRange::Interval lhs, QMediaTimeRange::Interval rhs)
Returns true if \a lhs is not exactly equal to \a rhs.
*/
class QMediaTimeRangePrivate : public QSharedData
{
public:
QMediaTimeRangePrivate() = default;
QMediaTimeRangePrivate(const QMediaTimeRange::Interval &interval);
QList<QMediaTimeRange::Interval> intervals;
void addInterval(const QMediaTimeRange::Interval &interval);
void removeInterval(const QMediaTimeRange::Interval &interval);
};
QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QMediaTimeRangePrivate);
QMediaTimeRangePrivate::QMediaTimeRangePrivate(const QMediaTimeRange::Interval &interval)
{
if (interval.isNormal())
intervals << interval;
}
void QMediaTimeRangePrivate::addInterval(const QMediaTimeRange::Interval &interval)
{
// Handle normalized intervals only
if (!interval.isNormal())
return;
// Find a place to insert the interval
int i;
for (i = 0; i < intervals.size(); i++) {
// Insert before this element
if(interval.s < intervals[i].s) {
intervals.insert(i, interval);
break;
}
}
// Interval needs to be added to the end of the list
if (i == intervals.size())
intervals.append(interval);
// Do we need to correct the element before us?
if (i > 0 && intervals[i - 1].e >= interval.s - 1)
i--;
// Merge trailing ranges
while (i < intervals.size() - 1
&& intervals[i].e >= intervals[i + 1].s - 1) {
intervals[i].e = qMax(intervals[i].e, intervals[i + 1].e);
intervals.removeAt(i + 1);
}
}
void QMediaTimeRangePrivate::removeInterval(const QMediaTimeRange::Interval &interval)
{
// Handle normalized intervals only
if (!interval.isNormal())
return;
for (int i = 0; i < intervals.size(); i++) {
const QMediaTimeRange::Interval r = intervals.at(i);
if (r.e < interval.s) {
// Before the removal interval
continue;
} else if (interval.e < r.s) {
// After the removal interval - stop here
break;
} 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(QMediaTimeRange::Interval(interval.e + 1, r.e));
break;
} else if (r.s < interval.s) {
// Trimming Tail Case
intervals[i].e = interval.s - 1;
} else if (interval.e < r.e) {
// Trimming Head Case - we can stop after this
intervals[i].s = interval.e + 1;
break;
} else {
// Complete coverage case
intervals.removeAt(i);
--i;
}
}
}
/*!
\class QMediaTimeRange
\brief The QMediaTimeRange class represents a set of zero or more disjoint
time intervals.
\ingroup multimedia
\inmodule QtMultimedia
\reentrant
The earliestTime(), latestTime(), intervals() and isEmpty()
methods are used to get information about the current time range.
The addInterval(), removeInterval() and clear() methods are used to modify
the current time range.
When adding or removing intervals from the time range, existing intervals
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{QMediaTimeRange::Interval::isNormal()}{normal}.
\sa QMediaTimeRange::Interval
*/
/*!
Constructs an empty time range.
*/
QMediaTimeRange::QMediaTimeRange()
: d(new QMediaTimeRangePrivate)
{
}
/*!
Constructs a time range that contains an initial interval from
\a start to \a end inclusive.
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)
: QMediaTimeRange(Interval(start, end))
{
}
/*!
Constructs a time range that contains an initial interval, \a interval.
If \a interval is not \l{QMediaTimeRange::Interval::isNormal()}{normal},
the resulting time range will be empty.
\sa addInterval()
*/
QMediaTimeRange::QMediaTimeRange(const QMediaTimeRange::Interval &interval)
: d(new QMediaTimeRangePrivate(interval))
{
}
/*!
Constructs a time range by copying another time \a range.
*/
QMediaTimeRange::QMediaTimeRange(const QMediaTimeRange &range) noexcept = default;
/*! \fn QMediaTimeRange::QMediaTimeRange(QMediaTimeRange &&other)
Constructs a time range by moving from \a other.
*/
/*!
\fn void QMediaTimeRange::swap(QMediaTimeRange &other) noexcept
Swaps the current instance with the \a other.
*/
/*!
\fn QMediaTimeRange::~QMediaTimeRange()
Destructor.
*/
QMediaTimeRange::~QMediaTimeRange() = default;
/*!
Takes a copy of the \a other time range and returns itself.
*/
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 QMediaTimeRange::Interval &interval)
{
d = new QMediaTimeRangePrivate(interval);
return *this;
}
/*!
Returns the earliest time within the time range.
For empty time ranges, this value is equal to zero.
\sa latestTime()
*/
qint64 QMediaTimeRange::earliestTime() const
{
if (!d->intervals.isEmpty())
return d->intervals[0].start();
return 0;
}
/*!
Returns the latest time within the time range.
For empty time ranges, this value is equal to zero.
\sa earliestTime()
*/
qint64 QMediaTimeRange::latestTime() const
{
if (!d->intervals.isEmpty())
return d->intervals[d->intervals.size() - 1].end();
return 0;
}
/*!
\overload
Adds the interval specified by \a start and \a end
to the time range.
\sa addInterval()
*/
void QMediaTimeRange::addInterval(qint64 start, qint64 end)
{
detach();
d->addInterval(Interval(start, end));
}
/*!
Adds the specified \a interval to the time range.
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
intervals within the time range, these intervals will be merged.
This operation takes linear time.
\sa removeInterval()
*/
void QMediaTimeRange::addInterval(const QMediaTimeRange::Interval &interval)
{
detach();
d->addInterval(interval);
}
/*!
Adds each of the intervals in \a range to this time range.
Equivalent to calling addInterval() for each interval in \a range.
*/
void QMediaTimeRange::addTimeRange(const QMediaTimeRange &range)
{
detach();
const auto intervals = range.intervals();
for (const Interval &i : intervals) {
d->addInterval(i);
}
}
/*!
\overload
Removes the interval specified by \a start and \a end
from the time range.
\sa removeInterval()
*/
void QMediaTimeRange::removeInterval(qint64 start, qint64 end)
{
detach();
d->removeInterval(Interval(start, end));
}
/*!
\fn QMediaTimeRange::removeInterval(const QMediaTimeRange::Interval &interval)
Removes the specified \a interval from the time range.
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
such that no intervals within the time range include any part of the
target interval.
This operation takes linear time.
\sa addInterval()
*/
void QMediaTimeRange::removeInterval(const QMediaTimeRange::Interval &interval)
{
detach();
d->removeInterval(interval);
}
/*!
Removes each of the intervals in \a range from this time range.
Equivalent to calling removeInterval() for each interval in \a range.
*/
void QMediaTimeRange::removeTimeRange(const QMediaTimeRange &range)
{
detach();
const auto intervals = range.intervals();
for (const Interval &i : intervals) {
d->removeInterval(i);
}
}
/*!
Adds each interval in \a other to the time range and returns the result.
*/
QMediaTimeRange& QMediaTimeRange::operator+=(const QMediaTimeRange &other)
{
addTimeRange(other);
return *this;
}
/*!
Adds the specified \a interval to the time range and returns the result.
*/
QMediaTimeRange& QMediaTimeRange::operator+=(const QMediaTimeRange::Interval &interval)
{
addInterval(interval);
return *this;
}
/*!
Removes each interval in \a other from the time range and returns the result.
*/
QMediaTimeRange& QMediaTimeRange::operator-=(const QMediaTimeRange &other)
{
removeTimeRange(other);
return *this;
}
/*!
Removes the specified \a interval from the time range and returns the result.
*/
QMediaTimeRange& QMediaTimeRange::operator-=(const QMediaTimeRange::Interval &interval)
{
removeInterval(interval);
return *this;
}
/*!
\fn QMediaTimeRange::clear()
Removes all intervals from the time range.
\sa removeInterval()
*/
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<QMediaTimeRange::Interval> QMediaTimeRange::intervals() const
{
return d->intervals;
}
/*!
\fn QMediaTimeRange::isEmpty() const
Returns true if there are no intervals within the time range.
\sa intervals()
*/
bool QMediaTimeRange::isEmpty() const
{
return d->intervals.isEmpty();
}
/*!
\fn QMediaTimeRange::isContinuous() const
Returns true if the time range consists of a continuous interval.
That is, there is one or fewer disjoint intervals within the time range.
*/
bool QMediaTimeRange::isContinuous() const
{
return (d->intervals.size() <= 1);
}
/*!
\fn QMediaTimeRange::contains(qint64 time) const
Returns true if the specified \a time lies within the time range.
*/
bool QMediaTimeRange::contains(qint64 time) const
{
for (int i = 0; i < d->intervals.size(); i++) {
if (d->intervals[i].contains(time))
return true;
if (time < d->intervals[i].start())
break;
}
return false;
}
/*!
\fn bool QMediaTimeRange::operator==(const QMediaTimeRange &lhs, const QMediaTimeRange &rhs)
Returns true if all intervals in \a lhs are present in \a rhs.
*/
/*!
\fn bool QMediaTimeRange::operator!=(const QMediaTimeRange &lhs, const QMediaTimeRange &rhs)
Returns true if one or more intervals in \a lhs are not present in \a rhs.
*/
/*!
\fn QMediaTimeRange operator+(const QMediaTimeRange &r1, const QMediaTimeRange &r2)
\relates QMediaTimeRange
Returns a time range containing the union between \a r1 and \a r2.
*/
/*!
\fn QMediaTimeRange operator-(const QMediaTimeRange &r1, const QMediaTimeRange &r2)
\relates QMediaTimeRange
Returns a time range containing \a r2 subtracted from \a r1.
*/
#ifndef QT_NO_DEBUG_STREAM
QDebug operator<<(QDebug dbg, const QMediaTimeRange::Interval &interval)
{
QDebugStateSaver saver(dbg);
dbg.nospace();
dbg << "QMediaTimeRange::Interval( " << interval.start() << ", " << interval.end() << " )";
return dbg;
}
QDebug operator<<(QDebug dbg, const QMediaTimeRange &range)
{
QDebugStateSaver saver(dbg);
dbg.nospace();
dbg << "QMediaTimeRange( ";
const auto intervals = range.intervals();
for (const auto &interval : intervals)
dbg << '(' << interval.start() << ", " << interval.end() << ") ";
dbg.space();
dbg << ')';
return dbg;
}
#endif
QT_END_NAMESPACE