From: Corey Farwell <coreyf@rwell.org>
Date: Thu, 14 Sep 2017 19:34:31 +0000 (-0400)
Subject: Clarify return type of `String::from_utf16_lossy`.
X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=258ef37f8e81388a11f420411e35b427215b0754;p=rust.git

Clarify return type of `String::from_utf16_lossy`.

Fixes https://github.com/rust-lang/rust/issues/32874
---

diff --git a/src/liballoc/string.rs b/src/liballoc/string.rs
index 1708f3e3987..088082c261a 100644
--- a/src/liballoc/string.rs
+++ b/src/liballoc/string.rs
@@ -622,6 +622,13 @@ pub fn from_utf16(v: &[u16]) -> Result<String, FromUtf16Error> {
     /// Decode a UTF-16 encoded slice `v` into a `String`, replacing
     /// invalid data with the replacement character (U+FFFD).
     ///
+    /// Unlike [`from_utf8_lossy`] which returns a [`Cow<'a, str>`],
+    /// `from_utf16_lossy` returns a `String` since the UTF-16 to UTF-8
+    /// conversion requires a memory allocation.
+    ///
+    /// [`from_utf8_lossy`]: #method.from_utf8_lossy
+    /// [`Cow<'a, str>`]: ../borrow/enum.Cow.html
+    ///
     /// # Examples
     ///
     /// Basic usage: