Revision control
++ // Copyright (C) 2025 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \group string-processing
++
++ \title Classes for string data
++
++ \section1 Overview
++
++ This page gives an overview over string classes in Qt, in particular the
++ large amount of string containers and how to use them efficiently in
++ performance-critical code.
++
++ The following instructions for efficient use are aimed at experienced
++ developers working on performance-critical code that contains considerable
++ amounts of string processing. This is, for example, a parser or a text file
++ generator. \e {Generally, \l QString can be used everywhere and it will
++ perform fine.} It also provides APIs for handling several encodings (for
++ example \l{QString::fromLatin1()}). For many applications and especially when
++ string-processing plays an insignificant role for performance, \l QString
++ will be a simple and sufficient solution. Some Qt functions return a \l
++ QStringView. It can be converted to a QString with
++ \l{QStringView::toString()} if required.
++
++ \section2 Impactful tips
++
++ The following three rules improve string handling substantially without
++ increasing the complexity too much. Follow these rules to get nearly
++ optimal performance in most cases. The first two rules address encoding of
++ string literals and marking them in source code. The third rule addresses
++ deep copies when using parts of a string.
++
++ \list
++
++ \li All strings that only contain ASCII characters (for example log
++ messages) can be encoded with Latin-1. Use the
++ \l{Qt::Literals::StringLiterals::operator""_L1}{string literal}
++ \c{"foo"_L1}. Without
++ this suffix, string literals in source code are assumed to be UTF-8
++ encoded and processing them will be slower. Generally, try to use the
++ tightest encoding, which is Latin-1 in many cases.
++
++ \li User-visible strings are usually translated and thus passed through the
++ \l {QObject::tr()} function. This function takes a string literal (const char
++ array) and returns a \l QString with UTF-16 encoding as demanded by all UI
++ elements. If the translation infrastructure is not used, you should use
++ UTF-16 encoding throughout the whole application. Use the string literal
++ \c{u"foo"} to create UTF-16 string literals or the Qt specific literal
++ \c{u"foo"_s} to directly create a \l QString.
++
++ \li When processing parts of a \l QString, instead of copying each part
++ into its own \l QString object, create \l QStringView objects instead.
++ These can be converted back to \l QString using
++ \l{QStringView::toString()}, but avoid doing so as much as possible. If
++ functions return \l QStringView, it is most efficient to keep working with
++ this class, if possible. The API is similar to a constant \l QString.
++
++ \endlist
++
++ \section2 Efficient usage
++
++ To use string classes efficiently, one should understand the three concepts
++ of:
++ \list
++ \li Encoding
++ \li Owning and non-owning containers
++ \li Literals
++ \endlist
++
++ \section3 Encoding
++
++ Encoding-wise Qt supports UTF-16, UTF-8, Latin-1 (ISO 8859-1) and US-ASCII
++ (that is the common subset of Latin-1 and UTF-8) in one form or another.
++ \list
++ \li Latin-1 is a character encoding that uses a single byte per character
++ which makes it the most efficient but also limited encoding.
++ \li UTF-8 is a variable-length character encoding that encodes all
++ characters using one to four bytes. It is backwards compatible to
++ US-ASCII and it is the common encoding for source code and similar
++ files. Qt assumes that source code is encoded in UTF-8.
++ \li UTF-16 is a variable-length encoding that uses two or four bytes per
++ character. It is the common encoding for user-exposed text in Qt.
++ \endlist
++ See the \l{Unicode in Qt}{information about support for Unicode in Qt} for
++ more information.
++
++ Other encodings are supported in the form of single functions like
++ \l{QString::fromUcs4()} or of the \l{QStringConverter} classes. Furthermore,
++ Qt provides an encoding-agnostic container for data, \l QByteArray, that is
++ well-suited to storing binary data. \l QAnyStringView keeps track of the
++ encoding of the underlying string and can thus carry a view onto strings
++ with any of the supported encoding standards.
++
++ Converting between encodings is expensive, therefore, avoid if possible. On
++ the other hand, a more compact encoding, particularly for string literals,
++ can reduce binary size, which can increase performance. Where string
++ literals can be expressed in Latin-1, it manages a good compromise between
++ these competing factors, even if it has to be converted to UTF-16 at some
++ point. When a Latin-1 string must be converted to a \l QString, it is done
++ relatively efficiently.
++
++ \section3 Functionality
++
++ String classes can be further distinguished by the functionality they
++ support. One major distinction is whether they own, and thus control, their
++ data or merely reference data held elsewhere. The former are called \e
++ owning containers, the latter \e non-owning containers or views. A
++ non-owning container type typically just records a pointer to the start of
++ the data and its size, making it lightweight and cheap, but it only remains
++ valid as long as the data remains available. An owning string manages the
++ memory in which it stores its data, ensuring that data remains available
++ throughout the lifetime of the container, but its creation and destruction
++ incur the costs of allocating and releasing memory. Views typically support
++ a subset of the functions of the owning string, lacking the possibility to
++ modify the underlying data.
++
++ As a result, string views are particularly well-suited to representing
++ parts of larger strings, for example in a parser, while owning strings are
++ good for persistent storage, such as members of a class. Where a function
++ returns a string that it has constructed, for example by combining
++ fragments, it has to return an owning string; but where a function returns
++ part of some persistently stored string, a view is usually more suitable.
++
++ Note that owning containers in Qt share their data \l{Implicit
++ Sharing}{implicitly}, meaning that it is also efficient to pass or return
++ large containers by value, although slightly less efficient than passing by
++ reference due to the reference counting. If you want to make use of the
++ implicit data sharing mechanism of Qt classes, you have to pass the string
++ as an owning container or a reference to one. Conversion to a view and back
++ will always create an additional copy of the data.
++
++ Finally, Qt provides classes for single characters, lists of strings and
++ string matchers. These classes are available for most supported encoding
++ standards in Qt, with some exceptions. Higher level functionality is
++ provided by specialized classes, such as \l QLocale or \l
++ QTextBoundaryFinder. These high level classes usually rely on \l QString
++ and its UTF-16 encoding. Some classes are templates and work with all
++ available string classes.
++
++ \section3 Literals
++
++ The C++ standard provides
++ \l{https://en.cppreference.com/w/cpp/language/string_literal} {string
++ literals} to create strings at compile-time. There are string literals
++ defined by the language and literals defined by Qt, so-called
++ \l{https://en.cppreference.com/w/cpp/language/user_literal}{user-defined
++ literals}. A string literal defined by C++ is enclosed in double quotes and
++ can have a prefix that tells the compiler how to interpret its content. For
++ Qt, the UTF-16 string literal \c{u"foo"} is the most important. It creates
++ a string encoded in UTF-16 at compile-time, saving the need to convert from
++ some other encoding at run-time. \l QStringView can be easily and
++ efficiently constructed from one, so they can be passed to functions that
++ accept a \l QStringView argument (or, as a result, a \l QAnyStringView).
++
++ User-defined literals have the same form as those defined by C++ but add a
++ suffix after the closing quote. The encoding remains determined by the
++ prefix, but the resulting literal is used to construct an object of some
++ user-defined type. Qt thus defines these for some of its own string types:
++ \c{u"foo"_s} for \l QString, \c{"foo"_L1} for \l QLatin1StringView and
++ \c{u"foo"_ba} for \l QByteArray. These are provided by using the
++ \l{Qt::Literals::StringLiterals}{StringLiterals Namespace}. A plain C++
++ string literal \c{"foo"} will be
++ understood as UTF-8 and conversion to QString and thus UTF-16 will be
++ expensive. When you have string literals in plain ASCII, use \c{"foo"_L1}
++ to interpret it as Latin-1, gaining the various benefits outlined above.
++
++ \section1 Basic string classes
++
++ The following table gives an overview over basic string classes for the
++ various standards of text encoding.
++
++ \table
++ \header
++ \li Encoding
++ \li C++ String literal
++ \li Qt user-defined literal
++ \li C++ Character
++ \li Qt Character
++ \li Owning string
++ \li Non-owning string
++ \row
++ \li Latin-1
++ \li -
++ \li ""_L1
++ \li -
++ \li \l QLatin1Char
++ \li -
++ \li \l QLatin1StringView
++ \row
++ \li UTF-8
++ \li u8""
++ \li -
++ \li char8_t
++ \li -
++ \li -
++ \li \l QUtf8StringView
++ \row
++ \li UTF-16
++ \li u""
++ \li u""_s
++ \li char16_t
++ \li \l QChar
++ \li \l QString
++ \li \l QStringView
++ \row
++ \li Binary/None
++ \li -
++ \li ""_ba
++ \li std::byte
++ \li -
++ \li \l QByteArray
++ \li \l QByteArrayView
++ \row
++ \li Flexible
++ \li any
++ \li -
++ \li -
++ \li -
++ \li -
++ \li \l QAnyStringView
++ \endtable
++
++ Some of the missing entries can be substituted with built-in and standard
++ library C++ types: An owning Latin-1 or UTF-8 encoded string can be
++ \c{std::string} or any 8-bit \c char array. \l QStringView can also reference
++ any 16-bit character arrays, such as std::u16string or std::wstring on some
++ platforms.
++
++ Qt also provides specialized lists for some of those types, that are \l
++ QStringList and \l QByteArrayView, as well as matchers, \l
++ QLatin1StringMatcher and \l QByteArrayMatcher. The matchers also have
++ static versions that are created at compile-time, \l
++ QStaticLatin1StringMatcher and \l QStaticByteArrayMatcher.
++
++ Further worth noting:
++
++ \list
++
++ \li \l QStringLiteral is a macro which is identical to \c{u"foo"_s} and
++ available without the \l{Qt::Literals::StringLiterals}{StringLiterals
++ Namespace}. Preferably you should use the modern string literal.
++
++ \li \l QLatin1String is a synonym for \l QLatin1StringView and exists for
++ backwards compatibility. It is not an owning string and might be removed in
++ future releases.
++
++ \li \l QAnyStringView provides a view for a string with any of the three
++ supported encodings. The encoding is stored alongside the reference to the
++ data. This class is well suited to create interfaces that take a wide
++ spectrum of string types and encodings. In contrast to other classes, no
++ processing is conducted on \l QAnyStringView directly. Processing is
++ conducted on the underlying \l QLatin1StringView, \l QUtf8StringView or
++ \l QStringView in the respective encoding. Use \l QAnyStringView::visit()
++ to do the same in your own functions that take this class as an argument.
++
++ \li A \l QLatin1StringView with non-ASCII characters is not straightforward
++ to construct in a UTF-8 encoded source code file and requires special
++ treatment, see the \l QLatin1StringView documentation.
++
++ \li \l QStringRef is a reference to a portion of a \l QString, available in
++ the Qt5Compat module for backwards compatibility. It should be replaced by
++ \l QStringView.
++
++ \endlist
++
++ \section1 High-level string-related classes
++
++ More high-level classes that provide additional functionality work
++ mostly with \l QString and thus UTF-16. These are:
++
++ \list
++ \li \l QRegularExpression, \l QRegularExpressionMatch and
++ \l QRegularExpressionMatchIterator to work with pattern matching
++ and regular expressions.
++ \li \l QLocale to convert numbers and data to and from strings in a
++ manner appropriate to the user's language and culture.
++ \li \l QCollator and \l QCollatorSortKey to compare strings with
++ respect to the users language, script or territory.
++ \li \l QTextBoundaryFinder to break up text ready for typesetting
++ in accord with Unicode rules.
++ \li \c{QStringBuilder}, an internal class that will substantially
++ improve the performance of string concatenations with the \c{+}
++ operator, see the \l QString documentation.
++ \endlist
++
++ Some classes are templates or have a flexible API and work with various
++ string classes. These are
++
++ \list
++ \li \l QTextStream to stream into \l QIODevice, \l QByteArray or
++ \l QString
++ \li \l QStringTokenizer to split strings
++ \endlist
++
++ \section1 Which string class to use?
++
++ The general guidance in using string classes is:
++ \list
++ \li Avoid copying and memory allocations,
++ \li Avoid encoding conversions, and
++ \li Choose the most compact encoding.
++ \endlist
++
++ Qt provides many functionalities to avoid memory allocations. Most Qt
++ containers employ \l{Implicit Sharing} of their data. For implicit sharing
++ to work, there must be an uninterrupted chain of the same class —
++ converting from \l QString to \l QStringView and back will result in two \l
++ {QString}{QStrings} that do not share their data. Therefore, functions need
++ to pass their data as \l QString (both values or references work).
++ Extracting parts of a string is not possible with implicit data sharing. To
++ use parts of a longer string, make use of string views, an explicit form of
++ data sharing.
++
++ Conversions between encodings can be reduced by sticking to a certain
++ encoding. Data received, for example in UTF-8, is best stored and processed
++ in UTF-8 if no conversation to any other encoding is required. Comparisons
++ between strings of the same encoding are fastest and the same is the case
++ for most other operations. If strings of a certain encoding are often
++ compared or converted to any other encoding it might be beneficial to
++ convert and store them once. Some operations provide many overloads (or a
++ \l QAnyStringView overload) to take various string types and encodings and
++ they should be the second choice to optimize performance, if using the same
++ encoding is not feasible. Explicit encoding conversions before calling a
++ function should be a last resort when no other option is available. Latin-1
++ is a very simple encoding and operation between Latin-1 and any other
++ encoding are almost as efficient as operations between the same encoding.
++
++ The most efficient encoding (from most to least efficient Latin-1, UTF-8,
++ UTF-16) should be chosen when no other constrains determine the encoding.
++ For error handling and logging \l QLatin1StringView is usually sufficient.
++ User-visible strings in Qt are always of type \l {QString} and as such
++ UTF-16 encoded. Therefore it is most effective to use \l
++ {QString}{QStrings}, \l {QStringView}{QStringViews} and \l
++ {QStringLiteral}{QStringLiterals} throughout the life-time of a
++ user-visible string. The \l QObject::tr() function provides the correct
++ encoding and type. \l QByteArray should be used if encoding does not play a
++ role, for example to store binary data, or if the encoding is unknown.
++
++ \section2 String class for creating API
++
++ \image string_class_api.svg "String class for an optimal API"
++
++ \section3 Member variables
++
++ Member variables should be of an owning type in nearly all cases. Views can only
++ be used as member variables if the lifetime of the referenced owning string
++ is guaranteed to exceed the lifetime of the object.
++
++ \section3 Function arguments
++
++ Function arguments should be string views of a suitable encoding in most
++ cases. \l QAnyStringView can be used as a parameter to support more than
++ one encoding and \l QAnyStringView::visit() can be used internally to fork
++ off into per-encoding functions. If the function is limited to a single
++ encoding, \l QLatin1StringView, \l QUtf8StringView, \l QStringView or \l
++ QByteArrayView should be used.
++
++ If the function saves the argument in an owning string (usually a
++ setter function), it is most efficient to use the same owning string as
++ function argument to make use of the implicit data sharing functionality of
++ Qt. The owning string can be passed as a \c const reference. Overloading
++ functions with multiple owning and non-owning string types can lead to
++ overload ambiguity and should be avoided. Owning string types in Qt can be
++ automatically converted to their non-owning version or to \l
++ QAnyStringView.
++
++ \section3 Return values
++
++ Temporary strings have to be returned as an owning string, usually
++ \l QString. If the returned string is known at compile-time use
++ \c{u"foo"_s} to construct the \l QString structure at compile-time. If
++ existing owning strings (for example \l QString) are returned from a
++ function in full (for example a getter function), it is most efficient to
++ return them by reference. They can also be returned by value to allow
++ returning a temporary in the future. Qt's use of implicit sharing avoids
++ the performance impact of allocation and copying when returning by value.
++
++ Parts of existing strings can be returned efficiently with a string view
++ of the appropriate encoding, for an example see \l
++ QRegularExpressionMatch::capturedView() which returns a \l QStringView.
++
++ \section2 String class for using API
++
++ \image string_class_calling.svg "String class for calling a function"
++
++ To use a Qt API efficiently you should try to match the function argument
++ types. If you are limited in your choice, Qt will conduct various
++ conversions: Owning strings are implicitly converted to non-owning
++ strings, non-owning strings can create their owning counter parts,
++ see for example \l QStringView::toString(). Encoding conversions are
++ conducted implicitly in many cases but this should be avoided if possible.
++ To avoid accidental implicit conversion from UTF-8 you can activate the
++ macro \l QT_NO_CAST_FROM_ASCII.
++
++ If you need to assemble a string at runtime before passing it to a function
++ you will need an owning string and thus \l QString. If the function
++ argument is \l QStringView or \l QAnyStringView it will be implicitly
++ converted.
++
++ If the string is known at compile-time, there is room for optimization. If
++ the function accepts a \l QString, you should create it with \c{u"foo"_s}
++ or the \l QStringLiteral macro. If the function expects a \l QStringView,
++ it is best constructed with an ordinary UTF-16 string literal \c{u"foo"},
++ if a \l QLatin1StringView is expected, construct it with \c{"foo"_L1}. If
++ you have the choice between both, for example if the function expects \l
++ QAnyStringView, use the tightest encoding, usually Latin-1.
++
++ \section1 List of all string related classes
++ */
++
++ // The list is autogenerated by qdoc because this is a group page