Add front()/back() to QString, QStringRef, QByteArray and QLatin1String

These STL-compatibility functions are present on our generic
containers, but not on the string classes.

[ChangeLog][QtCore][QString/QStringRef/QByteArray/QLatin1String] Added
front() and back() for STL compatibility.

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

5 files changed, 214 insertions, 0 deletions

diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp
index 329cc358d4..6be28fea5f 100644
--- a/src/corelib/tools/qbytearray.cpp
+++ b/src/corelib/tools/qbytearray.cpp
@@ -1446,6 +1446,66 @@ QByteArray &QByteArray::operator=(const char *str)
     \overload
 */
 
+/*!
+    \fn char QByteArray::front() const
+    \since 5.10
+
+    Returns the first character in the byte array.
+    Same as \c{at(0)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty byte array constitutes
+    undefined behavior.
+
+    \sa back(), at(), operator[]()
+*/
+
+/*!
+    \fn char QByteArray::back() const
+    \since 5.10
+
+    Returns the last character in the byte array.
+    Same as \c{at(size() - 1)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty byte array constitutes
+    undefined behavior.
+
+    \sa front(), at(), operator[]()
+*/
+
+/*!
+    \fn QByteRef QByteArray::front()
+    \since 5.10
+
+    Returns a reference to the first character in the byte array.
+    Same as \c{operator[](0)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty byte array constitutes
+    undefined behavior.
+
+    \sa back(), at(), operator[]()
+*/
+
+/*!
+    \fn QByteRef QByteArray::back()
+    \since 5.10
+
+    Returns a reference to the last character in the byte array.
+    Same as \c{operator[](size() - 1)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty byte array constitutes
+    undefined behavior.
+
+    \sa front(), at(), operator[]()
+*/
+
 /*! \fn bool QByteArray::contains(const QByteArray &ba) const
 
     Returns \c true if the byte array contains an occurrence of the byte
diff --git a/src/corelib/tools/qbytearray.h b/src/corelib/tools/qbytearray.h
index 06a50e5990..c6b7fe4053 100644
--- a/src/corelib/tools/qbytearray.h
+++ b/src/corelib/tools/qbytearray.h
@@ -212,6 +212,10 @@ public:
     char operator[](uint i) const;
     QByteRef operator[](int i);
     QByteRef operator[](uint i);
+    char front() const Q_REQUIRED_RESULT { return at(0); }
+    QByteRef front() Q_REQUIRED_RESULT;
+    char back() const Q_REQUIRED_RESULT { return at(size() - 1); }
+    QByteRef back() Q_REQUIRED_RESULT;
 
     int indexOf(char c, int from = 0) const;
     int indexOf(const char *c, int from = 0) const;
@@ -549,6 +553,8 @@ inline QByteRef QByteArray::operator[](int i)
 { Q_ASSERT(i >= 0); return QByteRef(*this, i); }
 inline QByteRef QByteArray::operator[](uint i)
 { return QByteRef(*this, i); }
+inline QByteRef QByteArray::front() { return operator[](0); }
+inline QByteRef QByteArray::back() { return operator[](size() - 1); }
 inline QByteArray::iterator QByteArray::begin()
 { detach(); return d->data(); }
 inline QByteArray::const_iterator QByteArray::begin() const
diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp
index 4f975724d8..4a92a7f424 100644
--- a/src/corelib/tools/qstring.cpp
+++ b/src/corelib/tools/qstring.cpp
@@ -5246,6 +5246,66 @@ modifiable reference.
 */
 
 /*!
+    \fn QChar QString::front() const
+    \since 5.10
+
+    Returns the first character in the string.
+    Same as \c{at(0)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty string constitutes
+    undefined behavior.
+
+    \sa back(), at(), operator[]()
+*/
+
+/*!
+    \fn QChar QString::back() const
+    \since 5.10
+
+    Returns the last character in the string.
+    Same as \c{at(size() - 1)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty string constitutes
+    undefined behavior.
+
+    \sa front(), at(), operator[]()
+*/
+
+/*!
+    \fn QCharRef QString::front()
+    \since 5.10
+
+    Returns a reference to the first character in the string.
+    Same as \c{operator[](0)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty string constitutes
+    undefined behavior.
+
+    \sa back(), at(), operator[]()
+*/
+
+/*!
+    \fn QCharRef QString::back()
+    \since 5.10
+
+    Returns a reference to the last character in the string.
+    Same as \c{operator[](size() - 1)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty string constitutes
+    undefined behavior.
+
+    \sa front(), at(), operator[]()
+*/
+
+/*!
     \fn void QString::truncate(int position)
 
     Truncates the string at the given \a position index.
@@ -8751,6 +8811,36 @@ QString &QString::setRawData(const QChar *unicode, int size)
 */
 
 /*!
+    \fn QLatin1Char QLatin1String::front() const
+    \since 5.10
+
+    Returns the first character in the string.
+    Same as \c{at(0)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty string constitutes
+    undefined behavior.
+
+    \sa back(), at(), operator[]()
+*/
+
+/*!
+    \fn QLatin1Char QLatin1String::back() const
+    \since 5.10
+
+    Returns the last character in the string.
+    Same as \c{at(size() - 1)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty string constitutes
+    undefined behavior.
+
+    \sa front(), at(), operator[]()
+*/
+
+/*!
     \fn QLatin1String::const_iterator QLatin1String::begin() const
     \since 5.10
 
@@ -9693,6 +9783,36 @@ bool operator<(const QStringRef &s1,const QStringRef &s2) Q_DECL_NOTHROW
 */
 
 /*!
+    \fn QChar QStringRef::front() const
+    \since 5.10
+
+    Returns the first character in the string.
+    Same as \c{at(0)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty string constitutes
+    undefined behavior.
+
+    \sa back(), at(), operator[]()
+*/
+
+/*!
+    \fn QChar QStringRef::back() const
+    \since 5.10
+
+    Returns the last character in the string.
+    Same as \c{at(size() - 1)}.
+
+    This function is provided for STL compatibility.
+
+    \warning Calling this function on an empty string constitutes
+    undefined behavior.
+
+    \sa front(), at(), operator[]()
+*/
+
+/*!
     \fn void QStringRef::clear()
 
     Clears the contents of the string reference by making it null and empty.
diff --git a/src/corelib/tools/qstring.h b/src/corelib/tools/qstring.h
index 431e2672ff..c00208869c 100644
--- a/src/corelib/tools/qstring.h
+++ b/src/corelib/tools/qstring.h
@@ -120,6 +120,9 @@ public:
     { return Q_ASSERT(i >= 0), Q_ASSERT(i < size()), QLatin1Char(m_data[i]); }
     Q_DECL_CONSTEXPR QLatin1Char operator[](int i) const { return at(i); }
 
+    Q_DECL_CONSTEXPR QLatin1Char front() const Q_REQUIRED_RESULT { return at(0); }
+    Q_DECL_CONSTEXPR QLatin1Char back() const Q_REQUIRED_RESULT { return at(size() - 1); }
+
     using value_type = const char;
     using reference = value_type&;
     using const_reference = reference;
@@ -302,6 +305,11 @@ public:
     const QChar operator[](uint i) const;
     QCharRef operator[](uint i);
 
+    inline QChar front() const Q_REQUIRED_RESULT { return at(0); }
+    inline QCharRef front() Q_REQUIRED_RESULT;
+    inline QChar back() const Q_REQUIRED_RESULT { return at(size() - 1); }
+    inline QCharRef back() Q_REQUIRED_RESULT;
+
     QString arg(qlonglong a, int fieldwidth=0, int base=10,
                 QChar fillChar = QLatin1Char(' ')) const Q_REQUIRED_RESULT;
     QString arg(qulonglong a, int fieldwidth=0, int base=10,
@@ -1160,6 +1168,8 @@ inline QCharRef QString::operator[](int i)
 { Q_ASSERT(i >= 0); return QCharRef(*this, i); }
 inline QCharRef QString::operator[](uint i)
 { return QCharRef(*this, i); }
+inline QCharRef QString::front() { return operator[](0); }
+inline QCharRef QString::back() { return operator[](size() - 1); }
 inline QString::iterator QString::begin()
 { detach(); return reinterpret_cast<QChar*>(d->data()); }
 inline QString::const_iterator QString::begin() const
@@ -1544,6 +1554,8 @@ public:
     inline const QChar at(int i) const
         { Q_ASSERT(uint(i) < uint(size())); return m_string->at(i + m_position); }
     QChar operator[](int i) const { return at(i); }
+    QChar front() const Q_REQUIRED_RESULT { return at(0); }
+    QChar back() const Q_REQUIRED_RESULT { return at(size() - 1); }
 
 #if !defined(QT_NO_CAST_FROM_ASCII) && !defined(QT_RESTRICTED_CAST_FROM_ASCII)
     // ASCII compatibility
diff --git a/tests/auto/corelib/tools/containerapisymmetry/tst_containerapisymmetry.cpp b/tests/auto/corelib/tools/containerapisymmetry/tst_containerapisymmetry.cpp
index d7ec624804..3b8111f1a3 100644
--- a/tests/auto/corelib/tools/containerapisymmetry/tst_containerapisymmetry.cpp
+++ b/tests/auto/corelib/tools/containerapisymmetry/tst_containerapisymmetry.cpp
@@ -28,8 +28,10 @@
 
 #include <QtTest/QtTest>
 
+#include "qbytearray.h"
 #include "qlinkedlist.h"
 #include "qlist.h"
+#include "qstring.h"
 #include "qvarlengtharray.h"
 #include "qvector.h"
 
@@ -49,6 +51,11 @@ private Q_SLOTS:
     void front_back_QList() { front_back_impl<QList<qintptr>>(); }
     void front_back_QLinkedList() { front_back_impl<QLinkedList<int>>(); }
     void front_back_QVarLengthArray() { front_back_impl<QVarLengthArray<int>>(); }
+    void front_back_QString() { front_back_impl<QString>(); }
+    void front_back_QStringRef() { front_back_impl<QStringRef>(); }
+    void front_back_QStringView() { front_back_impl<QStringView>(); }
+    void front_back_QLatin1String() { front_back_impl<QLatin1String>(); }
+    void front_back_QByteArray() { front_back_impl<QByteArray>(); }
 };
 
 template <typename Container>
@@ -61,7 +68,16 @@ Container make(int size)
     return c;
 }
 
+static QString s_string = QStringLiteral("\1\2\3\4\5\6\7");
+
+template <> QStringRef    make(int size) { return s_string.leftRef(size); }
+template <> QStringView   make(int size) { return QStringView(s_string).left(size); }
+template <> QLatin1String make(int size) { return QLatin1String("\1\2\3\4\5\6\7", size); }
+
 template <typename T> T clean(T &&t) { return std::forward<T>(t); }
+inline QChar clean(QCharRef ch) { return ch; }
+inline char clean(QByteRef ch) { return ch; }
+inline char clean(QLatin1Char ch) { return ch.toLatin1(); }
 
 template <typename Container>
 void tst_ContainerApiSymmetry::front_back_impl() const