Implement first/last/from and slice() for string-like classes

These methods are scheduled as a replacement for left/right/mid()
in Qt 6 with a consistent, narrow contract that does not allow
out of bounds indices, and therefore does permit faster
implementations.

Change-Id: Iabf22e8d4f3fef3c5e69a17f103e6cddebe420b1
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>

6 files changed, 173 insertions, 3 deletions

diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp
index 1a0237c225..008ce7298b 100644
--- a/src/corelib/text/qbytearray.cpp
+++ b/src/corelib/text/qbytearray.cpp
@@ -2989,6 +2989,53 @@ QByteArray QByteArray::mid(int pos, int len) const
 }
 
 /*!
+    \fn QByteArray QByteArray::first(qsizetype n) const
+    \since 6.0
+
+    Returns the first \a n bytes of the byte array.
+
+    \note The behavior is undefined when \a n < 0 or \a n > size().
+
+    \sa last(), slice(), from(), startsWith(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QByteArray QByteArray::last(qsizetype n) const
+    \since 6.0
+
+    Returns the last \a n bytes of the byte array.
+
+    \note The behavior is undefined when \a n < 0 or \a n > size().
+
+    \sa first(), slice(), from(), endsWith(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QByteArray QByteArray::slice(qsizetype pos, qsizetype n) const
+    \since 6.0
+
+    Returns a byte array containing the \a n bytes of this object starting
+    at position \a pos.
+
+    \note The behavior is undefined when \a pos < 0, \a n < 0,
+    or \a pos + \a n > size().
+
+    \sa first(), last(), from(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QByteArray QByteArray::from(qsizetype pos) const
+    \since 6.0
+
+    Returns a byte array containing the bytes starting at position \a pos
+    in this object, and extending to the end of this object.
+
+    \note The behavior is undefined when \a pos < 0 or \a pos > size().
+
+    \sa first(), last(), slice(), chopped(), chop(), truncate()
+*/
+
+/*!
     \fn QByteArray::chopped(int len) const
     \since 5.10
 
diff --git a/src/corelib/text/qbytearray.h b/src/corelib/text/qbytearray.h
index 265ad9c642..130509802b 100644
--- a/src/corelib/text/qbytearray.h
+++ b/src/corelib/text/qbytearray.h
@@ -224,8 +224,17 @@ public:
     Q_REQUIRED_RESULT 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 first(qsizetype n) const
+    { Q_ASSERT(n >= 0); Q_ASSERT(n <= size()); return QByteArray(data(), int(n)); }
+    Q_REQUIRED_RESULT QByteArray last(qsizetype n) const
+    { Q_ASSERT(n >= 0); Q_ASSERT(n <= size()); return QByteArray(data() + size() - n, int(n)); }
+    Q_REQUIRED_RESULT QByteArray from(qsizetype pos) const
+    { Q_ASSERT(pos >= 0); Q_ASSERT(pos <= size()); return QByteArray(data() + pos, size() - int(pos)); }
+    Q_REQUIRED_RESULT QByteArray slice(qsizetype pos, qsizetype n) const
+    { Q_ASSERT(pos >= 0); Q_ASSERT(n >= 0); Q_ASSERT(size_t(pos) + size_t(n) <= size_t(size())); return QByteArray(data() + pos, int(n)); }
     Q_REQUIRED_RESULT QByteArray chopped(int len) const
-    { Q_ASSERT(len >= 0); Q_ASSERT(len <= size()); return left(size() - len); }
+    { Q_ASSERT(len >= 0); Q_ASSERT(len <= size()); return first(size() - len); }
 
     bool startsWith(const QByteArray &a) const;
     bool startsWith(char c) const;
diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp
index b84262340b..6707cc580e 100644
--- a/src/corelib/text/qstring.cpp
+++ b/src/corelib/text/qstring.cpp
@@ -4601,10 +4601,58 @@ QString QString::mid(int position, int n) const
 }
 
 /*!
+    \fn QString QString::first(qsizetype n) const
+    \since 6.0
+
+    Returns a string that contains the first \a n characters
+    of this string.
+
+    \note The behavior is undefined when \a n < 0 or \a n > size().
+
+    \sa last(), slice(), from(), startsWith(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QString QString::last(qsizetype n) const
+    \since 6.0
+
+    Returns the string that contains the last \a n characters of this string.
+
+    \note The behavior is undefined when \a n < 0 or \a n > size().
+
+    \sa first(), slice(), from(), endsWith(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QString QString::slice(qsizetype pos, qsizetype n) const
+    \since 6.0
+
+    Returns a string that contains \a n characters of this string,
+    starting at position \a pos.
+
+    \note The behavior is undefined when \a pos < 0, \a n < 0,
+    or \a pos + \a n > size().
+
+    \sa first(), last(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QString QString::from(qsizetype pos) const
+    \since 6.0
+
+    Returns a string that contains the portion of this string starting at
+    position \a pos and extending to its end.
+
+    \note The behavior is undefined when \a pos < 0 or \a pos > size().
+
+    \sa first(), last(), slice(), chopped(), chop(), truncate()
+*/
+
+/*!
     \fn QString QString::chopped(int len) const
     \since 5.10
 
-    Returns a substring that contains the size() - \a len leftmost characters
+    Returns a string 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().
diff --git a/src/corelib/text/qstring.h b/src/corelib/text/qstring.h
index 54aacfb298..c0b23c9733 100644
--- a/src/corelib/text/qstring.h
+++ b/src/corelib/text/qstring.h
@@ -455,8 +455,17 @@ public:
     Q_REQUIRED_RESULT 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 first(qsizetype n) const
+    { Q_ASSERT(n >= 0); Q_ASSERT(n <= size()); return QString(data(), int(n)); }
+    Q_REQUIRED_RESULT QString last(qsizetype n) const
+    { Q_ASSERT(n >= 0); Q_ASSERT(n <= size()); return QString(data() + size() - n, int(n)); }
+    Q_REQUIRED_RESULT QString from(qsizetype pos) const
+    { Q_ASSERT(pos >= 0); Q_ASSERT(pos <= size()); return QString(data() + pos, size() - int(pos)); }
+    Q_REQUIRED_RESULT QString slice(qsizetype pos, qsizetype n) const
+    { Q_ASSERT(pos >= 0); Q_ASSERT(n >= 0); Q_ASSERT(size_t(pos) + size_t(n) <= size_t(size())); return QString(data() + pos, int(n)); }
     Q_REQUIRED_RESULT QString chopped(int n) const
-    { Q_ASSERT(n >= 0); Q_ASSERT(n <= size()); return left(size() - n); }
+    { Q_ASSERT(n >= 0); Q_ASSERT(n <= size()); return first(size() - n); }
 
 
     Q_REQUIRED_RESULT QStringRef leftRef(int n) const;
diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp
index 667d9306af..b9dc9d2d41 100644
--- a/src/corelib/text/qstringview.cpp
+++ b/src/corelib/text/qstringview.cpp
@@ -657,6 +657,54 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \fn QStringView QStringView::first(qsizetype n) const
+    \since 6.0
+
+    Returns a string view that points to the first \a n characters
+    of this string.
+
+    \note The behavior is undefined when \a n < 0 or \a n > size().
+
+    \sa last(), subString(), startsWith(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QStringView QStringView::last(qsizetype n) const
+    \since 6.0
+
+    Returns a string view that points to the last \a n characters of this string.
+
+    \note The behavior is undefined when \a n < 0 or \a n > size().
+
+    \sa first(), subString(), endsWith(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QStringView QStringView::slice(qsizetype pos, qsizetype n) const
+    \since 6.0
+
+    Returns a string view that points to \a n characters of this string,
+    starting at position \a pos.
+
+    \note The behavior is undefined when \a pos < 0, \a n < 0,
+    or \a pos + \a n > size().
+
+    \sa first(), last(), chopped(), chop(), truncate()
+*/
+
+/*!
+    \fn QStringView QStringView::from(qsizetype pos) const
+    \since 6.0
+
+    Returns a string view starting at position \a pos in this object,
+    and extending to its end.
+
+    \note The behavior is undefined when \a pos < 0 or \a pos > size().
+
+    \sa first(), last(), chopped(), chop(), truncate()
+*/
+
+/*!
     \fn QStringView QStringView::chopped(qsizetype length) const
 
     Returns the substring of length size() - \a length starting at the
diff --git a/src/corelib/text/qstringview.h b/src/corelib/text/qstringview.h
index 028bf3a544..2b085c769d 100644
--- a/src/corelib/text/qstringview.h
+++ b/src/corelib/text/qstringview.h
@@ -265,6 +265,15 @@ public:
     { return Q_ASSERT(n >= 0), Q_ASSERT(n <= size()), QStringView(m_data, n); }
     Q_REQUIRED_RESULT Q_DECL_CONSTEXPR QStringView right(qsizetype n) const
     { return Q_ASSERT(n >= 0), Q_ASSERT(n <= size()), QStringView(m_data + m_size - n, n); }
+
+    Q_REQUIRED_RESULT constexpr QStringView first(qsizetype n) const
+    { Q_ASSERT(n >= 0); Q_ASSERT(n <= size()); return QStringView(m_data, int(n)); }
+    Q_REQUIRED_RESULT constexpr QStringView last(qsizetype n) const
+    { Q_ASSERT(n >= 0); Q_ASSERT(n <= size()); return QStringView(m_data + size() - n, int(n)); }
+    Q_REQUIRED_RESULT constexpr QStringView from(qsizetype pos) const
+    { Q_ASSERT(pos >= 0); Q_ASSERT(pos <= size()); return QStringView(m_data + pos, size() - int(pos)); }
+    Q_REQUIRED_RESULT constexpr QStringView slice(qsizetype pos, qsizetype n) const
+    { Q_ASSERT(pos >= 0); Q_ASSERT(n >= 0); Q_ASSERT(size_t(pos) + size_t(n) <= size_t(size())); return QStringView(m_data + pos, int(n)); }
     Q_REQUIRED_RESULT Q_DECL_CONSTEXPR QStringView chopped(qsizetype n) const
     { return Q_ASSERT(n >= 0), Q_ASSERT(n <= size()), QStringView(m_data, m_size - n); }