QString/QByteArray: add slice() methods

[ChangeLog][QtCore][QString/QByteArray] Added slice() methods that work
like sliced(), but modify the string/byte-array they are called on.

Task-number: QTBUG-99218
Change-Id: I3075562983ef123d9aa022a2304c7e774cf2ea42
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

src/corelib/doc/snippets/code/src_corelib_text_qbytearray.cpp

@@ -472,4 +472,10 @@ QByteArray byteArray = "test";
 emscripten::val uint8array = QByteArray::toEcmaUint8Array(byteArray);
 //! [56]
 
+//! [57]
+QByteArray x = "Five pineapples"_ba;
+x.slice(5);     // x == "pineapples"
+x.slice(4, 3);  // x == "app"
+//! [57]
+
 }

src/corelib/doc/snippets/qstring/main.cpp

@@ -41,6 +41,7 @@ public:
     void firstFunction();
     void leftJustifiedFunction();
     void slicedFunction();
+    void sliceFunction();
     void numberFunction();
 
     void prependFunction();
@@ -909,6 +910,15 @@ void Widget::arrayOperator()
     //! [85]
 }
 
+void Widget::sliceFunction()
+{
+    //! [86]
+    QString x = u"Nine pineapples"_s;
+    x.slice(5);     // x == "pineapples"
+    x.slice(4, 3);  // x == "app"
+    //! [86]
+}
+
 
 int main(int argc, char *argv[])
 {

src/corelib/text/qbytearray.cpp

@@ -3068,7 +3068,7 @@ bool QByteArray::isLower() const
 
     Returns an empty QByteArray if \a len is smaller than 0.
 
-    \sa endsWith(), last(), first(), sliced(), chopped(), chop(), truncate()
+    \sa endsWith(), last(), first(), sliced(), chopped(), chop(), truncate(), slice()
 */
 
 /*!
@@ -3085,7 +3085,7 @@ bool QByteArray::isLower() const
     returns a byte array containing all bytes starting at position \a
     pos until the end of the byte array.
 
-    \sa first(), last(), sliced(), chopped(), chop(), truncate()
+    \sa first(), last(), sliced(), chopped(), chop(), truncate(), slice()
 */
 
 QByteArray QByteArray::mid(qsizetype pos, qsizetype len) const &
@@ -3139,7 +3139,7 @@ QByteArray QByteArray::mid(qsizetype pos, qsizetype len) &&
     Example:
     \snippet code/src_corelib_text_qbytearray.cpp 27
 
-    \sa last(), sliced(), startsWith(), chopped(), chop(), truncate()
+    \sa last(), sliced(), startsWith(), chopped(), chop(), truncate(), slice()
 */
 
 /*!
@@ -3154,7 +3154,7 @@ QByteArray QByteArray::mid(qsizetype pos, qsizetype len) &&
     Example:
     \snippet code/src_corelib_text_qbytearray.cpp 28
 
-    \sa first(), sliced(), endsWith(), chopped(), chop(), truncate()
+    \sa first(), sliced(), endsWith(), chopped(), chop(), truncate(), slice()
 */
 
 /*!
@@ -3171,7 +3171,7 @@ QByteArray QByteArray::mid(qsizetype pos, qsizetype len) &&
     Example:
     \snippet code/src_corelib_text_qbytearray.cpp 29
 
-    \sa first(), last(), chopped(), chop(), truncate()
+    \sa first(), last(), chopped(), chop(), truncate(), slice()
 */
 QByteArray QByteArray::sliced_helper(QByteArray &a, qsizetype pos, qsizetype n)
 {
@@ -3193,7 +3193,36 @@ QByteArray QByteArray::sliced_helper(QByteArray &a, qsizetype pos, qsizetype n)
 
     \note The behavior is undefined when \a pos < 0 or \a pos > size().
 
-    \sa first(), last(), sliced(), chopped(), chop(), truncate()
+    \sa first(), last(), chopped(), chop(), truncate(), slice()
+*/
+
+/*!
+    \fn QByteArray &QByteArray::slice(qsizetype pos, qsizetype n)
+    \since 6.8
+
+    Modifies this byte array to start at position \a pos, extending for \a n
+    bytes, and returns a reference to this byte array.
+
+    \note The behavior is undefined if \a pos < 0, \a n < 0,
+    or \a pos + \a n > size().
+
+    Example:
+    \snippet code/src_corelib_text_qbytearray.cpp 57
+
+    \sa sliced(), first(), last(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QByteArray &QByteArray::slice(qsizetype pos)
+    \since 6.8
+    \overload
+
+    Modifies this byte array to start at position \a pos, extending to its
+    end, and returns a reference to this byte array.
+
+    \note The behavior is undefined if \a pos < 0 or \a pos > size().
+
+    \sa sliced(), first(), last(), chopped(), chop(), truncate()
 */
 
 /*!
@@ -3206,7 +3235,7 @@ QByteArray QByteArray::sliced_helper(QByteArray &a, qsizetype pos, qsizetype n)
 
     \note The behavior is undefined if \a len is negative or greater than size().
 
-    \sa endsWith(), first(), last(), sliced(), chop(), truncate()
+    \sa endsWith(), first(), last(), sliced(), chop(), truncate(), slice()
 */
 
 /*!

src/corelib/text/qbytearray.h

@@ -238,6 +238,17 @@ public:
     void truncate(qsizetype pos);
     void chop(qsizetype n);
 
+    QByteArray &slice(qsizetype pos)
+    { verify(pos, 0); return remove(0, pos); }
+    QByteArray &slice(qsizetype pos, qsizetype n)
+    {
+        verify(pos, n);
+        if (isNull())
+            return *this;
+        resize(pos + n);
+        return remove(0, pos);
+    }
+
 #if !defined(Q_QDOC)
     [[nodiscard]] QByteArray toLower() const &
     { return toLower_helper(*this); }

src/corelib/text/qstring.cpp

@@ -5181,7 +5181,7 @@ QString QString::section(const QRegularExpression &re, qsizetype start, qsizetyp
     The entire string is returned if \a n is greater than or equal
     to size(), or less than zero.
 
-    \sa endsWith(), last(), first(), sliced(), chopped(), chop(), truncate()
+    \sa endsWith(), last(), first(), sliced(), chopped(), chop(), truncate(), slice()
 */
 
 /*!
@@ -5200,7 +5200,7 @@ QString QString::section(const QRegularExpression &re, qsizetype start, qsizetyp
     \a n is -1 (default), the function returns all characters that
     are available from the specified \a position.
 
-    \sa first(), last(), sliced(), chopped(), chop(), truncate()
+    \sa first(), last(), sliced(), chopped(), chop(), truncate(), slice()
 */
 QString QString::mid(qsizetype position, qsizetype n) const &
 {
@@ -5251,7 +5251,7 @@ QString QString::mid(qsizetype position, qsizetype n) &&
 
     \snippet qstring/main.cpp 31
 
-    \sa last(), sliced(), startsWith(), chopped(), chop(), truncate()
+    \sa last(), sliced(), startsWith(), chopped(), chop(), truncate(), slice()
 */
 
 /*!
@@ -5265,7 +5265,7 @@ QString QString::mid(qsizetype position, qsizetype n) &&
 
     \snippet qstring/main.cpp 48
 
-    \sa first(), sliced(), endsWith(), chopped(), chop(), truncate()
+    \sa first(), sliced(), endsWith(), chopped(), chop(), truncate(), slice()
 */
 
 /*!
@@ -5281,7 +5281,7 @@ QString QString::mid(qsizetype position, qsizetype n) &&
 
     \snippet qstring/main.cpp 34
 
-    \sa first(), last(), chopped(), chop(), truncate()
+    \sa first(), last(), chopped(), chop(), truncate(), slice()
 */
 QString QString::sliced_helper(QString &str, qsizetype pos, qsizetype n)
 {
@@ -5303,7 +5303,35 @@ QString QString::sliced_helper(QString &str, qsizetype pos, qsizetype n)
 
     \note The behavior is undefined when \a pos < 0 or \a pos > size().
 
-    \sa first(), last(), sliced(), chopped(), chop(), truncate()
+    \sa first(), last(), chopped(), chop(), truncate(), slice()
+*/
+
+/*!
+    \fn QString &QString::slice(qsizetype pos, qsizetype n)
+    \since 6.8
+
+    Modifies this string to start at position \a pos, extending for \a n
+    characters (code points), and returns a reference to this string.
+
+    \note The behavior is undefined if \a pos < 0, \a n < 0,
+    or \a pos + \a n > size().
+
+    \snippet qstring/main.cpp 86
+
+    \sa sliced(), first(), last(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QString &QString::slice(qsizetype pos)
+    \since 6.8
+    \overload
+
+    Modifies this string to start at position \a pos and extending to its end,
+    and returns a reference to this string.
+
+    \note The behavior is undefined if \a pos < 0 or \a pos > size().
+
+    \sa sliced(), first(), last(), chopped(), chop(), truncate()
 */
 
 /*!
@@ -5316,7 +5344,7 @@ QString QString::sliced_helper(QString &str, qsizetype pos, qsizetype n)
 
     \note The behavior is undefined if \a len is negative or greater than size().
 
-    \sa endsWith(), first(), last(), sliced(), chop(), truncate()
+    \sa endsWith(), first(), last(), sliced(), chop(), truncate(), slice()
 */
 
 /*!

src/corelib/text/qstring.h

@@ -196,6 +196,17 @@ public:
     void truncate(qsizetype pos);
     void chop(qsizetype n);
 
+    QString &slice(qsizetype pos)
+    { verify(pos, 0); return remove(0, pos); }
+    QString &slice(qsizetype pos, qsizetype n)
+    {
+        verify(pos, n);
+        if (isNull())
+            return *this;
+        resize(pos + n);
+        return remove(0, pos);
+    }
+
     inline qsizetype capacity() const;
     inline void reserve(qsizetype size);
     inline void squeeze();

tests/auto/corelib/text/qbytearray/tst_qbytearray.cpp

@@ -132,6 +132,7 @@ private slots:
     void mid();
     void length();
     void length_data();
+    void slice() const;
 };
 
 static const QByteArray::DataPointer staticStandard = {
@@ -2890,5 +2891,31 @@ void tst_QByteArray::length_data()
     QTest::newRow("with '\\0' no size") << QByteArray("abc\0def") << qsizetype(3);
 }
 
+void tst_QByteArray::slice() const
+{
+    QByteArray a;
+
+    a.slice(0);
+    QVERIFY(a.isEmpty());
+    QVERIFY(a.isNull());
+    a.slice(0, 0);
+    QVERIFY(a.isEmpty());
+    QVERIFY(a.isNull());
+
+    a = "Five pineapples";
+
+    a.slice(5);
+    QCOMPARE_EQ(a, "pineapples");
+
+    a.slice(4, 3);
+    QCOMPARE_EQ(a, "app");
+
+    a.slice(a.size());
+    QVERIFY(a.isEmpty());
+
+    a.slice(0, 0);
+    QVERIFY(a.isEmpty());
+}
+
 QTEST_MAIN(tst_QByteArray)
 #include "tst_qbytearray.moc"

tests/auto/corelib/text/qstring/tst_qstring.cpp

@@ -710,6 +710,7 @@ private slots:
     void first();
     void last();
     void sliced();
+    void slice();
     void chopped();
     void removeIf();
 
@@ -9143,6 +9144,29 @@ void tst_QString::sliced()
     QCOMPARE(a, u"ABCDEFGHIEfGEFG");
 }
 
+void tst_QString::slice()
+{
+    QString a;
+
+    a.slice(0);
+    QVERIFY(a.isEmpty());
+    QVERIFY(a.isNull());
+    a.slice(0, 0);
+    QVERIFY(a.isEmpty());
+    QVERIFY(a.isNull());
+
+    a = u"Five pineapples"_s;
+
+    a.slice(5);
+    QCOMPARE_EQ(a, u"pineapples");
+
+    a.slice(4, 3);
+    QCOMPARE_EQ(a, u"app");
+
+    a.slice(a.size());
+    QVERIFY(a.isEmpty());
+}
+
 void tst_QString::chopped()
 {
     QString a;

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

@@ -694,6 +694,7 @@ private:
 
     void sliced_data();
     template <typename String> void sliced_impl();
+    template <typename String> void slice_impl();
 
     void first_data();
     template <typename String> void first_impl();
@@ -782,6 +783,11 @@ private Q_SLOTS:
     void sliced_QByteArrayView_data() { sliced_data(); }
     void sliced_QByteArrayView() { sliced_impl<QByteArrayView>(); }
 
+    void slice_QString_data() { sliced_data(); }
+    void slice_QString() { slice_impl<QString>(); }
+    void slice_QByteArray_data() { sliced_data(); }
+    void slice_QByteArray() { slice_impl<QByteArray>(); }
+
     void first_truncate_QString_data() { first_data(); }
     void first_truncate_QString() { first_impl<QString>(); }
     void first_truncate_QStringView_data() { first_data(); }
@@ -2426,6 +2432,27 @@ void tst_QStringApiSymmetry::sliced_impl()
     }
 }
 
+template <typename String>
+void tst_QStringApiSymmetry::slice_impl()
+{
+    QFETCH(const QStringView, unicode);
+    QFETCH(const QLatin1String, latin1);
+    QFETCH(const int, pos);
+    QFETCH(const int, n);
+    QFETCH(const QAnyStringView, result);
+    QFETCH(const QAnyStringView, result2);
+
+    const auto str = make<String>(unicode, latin1, unicode.toUtf8());
+
+    auto s = str;
+    s.slice(pos);
+    QCOMPARE_EQ(s, result);
+
+    s = str;
+    s.slice(pos, n);
+    QCOMPARE_EQ(s, result2);
+}
+
 void tst_QStringApiSymmetry::first_data()
 {
     QTest::addColumn<QStringView>("unicode");