QByteArray, QString, QStringRef: Add chopped()

We have two functions to get a substring without doing some
calculations involving size():

- mid(p):    mid(p, size() - p)
- right(n) : mid(size() - n, n)

(left does not involve size(), so isn't in that set). What was missing
was a name for

- f(n): mid(0, size() - n)

As an action, it's called chop(), so call the transformation version
chopped().

I made chopped(n), n < 0 or n > size(), undefined, because QString(Ref)
::left() is broken[1], while the QByteArray implementation is not. This
is the only way to get consistent behavior among the three classes.

I's also the correct thing to do.

[1] instead of returning the empty string for negative indexes, it
returns the whole string.

[ChangeLog][QtCore][QString/QStringRef/QByteArray] Added chopped(n), a
const version of chop(n).

Change-Id: I6c2c5b16e0060fa924ced5860f21f2d0f23bd023
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
Reviewed-by: Anton Kudryavtsev <antkudr@mail.ru>

src/corelib/tools/qbytearray.cpp

@@ -2972,7 +2972,7 @@ bool QByteArray::endsWith(char ch) const
     Example:
     \snippet code/src_corelib_tools_qbytearray.cpp 27
 
-    \sa right(), mid(), startsWith(), truncate()
+    \sa startsWith(), right(), mid(), chopped(), chop(), truncate()
 */
 
 QByteArray QByteArray::left(int len)  const
@@ -2994,7 +2994,7 @@ QByteArray QByteArray::left(int len)  const
     Example:
     \snippet code/src_corelib_tools_qbytearray.cpp 28
 
-    \sa endsWith(), left(), mid()
+    \sa endsWith(), left(), mid(), chopped(), chop(), truncate()
 */
 
 QByteArray QByteArray::right(int len) const
@@ -3017,7 +3017,7 @@ QByteArray QByteArray::right(int len) const
     Example:
     \snippet code/src_corelib_tools_qbytearray.cpp 29
 
-    \sa left(), right()
+    \sa left(), right(), chopped(), chop(), truncate()
 */
 
 QByteArray QByteArray::mid(int pos, int len) const
@@ -3040,6 +3040,18 @@ QByteArray QByteArray::mid(int pos, int len) const
     return QByteArray();
 }
 
