Document number: P1679R0
Date: 2019-05-26
Project: WG21, Library Working Group
Author: Wim Leflere wim.leflere@gmail.com
This paper proposes to add member function contains to class templates basic_string and basic_string_view. This function checks, whether or not a string contains a given substring.
Checking, whether or not a given string contains a given substring is a common task, that is missing from the standard library.
Standard libraries of many other programming languages include routines for performing such a check, for example:
And so on.
Also, some C++ libraries (other than the standard library) that implement a string type include such methods.
For example, Qt library has classes QString 4 and QStringRef (analogous to std::string_view) which have contains member functions.
The teachability of C++ for people coming from other languages might improve, because they are already familiar with the contains function in a string type.
The 'standard' 5 way of checking if a string contains a substring is to use the find member function.
if (str.find(substr) != std::string::npos)
std::cout << "found!" << '\n';
But using find requires that one extra step of thinking when writing it.
You're trying to do something positive (check if contains) but you have to do something negative (check inequality).
And one extra step when reading the code.
Are we looking for the actual position? Or checking if the string contains a substring? Or checking if the string doesn't contain a substring?
A contains member function would make the intention of the programmer more clear and make the code more readable.
if (str.contains(substr))
std::cout << "found!" << '\n';
The proposed change would improve teachability of C++ for beginners as the contains function better matches the intention of the programmer. And because it is a simpler construct to write and remember than using find.
The string contains function would complete the three string checking musketeers, together with the string prefix and suffix check, starts_with and ends_with 6.
This proposal adds member function contains to class templates basic_string and basic_string_view.
Another considered option was to add a free function contains to namespace std, as in Boost 7.
The drawback of a free function is that the order of parameters of a free function is ambiguous, contains(string, substring) vs contains(substring, string).
Qt offers the following overload set (for QString and QStringRef):
bool contains(const QString &str, Qt::CaseSensitivity cs = ...) const
bool contains(QChar ch, Qt::CaseSensitivity cs = ...) const
bool contains(QLatin1String str, Qt::CaseSensitivity cs = ...) const
bool contains(const QStringRef &str, Qt::CaseSensitivity cs = ...) const
This proposal includes the following overloads:
// basic_string:
bool contains(charT ch) const noexcept;
bool contains(basic_string_view<charT, traits> str) const noexcept;
bool contains(const charT* str) const;
// basic_string_view:
constexpr bool contains(charT ch) const noexcept;
constexpr bool contains(basic_string_view<charT, traits> str) const noexcept;
constexpr bool contains(const charT* str) const;