Introduce QAbstractItemModel::checkIndex()

When implementing a custom model there's the habit, in each and every
function that takes a QModelIndex, to carefully checking the index
passed by the caller. This index is checked for "legality" (*): does the
index belong to this model, is the index pointing to an existing row and
column, and so on.  These checks are hand-rolled and, as such, slightly
different and possibly incomplete (i.e. wrong) every time.

What's worse, these checks are implemented via "ordinary" code (if
statements). However, passing an illegal index to a QAIM function is a
precondition violation, and as such does not (and must not) be
checked in ordinary conditions, as it triggers undefined behavior. On
the other hand, while debugging a custom model or a custom hierarchy
of (proxy) models, having such checks in place can be a significant
aid.

Enter checkIndex(): a debugging helper for QAbstractItemModel and its
subclasses. checkIndex() centralizes the checks for legality of a
given index. User code is free to assert on it, or have some other
fallback mechanism in case a check fails.

(*) Using "legality" here instead of "validity" in order to avoid
confusion between QModelIndex::isValid() and what checkIndex() really
does.

[ChangeLog][QtCore][QAbstractItemModel] Added
QAbstractItemModel::checkIndex(), a debugging function for
QAbstractItemModel subclasses.

Change-Id: I1eea0586b1ac3ededdbfbf46759145022dc5ad86
Reviewed-by: Thorbjørn Lund Martsum <tmartsum@gmail.com>
Reviewed-by: David Faure <david.faure@kdab.com>

1 files changed, 13 insertions, 0 deletions

diff --git a/src/corelib/itemmodels/qabstractitemmodel.h b/src/corelib/itemmodels/qabstractitemmodel.h
index cd294ef8fa..621f284c34 100644
--- a/src/corelib/itemmodels/qabstractitemmodel.h
+++ b/src/corelib/itemmodels/qabstractitemmodel.h
@@ -250,6 +250,17 @@ public:
     };
     Q_ENUM(LayoutChangeHint)
 
+    enum class CheckIndexOption {
+        NoOption         = 0x0000,
+        IndexIsValid     = 0x0001,
+        DoNotUseParent   = 0x0002,
+        ParentIsInvalid  = 0x0004,
+    };
+    Q_ENUM(CheckIndexOption)
+    Q_DECLARE_FLAGS(CheckIndexOptions, CheckIndexOption)
+
+    Q_REQUIRED_RESULT bool checkIndex(const QModelIndex &index, CheckIndexOptions options = CheckIndexOption::NoOption) const;
+
 Q_SIGNALS:
     void dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QVector<int> &roles = QVector<int>());
     void headerDataChanged(Qt::Orientation orientation, int first, int last);
@@ -343,6 +354,8 @@ private:
     Q_DISABLE_COPY(QAbstractItemModel)
 };
 
+Q_DECLARE_OPERATORS_FOR_FLAGS(QAbstractItemModel::CheckIndexOptions)
+
 inline bool QAbstractItemModel::insertRow(int arow, const QModelIndex &aparent)
 { return insertRows(arow, 1, aparent); }
 inline bool QAbstractItemModel::insertColumn(int acolumn, const QModelIndex &aparent)