+/*!
+    \fn QByteArray::chopped(int len) const
+    \since 5.10
+
+    Returns a byte array that contains the leftmost size() - \a len bytes of
+    this byte array.
+
+    \note The behavior is undefined if \a len is negative or greater than size().
+
+    \sa endsWith(), left(), right(), mid(), chop(), truncate().
+*/
+
 /*!
     \fn QByteArray QByteArray::toLower() const
 

src/corelib/tools/qbytearray.h

@@ -234,6 +234,8 @@ public:
     QByteArray left(int len) const Q_REQUIRED_RESULT;
     QByteArray right(int len) const Q_REQUIRED_RESULT;
     QByteArray mid(int index, int len = -1) const Q_REQUIRED_RESULT;
+    QByteArray chopped(int len) const Q_REQUIRED_RESULT
+    { Q_ASSERT(len >= 0); Q_ASSERT(len <= size()); return left(size() - len); }
 
     bool startsWith(const QByteArray &a) const;
     bool startsWith(char c) const;

src/corelib/tools/qstring.cpp

@@ -4455,7 +4455,7 @@ QString QString::section(const QRegularExpression &re, int start, int end, Secti
 
     \snippet qstring/main.cpp 31
 
-    \sa right(), mid(), startsWith()
+    \sa right(), mid(), startsWith(), chopped(), chop(), truncate()
 */
 QString QString::left(int n)  const
 {
@@ -4473,7 +4473,7 @@ QString QString::left(int n)  const
 
     \snippet qstring/main.cpp 48
 
-    \sa left(), mid(), endsWith()
+    \sa left(), mid(), endsWith(), chopped(), chop(), truncate()
 */
 QString QString::right(int n) const
 {
@@ -4496,7 +4496,7 @@ QString QString::right(int n) const
 
     \snippet qstring/main.cpp 34
 
-    \sa left(), right()
+    \sa left(), right(), chopped(), chop(), truncate()
 */
 
 QString QString::mid(int position, int n) const
@@ -4519,6 +4519,18 @@ QString QString::mid(int position, int n) const
     return QString();
 }
 
+/*!
+    \fn QString::chopped(int len) const
+    \since 5.10
+
+    Returns a substring that contains the size() - \a len leftmost characters
+    of this string.
+
+    \note The behavior is undefined if \a len is negative or greater than size().
+
+    \sa endsWith(), left(), right(), mid(), chop(), truncate().
+*/
+
 /*!
     Returns \c true if the string starts with \a s; otherwise returns
     \c false.
@@ -10178,7 +10190,7 @@ QString &QString::append(const QStringRef &str)
     If \a n is greater than or equal to size(), or less than zero,
     a reference to the entire string is returned.
 
-    \sa right(), mid(), startsWith()
+    \sa right(), mid(), startsWith(), chopped(), chop(), truncate()
 */
 QStringRef QStringRef::left(int n) const
 {
@@ -10215,7 +10227,7 @@ QStringRef QString::leftRef(int n)  const
     If \a n is greater than or equal to size(), or less than zero,
     a reference to the entire string is returned.
 
-    \sa left(), mid(), endsWith()
+    \sa left(), mid(), endsWith(), chopped(), chop(), truncate()
 */
 QStringRef QStringRef::right(int n) const
 {
@@ -10257,7 +10269,7 @@ QStringRef QString::rightRef(int n) const
     function returns all characters from the specified \a position
     onwards.
 
-    \sa left(), right()
+    \sa left(), right(), chopped(), chop(), truncate()
 */
 QStringRef QStringRef::mid(int pos, int n) const
 {
@@ -10276,6 +10288,18 @@ QStringRef QStringRef::mid(int pos, int n) const
     return QStringRef();
 }
 
+/*!
+    \fn QStringRef::chopped(int len) const
+    \since 5.10
+
+    Returns a substring reference to the size() - \a len leftmost characters
+    of this string.
+
+    \note The behavior is undefined if \a len is negative or greater than size().
+
+    \sa endsWith(), left(), right(), mid(), chop(), truncate().
+*/
+
 /*!
     \since 4.4
 

src/corelib/tools/qstring.h

@@ -421,6 +421,10 @@ public:
     QString left(int n) const Q_REQUIRED_RESULT;
     QString right(int n) const Q_REQUIRED_RESULT;
     QString mid(int position, int n = -1) const Q_REQUIRED_RESULT;
+    QString chopped(int n) const Q_REQUIRED_RESULT
+    { Q_ASSERT(n >= 0); Q_ASSERT(n <= size()); return left(size() - n); }
+
+
     QStringRef leftRef(int n) const Q_REQUIRED_RESULT;
     QStringRef rightRef(int n) const Q_REQUIRED_RESULT;
     QStringRef midRef(int position, int n = -1) const Q_REQUIRED_RESULT;
@@ -1492,6 +1496,8 @@ public:
     QStringRef left(int n) const Q_REQUIRED_RESULT;
     QStringRef right(int n) const Q_REQUIRED_RESULT;
     QStringRef mid(int pos, int n = -1) const Q_REQUIRED_RESULT;
+    QStringRef chopped(int n) const Q_REQUIRED_RESULT
+    { Q_ASSERT(n >= 0); Q_ASSERT(n <= size()); return left(size() - n); }
 
     void truncate(int pos) Q_DECL_NOTHROW { m_size = qBound(0, pos, m_size); }
     void chop(int n) Q_DECL_NOTHROW

tests/auto/corelib/tools/qstringapisymmetry/tst_qstringapisymmetry.cpp

@@ -608,6 +608,14 @@ void tst_QStringApiSymmetry::chop_impl()
 
     const auto s = make<String>(unicode, latin1, utf8);
 
+    {
+        const auto chopped = s.chopped(n);
+
+        QVERIFY(chopped == result);
+        QCOMPARE(chopped.isNull(), result.isNull());
+        QCOMPARE(chopped.isEmpty(), result.isEmpty());
+    }
+
     {
         auto chopped = s;
         chopped.chop(n);