================
@@ -0,0 +1,113 @@
+.. title:: clang-tidy - modernize-use-string-view
+
+modernize-use-string-view
+=========================
+
+Looks for functions returning ``std::[w|u8|u16|u32]string`` and suggests to
+change it to ``std::[...]string_view`` for performance reasons if possible.
+
+Each time a new ``std::string`` is created from a literal, a copy of that
+literal is allocated either in ``std::string``'s internal buffer
+(for short literals) or in a heap.
+
+For the cases where ``std::string`` is returned from a function,
+such allocations can sometimes be eliminated by using ``std::string_view``
+as a return type.
+
+This check looks for such functions returning ``std::string`` baked from the
+literals and suggests replacing their return type to ``std::string_view``.
+
+It handles ``std::string``, ``std::wstring``, ``std::u8string``,
+``std::u16string`` and ``std::u32string`` along with their aliases and selects
+the proper kind of ``std::string_view`` to return.
+
+Consider the following example:
+
+.. code-block:: c++
+
+ std::string foo(int i) {
+ switch(i) {
+ case 1:
+ return "case 1";
+ ...
+ default:
+ return "default";
+ }
+ }
+
+In the code above a new ``std::string`` object is created on each function
+invocation, making a copy of a string literal and possibly allocating a memory
+in a heap.
+
+The check gets this code transformed into:
+
+.. code-block:: c++
+
+ std::string_view foo(int i) {
+ switch(i) {
+ case 1:
+ return "case 1";
+ ...
+ default:
+ return "default";
+ }
+ }
+
+New version re-uses statically allocated literals without additional overhead.
+
+Hint
+----
+
+To prevent a warning and a fix wrap your string with ``std::string(...)``:
+
+.. code-block:: c++
+
+ std::string foo() {
+ return "default"; //warning and fix are generated
+ }
+
+ std::string bar() {
+ return std::string("default"); //warning and fix are NOT generated
+ }
+
+Limitations
+-----------
+
+* No warning and/or fix are generated as for now for these code patterns:
+
+ * ``return std::string("literal");`` - hint: to prevent a warning and a fix
+ you may wrap your string with ``std::string(...)``
+ * ``return std::string{"literal"};``
+ * ``return "simpleLiteral"s;``
+ * ``auto foo() { return "autoReturn"; }``
+ * ``auto Trailing() -> std::string { return "Trailing"; }`` warns, doesn't
fix
+ * returnings from lambda
+ * complicated macro and templated code
+
+* In some cases the fixed code can be incorrect. But it's usually easy to fix:
+
+.. code-block:: c++
+
+ string foo() { // <--- will be replaced with string_view
+ return "foo";
+ }
+
+ void bar() {
+ string f = foo(); // <----- error: no viable conversion from
'std::string_view'
+ // (aka 'basic_string_view<char>') to 'std::string'
(aka 'basic_string<char>')
+ }
+
+
+Options
+-------
+
+.. option:: IgnoredFunctions
+
+ A semicolon-separated list of the names of functions or methods to be
+ ignored. Regular expressions are accepted, e.g. `[Rr]ef(erence)?$` matches
+ every type with suffix ``Ref``, ``ref``, ``Reference`` and ``reference``.
+ The default is {`toString$;ToString$;to_string$`}. If a name in the list
+ contains the sequence `::` it is matched against the qualified type name
+ (i.e. ``namespace::Type``), otherwise it is matched against only the type
+ name (i.e. ``Type``).
+ The default is `toString$;ToString$;to_string$`.
----------------
zwuis wrote:
Duplicate default value.
https://github.com/llvm/llvm-project/pull/172170
_______________________________________________
cfe-commits mailing list
[email protected]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
