Add String::lossy constructors to C++ API

This constructor maps to `String::from_utf8_lossy` or
`String::from_utf16_lossy`. It's useful in situations where producing a
slightly garbled string on invalid Unicode data is preferable to
crashing the process, e.g. when passing error messages from C++ to Rust.

1 files changed, 11 insertions, 2 deletions

diff --git a/book/src/binding/string.md b/book/src/binding/string.md
index d564e00c..ad5e9caa 100644
--- a/book/src/binding/string.md
+++ b/book/src/binding/string.md
@@ -18,15 +18,24 @@ public:
   String(String &&) noexcept;
   ~String() noexcept;
 
-  // Throws std::invalid_argument if not utf-8.
+  // Throws std::invalid_argument if not UTF-8.
   String(const std::string &);
   String(const char *);
   String(const char *, size_t);
 
-  // Throws std::invalid_argument if not utf-16.
+  // Replaces invalid UTF-8 data with the replacement character (U+FFFD).
+  static String lossy(const std::string &) noexcept;
+  static String lossy(const char *) noexcept;
+  static String lossy(const char *, std::size_t) noexcept;
+
+  // Throws std::invalid_argument if not UTF-16.
   String(const char16_t *);
   String(const char16_t *, size_t);
 
+  // Replaces invalid UTF-16 data with the replacement character (U+FFFD).
+  static String lossy(const char16_t *) noexcept;
+  static String lossy(const char16_t *, std::size_t) noexcept;
+
   String &operator=(const String &) noexcept;
   String &operator=(String &&) noexcept;