QVector: add const first/last getters

Convenience to avoid annoying detaching (instead of using at()),
especially on temporary vectors (returned by functions or so).

[ChangeLog][QtCore][QVector] Added the convenience constFirst
and constLast functions.

Change-Id: If61b1f0096f6a7a1c9074340e237cc2376ce3d18
Task-number: QTBUG-46026
Reviewed-by: Olivier Goffart (Woboq GmbH) <ogoffart@woboq.com>

3 files changed, 163 insertions, 2 deletions

diff --git a/src/corelib/tools/qvector.cpp b/src/corelib/tools/qvector.cpp
index 4f46764697..b57954dc03 100644
--- a/src/corelib/tools/qvector.cpp
+++ b/src/corelib/tools/qvector.cpp
@@ -951,7 +951,7 @@
     Returns a reference to the first item in the vector. This
     function assumes that the vector isn't empty.
 
-    \sa last(), isEmpty()
+    \sa last(), isEmpty(), constFirst()
 */
 
 /*! \fn const T& QVector::first() const
@@ -959,12 +959,21 @@
     \overload
 */
 
+/*! \fn const T& QVector::constFirst() const
+    \since 5.6
+
+    Returns a const reference to the first item in the vector. This
+    function assumes that the vector isn't empty.
+
+    \sa constLast(), isEmpty(), first()
+*/
+
 /*! \fn T& QVector::last()
 
     Returns a reference to the last item in the vector. This function
     assumes that the vector isn't empty.
 
-    \sa first(), isEmpty()
+    \sa first(), isEmpty(), constLast()
 */
 
 /*! \fn const T& QVector::last() const
@@ -972,6 +981,15 @@
     \overload
 */
 
