Clarify UTF-16 decoding errors

Author: jnodorp

library/alloc/src/string.rs

@@ -410,7 +410,15 @@ pub struct FromUtf8Error {
 /// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 #[derive(Debug)]
-pub struct FromUtf16Error(());
+pub struct FromUtf16Error {
+    kind: FromUtf16ErrorKind,
+}
+
+#[derive(Debug)]
+enum FromUtf16ErrorKind {
+    LoneSurrogate,
+    OddBytes,
+}
 
 impl String {
     /// Creates a new empty `String`.
@@ -719,7 +727,7 @@ impl String {
             if let Ok(c) = c {
                 ret.push(c);
             } else {
-                return Err(FromUtf16Error(()));
+                return Err(FromUtf16Error { kind: FromUtf16ErrorKind::LoneSurrogate });
             }
         }
         Ok(ret)
@@ -781,13 +789,13 @@ impl String {
     #[unstable(feature = "str_from_utf16_endian", issue = "116258")]
     pub fn from_utf16le(v: &[u8]) -> Result<String, FromUtf16Error> {
         let (chunks, []) = v.as_chunks::<2>() else {
-            return Err(FromUtf16Error(()));
+            return Err(FromUtf16Error { kind: FromUtf16ErrorKind::OddBytes });
         };
         match (cfg!(target_endian = "little"), unsafe { v.align_to::<u16>() }) {
             (true, ([], v, [])) => Self::from_utf16(v),
             _ => char::decode_utf16(chunks.iter().copied().map(u16::from_le_bytes))
                 .collect::<Result<_, _>>()
-                .map_err(|_| FromUtf16Error(())),
+                .map_err(|_| FromUtf16Error { kind: FromUtf16ErrorKind::LoneSurrogate }),
         }
     }
 
@@ -856,13 +864,13 @@ impl String {
     #[unstable(feature = "str_from_utf16_endian", issue = "116258")]
     pub fn from_utf16be(v: &[u8]) -> Result<String, FromUtf16Error> {
         let (chunks, []) = v.as_chunks::<2>() else {
-            return Err(FromUtf16Error(()));
+            return Err(FromUtf16Error { kind: FromUtf16ErrorKind::OddBytes });
         };
         match (cfg!(target_endian = "big"), unsafe { v.align_to::<u16>() }) {
             (true, ([], v, [])) => Self::from_utf16(v),
             _ => char::decode_utf16(chunks.iter().copied().map(u16::from_be_bytes))
                 .collect::<Result<_, _>>()
-                .map_err(|_| FromUtf16Error(())),
+                .map_err(|_| FromUtf16Error { kind: FromUtf16ErrorKind::LoneSurrogate }),
         }
     }
 
@@ -2319,7 +2327,14 @@ impl fmt::Display for FromUtf8Error {
 #[stable(feature = "rust1", since = "1.0.0")]
 impl fmt::Display for FromUtf16Error {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        fmt::Display::fmt("invalid utf-16: lone surrogate found", f)
+        match self.kind {
+            FromUtf16ErrorKind::LoneSurrogate => {
+                fmt::Display::fmt("invalid utf-16: lone surrogate found", f)
+            }
+            FromUtf16ErrorKind::OddBytes => {
+                fmt::Display::fmt("invalid utf-16: odd number of bytes", f)
+            }
+        }
     }
 }