Glib: Replace StringView with StdStringView and UStringView

StdStringView and UStringView force users to be explicit (by using c_str())
when using a std::string where a Glib::ustring is recommended or vice versa.
See issue #64

1 files changed, 59 insertions, 26 deletions

diff --git a/glib/glibmm/ustring.h b/glib/glibmm/ustring.h
index 562153fe..2ce10c77 100644
--- a/glib/glibmm/ustring.h
+++ b/glib/glibmm/ustring.h
@@ -1564,56 +1564,89 @@ operator+(char lhs, const ustring& rhs)
   return temp;
 }
 
-//************* Glib::StringView ********************
+//********** Glib::StdStringView and Glib::UStringView *************
+
+// It would be possible to replace StdStringView and UStringView with a
+// template class BasicStringView + two type aliases defining StdStringView
+// and UStringView. But Doxygen don't generate links to type aliases.
+//
+// It would also be possible to replace StdStringView and UStringView with
+// a StringView class with 3 constructors, taking const std::string&,
+// const Glib::ustring& and const char*, respectively. The split into two classes
+// is by design. Using the wrong string class shall not be as easy as using
+// the right string class.
 
 /** Helper class to avoid unnecessary string copying in function calls.
  *
- * A %Glib::StringView holds a const char pointer. It can be used as an argument
+ * A %Glib::StdStringView holds a const char pointer. It can be used as an argument
  * type in a function that passes a const char pointer to a C function.
+ *
+ * Unlike std::string_view, %Glib::StdStringView shall be used only for
+ * null-terminated strings.
  * @code
- * // Use
  * std::string f1(Glib::StdStringView s1, Glib::StdStringView s2);
- * Glib::ustring f2(Glib::UStringView s1, Glib::UStringView s2);
- * // instead of
- * std::string f1(const std::string& s1, const std::string& s2);
- * Glib::ustring f2(const Glib::ustring& s1, const Glib::ustring& s2);
+ * // can be used instead of
+ * std::string f2(const std::string& s1, const std::string& s2);
  * @endcode
- * to avoid string copying when the functions are called with string literals.
+ * The strings are not copied when f1() is called with string literals.
  * @code
  * auto r1 = f1("string 1", "string 2");
- * auto r2 = f2("string 3", "string 4");
+ * @endcode
+ * To pass a Glib::ustring to a function taking a %Glib::StdStringView, you may have
+ * to use Glib::ustring::c_str().
+ * @code
+ * std::string str = "non-UTF8 string";
+ * Glib::ustring ustr = "UTF8 string";
+ * auto r1 = f1(str, ustr.c_str());
  * @endcode
  *
  * @newin{2,64}
  */
-class StringView
+class StdStringView
 {
 public:
-  StringView(const std::string& s) : pstring_(s.c_str()) {}
-  StringView(const Glib::ustring& s) : pstring_(s.c_str()) {}
-  StringView(const char* s) : pstring_(s) {}
+  StdStringView(const std::string& s) : pstring_(s.c_str()) {}
+  StdStringView(const char* s) : pstring_(s) {}
   const char* c_str() const { return pstring_; }
 private:
   const char* pstring_;
 };
 
-/** %Glib::StringView alias.
- *
- * The name %Glib::StdStringView signals that recommended data types are
- * std::string and const char*, but not Glib::ustring.
+/** Helper class to avoid unnecessary string copying in function calls.
  *
- * @relates Glib::StringView
- */
-using StdStringView = StringView;
-
-/** %Glib::StringView alias.
+ * A %Glib::UStringView holds a const char pointer. It can be used as an argument
+ * type in a function that passes a const char pointer to a C function.
  *
- * The name %Glib::UStringView signals that recommended data types are
- * Glib::ustring and const char*, but not std::string.
+ * Unlike std::string_view, %Glib::UStringView shall be used only for
+ * null-terminated strings.
+ * @code
+ * Glib::ustring f1(Glib::UStringView s1, Glib::UStringView s2);
+ * // can be used instead of
+ * Glib::ustring f2(const Glib::ustring& s1, const Glib::ustring& s2);
+ * @endcode
+ * The strings are not copied when f1() is called with string literals.
+ * @code
+ * auto r1 = f1("string 1", "string 2");
+ * @endcode
+ * To pass a std::string to a function taking a %Glib::UStringView, you may have
+ * to use std::string::c_str().
+ * @code
+ * std::string str = "non-UTF8 string";
+ * Glib::ustring ustr = "UTF8 string";
+ * auto r1 = f1(str.c_str(), ustr);
+ * @endcode
  *
- * @relates Glib::StringView
+ * @newin{2,64}
  */
-using UStringView = StringView;
+class UStringView
+{
+public:
+  UStringView(const Glib::ustring& s) : pstring_(s.c_str()) {}
+  UStringView(const char* s) : pstring_(s) {}
+  const char* c_str() const { return pstring_; }
+private:
+  const char* pstring_;
+};
 
 } // namespace Glib