+/*! \fn const T& QVector::constLast() const
+    \since 5.6
+
+    Returns a const reference to the last item in the vector. This function
+    assumes that the vector isn't empty.
+
+    \sa constFirst(), isEmpty(), last()
+*/
+
 /*! \fn T QVector::value(int i) const
 
     Returns the value at index position \a i in the vector.
diff --git a/src/corelib/tools/qvector.h b/src/corelib/tools/qvector.h
index 2eb2dc4550..2adf2d4522 100644
--- a/src/corelib/tools/qvector.h
+++ b/src/corelib/tools/qvector.h
@@ -212,8 +212,10 @@ public:
     inline int count() const { return d->size; }
     inline T& first() { Q_ASSERT(!isEmpty()); return *begin(); }
     inline const T &first() const { Q_ASSERT(!isEmpty()); return *begin(); }
+    inline const T &constFirst() const { Q_ASSERT(!isEmpty()); return *begin(); }
     inline T& last() { Q_ASSERT(!isEmpty()); return *(end()-1); }
     inline const T &last() const { Q_ASSERT(!isEmpty()); return *(end()-1); }
+    inline const T &constLast() const { Q_ASSERT(!isEmpty()); return *(end()-1); }
     inline bool startsWith(const T &t) const { return !isEmpty() && first() == t; }
     inline bool endsWith(const T &t) const { return !isEmpty() && last() == t; }
     QVector<T> mid(int pos, int len = -1) const;
diff --git a/tests/auto/corelib/tools/qvector/tst_qvector.cpp b/tests/auto/corelib/tools/qvector/tst_qvector.cpp
index 3f95fa18f6..f9f9ac472a 100644
--- a/tests/auto/corelib/tools/qvector/tst_qvector.cpp
+++ b/tests/auto/corelib/tools/qvector/tst_qvector.cpp
@@ -198,6 +198,8 @@ private slots:
     void clearMovable() const;
     void clearCustom() const;
     void constData() const;
+    void constFirst() const;
+    void constLast() const;
     void contains() const;
     void countInt() const;
     void countMovable() const;
@@ -1222,16 +1224,86 @@ void tst_QVector::first() const
 
     // test it starts ok
     QCOMPARE(myvec.first(), 69);
+    QCOMPARE(myvec.constFirst(), 69);
 
     // test removal changes
     myvec.remove(0);
     QCOMPARE(myvec.first(), 42);
+    QCOMPARE(myvec.constFirst(), 42);
 
     // test prepend changes
     myvec.prepend(23);
     QCOMPARE(myvec.first(), 23);
+    QCOMPARE(myvec.constFirst(), 23);
 }
 
+void tst_QVector::constFirst() const
+{
+    QVector<int> myvec;
+    myvec << 69 << 42 << 3;
+
+    // test it starts ok
+    QCOMPARE(myvec.constFirst(), 69);
+    QVERIFY(myvec.isDetached());
+
+    QVector<int> myvecCopy = myvec;
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+
+    QCOMPARE(myvec.constFirst(), 69);
+    QCOMPARE(myvecCopy.constFirst(), 69);
+
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+
+    // test removal changes
+    myvec.remove(0);
+    QVERIFY(myvec.isDetached());
+    QVERIFY(!myvec.isSharedWith(myvecCopy));
+    QCOMPARE(myvec.constFirst(), 42);
+    QCOMPARE(myvecCopy.constFirst(), 69);
+
+    myvecCopy = myvec;
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+
+    QCOMPARE(myvec.constFirst(), 42);
+    QCOMPARE(myvecCopy.constFirst(), 42);
+
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+
+    // test prepend changes
+    myvec.prepend(23);
+    QVERIFY(myvec.isDetached());
+    QVERIFY(!myvec.isSharedWith(myvecCopy));
+    QCOMPARE(myvec.constFirst(), 23);
+    QCOMPARE(myvecCopy.constFirst(), 42);
+
+    myvecCopy = myvec;
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+
+    QCOMPARE(myvec.constFirst(), 23);
+    QCOMPARE(myvecCopy.constFirst(), 23);
+
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+}
+
+
 template<typename T>
 void tst_QVector::fromList() const
 {
@@ -1409,14 +1481,83 @@ void tst_QVector::last() const
 
     // test starts ok
     QCOMPARE(myvec.last(), QLatin1String("C"));
+    QCOMPARE(myvec.constLast(), QLatin1String("C"));
 
     // test it changes ok
     myvec.append(QLatin1String("X"));
     QCOMPARE(myvec.last(), QLatin1String("X"));
+    QCOMPARE(myvec.constLast(), QLatin1String("X"));
 
     // and remove again
     myvec.remove(3);
     QCOMPARE(myvec.last(), QLatin1String("C"));
+    QCOMPARE(myvec.constLast(), QLatin1String("C"));
+}
+
+void tst_QVector::constLast() const
+{
+    QVector<int> myvec;
+    myvec << 69 << 42 << 3;
+
+    // test it starts ok
+    QCOMPARE(myvec.constLast(), 3);
+    QVERIFY(myvec.isDetached());
+
+    QVector<int> myvecCopy = myvec;
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+
+    QCOMPARE(myvec.constLast(), 3);
+    QCOMPARE(myvecCopy.constLast(), 3);
+
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+
+    // test removal changes
+    myvec.removeLast();
+    QVERIFY(myvec.isDetached());
+    QVERIFY(!myvec.isSharedWith(myvecCopy));
+    QCOMPARE(myvec.constLast(), 42);
+    QCOMPARE(myvecCopy.constLast(), 3);
+
+    myvecCopy = myvec;
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+
+    QCOMPARE(myvec.constLast(), 42);
+    QCOMPARE(myvecCopy.constLast(), 42);
+
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+
+    // test prepend changes
+    myvec.append(23);
+    QVERIFY(myvec.isDetached());
+    QVERIFY(!myvec.isSharedWith(myvecCopy));
+    QCOMPARE(myvec.constLast(), 23);
+    QCOMPARE(myvecCopy.constLast(), 42);
+
+    myvecCopy = myvec;
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
+
+    QCOMPARE(myvec.constLast(), 23);
+    QCOMPARE(myvecCopy.constLast(), 23);
+
+    QVERIFY(!myvec.isDetached());
+    QVERIFY(!myvecCopy.isDetached());
+    QVERIFY(myvec.isSharedWith(myvecCopy));
+    QVERIFY(myvecCopy.isSharedWith(myvec));
 }
 
 void tst_QVector::lastIndexOf() const