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>

1 files changed, 30 insertions, 6 deletions

diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp
index 07d6376b85..21e76851e6 100644
--- a/src/corelib/tools/qstring.cpp
+++ b/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
@@ -4520,6 +4520,18 @@ QString QString::mid(int position, int n) const
 }
 
 /*!
+    \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
 {
@@ -10277,6 +10289,18 @@ QStringRef QStringRef::mid(int pos, int n) const
 }
 
 /*!
+    \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
 
     Returns a substring reference to \a n characters of this string,