diff --git a/src/corelib/doc/images/string_class_api.svg b/src/corelib/doc/images/string_class_api.svg index c46b40d1bf3..b3bfc3082da 100644 --- a/src/corelib/doc/images/string_class_api.svg +++ b/src/corelib/doc/images/string_class_api.svg @@ -1,9 +1,7 @@ - + xmlns="http://www.w3.org/2000/svg"> - + - String class - for creating API + Choosing a string class + for creating an API @@ -68,8 +66,8 @@ font-size="12" fill="black" text-anchor="middle" dominant-baseline="middle" transform="translate(0, -6)"> - parameter or - return value? + For a parameter + or the return value? @@ -112,7 +110,7 @@ - const QString& + const QString&¹ @@ -123,8 +121,8 @@ text-anchor="middle" dominant-baseline="middle" transform="translate(0, -8)" > Q*StringView - parameters preferably QAnyStringView - or any of L1, UTF8, or UTF16 + Parameters: preferably QAnyStringView + Generally: any of L1, UTF-8, or UTF-16 @@ -231,4 +229,17 @@ temporary + + + + 1: + If you return a QString in full, you can choose + to return a value instead of a reference, allowing you to return a + temporary in the future without + breaking source code compatibility. This is + also done for all Qt APIs. + + diff --git a/src/corelib/doc/images/string_class_calling.svg b/src/corelib/doc/images/string_class_calling.svg index 2fcc15bea3d..4253d35705b 100644 --- a/src/corelib/doc/images/string_class_calling.svg +++ b/src/corelib/doc/images/string_class_calling.svg @@ -1,9 +1,7 @@ - + xmlns="http://www.w3.org/2000/svg"> - + - String class for - calling Qt functions + Choosing a string class + for calling Qt functions @@ -81,7 +79,7 @@ text-anchor="middle" dominant-baseline="middle" transform="translate(0, -6)"> Is the parameter a - QString or a *View? + QString or a Q*View? @@ -92,8 +90,8 @@ font-size="12" fill="black" text-anchor="middle" dominant-baseline="middle" transform="translate(0, -6)"> - Do you know the - preferred encoding? + Has the parameter a + preferred² encoding? @@ -115,8 +113,8 @@ font-size="12" fill="black" text-anchor="middle" dominant-baseline="middle" transform="translate(0, -4)" > - QString - or what is already existing + QString¹ + or any other owning string @@ -127,7 +125,7 @@ text-anchor="middle" dominant-baseline="middle" transform="translate(0, -4)" > QStringLiteral - same as u""_s + same as u"foo"_s @@ -138,7 +136,7 @@ text-anchor="middle" dominant-baseline="middle" transform="translate(0, -4)" > QLatin1StringView - same as u""_s + create with "foo"_L1 @@ -149,7 +147,7 @@ text-anchor="middle" dominant-baseline="middle" transform="translate(0, -4)" > QStringView - create with u"" + create with u"foo" f @@ -162,7 +160,7 @@ transform="translate(0, -8)" > Q*StringView of the preferred encoding, - create with u"", u8"" or ""_L1 + create with u"foo", u8"foo" or "foo"_L1 @@ -214,7 +212,7 @@ - *View + Q*View @@ -263,4 +261,22 @@ + + + 1: + An owning string is required to assemble or store + a string at runtime, if it is not known at compile time. This can be + QString or any other + owning string, such as std::string. The correct + choice depends on the required encoding. + 2: + Some functions are more effective when using the + preferred encoding. For example, QUtf8StringView::compare is fastest + with + QUtf8StringView. If you are unsure, proceed as + if there were no preferred encoding. + +