api: Deprecate OIIO::string_view::c_str() (AcademySoftwareFoundation#…

…4511)

Because it's not in std::string_view.

If you must use this functionality (with caution about when it is safe),
then use the freestanding `OIIO::c_str(OIIO::string_view)` function
instead.

I would like to include this warning in 3.0.

Signed-off-by: Larry Gritz <[email protected]>

docs/Deprecations-3.0.md

@@ -206,6 +206,13 @@ about being deprecated will be removed in the final 3.0 release.
 * The old OIIO_SIMD_HAS_FLOAT8 macro has been removed. It was deprecated since
   OIIO 1.8.
 
+## string_view.h
+
+* The string_view::c_str() method has been marked as deprecated, since
+  it is not present in C++17 std::string_view. If you must use this
+  functionality (with caution about when it is safe), then use the
+  freestanding OIIO::c_str(string_view) function instead.
+
 ## strutil.h
 
 * The default behavior of `Strutil::format()` has been changed to use the

src/include/OpenImageIO/string_view.h

@@ -139,24 +139,10 @@ class basic_string_view {
         // N.B. std::string ctr from chars+len is constexpr in C++20.
     }
 
-    /// Explicitly request a 0-terminated string. USUALLY, this turns out to
-    /// be just data(), with no significant added expense (because most uses
-    /// of string_view are simple wrappers of C strings, C++ std::string, or
-    /// ustring -- all of which are 0-terminated). But in the more rare case
-    /// that the string_view represents a non-0-terminated substring, it
-    /// will force an allocation and copy underneath.
-    ///
-    /// Caveats:
-    /// 1. This is NOT going to be part of the C++17 std::string_view, so
-    ///    it's probably best to avoid this method if you want to have 100%
-    ///    drop-in compatibility with std::string_view.
-    /// 2. It is NOT SAFE to use c_str() on a string_view whose last char
-    ///    is the end of an allocation -- because that next char may only
-    ///    *coincidentally* be a '\0', which will cause c_str() to return
-    ///    the string start (thinking it's a valid C string, so why not just
-    ///    return its address?), if there's any chance that the subsequent
-    ///    char could change from 0 to non-zero during the use of the result
-    ///    of c_str(), and thus break the assumption that it's a valid C str.
+    /// DEPRECATED(3.0) -- If you must use this at all, use the freestanding
+    /// OIIO::c_str(OIIO::string_view). We want to get this out of the
+    /// OIIO::string_view template to preserve symmetry with std::string_view.
+    OIIO_DEPRECATED("Unsafe, nonstandard. Use standalone OIIO::c_str(string_view) if you must. (3.0)")
     const CharT* c_str() const;
 
     /// Assignment
@@ -520,6 +506,7 @@ using wstring_view = basic_string_view<wchar_t>;
 OIIO_UTIL_API const char* c_str(string_view str);
 
 
+// DEPRECATED(3.0)
 template<> inline const char*
 basic_string_view<char>::c_str() const {
     return OIIO::c_str(*this);