Provide some utilities for decoding entire buffers

Author: dralley

Changelog.md

@@ -27,6 +27,8 @@
   the XML declared encoding and always use UTF-8
 - [#416]: Add `borrow()` methods in all event structs which allows to get
   a borrowed version of any event
+- [#436]: Added utilities `detect_encoding()`, `decode()`, and `decode_with_bom_removal()`
+  under the `quick-xml::encoding` namespace.
 
 ### Bug Fixes
 

src/encoding.rs

@@ -46,7 +46,7 @@ impl Decoder {
     ///
     /// If you instead want to use XML declared encoding, use the `encoding` feature
     pub fn decode_with_bom_removal<'b>(&self, bytes: &'b [u8]) -> Result<Cow<'b, str>> {
-        let bytes = if bytes.starts_with(b"\xEF\xBB\xBF") {
+        let bytes = if bytes.starts_with(&[0xEF, 0xBB, 0xBF]) {
             &bytes[3..]
         } else {
             bytes
@@ -72,13 +72,7 @@ impl Decoder {
     ///
     /// Returns an error in case of malformed sequences in the `bytes`.
     pub fn decode<'b>(&self, bytes: &'b [u8]) -> Result<Cow<'b, str>> {
-        match self
-            .encoding
-            .decode_without_bom_handling_and_without_replacement(bytes)
-        {
-            None => Err(Error::NonDecodable(None)),
-            Some(s) => Ok(s),
-        }
+        decode(bytes, self.encoding)
     }
 
     /// Decodes a slice with BOM removal if it is present in the `bytes` using
@@ -91,25 +85,54 @@ impl Decoder {
     ///
     /// Returns an error in case of malformed sequences in the `bytes`.
     pub fn decode_with_bom_removal<'b>(&self, bytes: &'b [u8]) -> Result<Cow<'b, str>> {
-        self.decode(self.remove_bom(bytes))
+        self.decode(remove_bom(bytes, self.encoding))
     }
-    /// Copied from [`Encoding::decode_with_bom_removal`]
-    #[inline]
-    fn remove_bom<'b>(&self, bytes: &'b [u8]) -> &'b [u8] {
-        if self.encoding == UTF_8 && bytes.starts_with(b"\xEF\xBB\xBF") {
-            return &bytes[3..];
-        }
-        if self.encoding == UTF_16LE && bytes.starts_with(b"\xFF\xFE") {
-            return &bytes[2..];
-        }
-        if self.encoding == UTF_16BE && bytes.starts_with(b"\xFE\xFF") {
-            return &bytes[2..];
-        }
+}
+
+/// Decodes the provided bytes using the specified encoding, ignoring the BOM
+/// if it is present in the `bytes`.
+///
+/// Returns an error in case of malformed sequences in the `bytes`.
+#[cfg(feature = "encoding")]
+pub fn decode<'b>(bytes: &'b [u8], encoding: &'static Encoding) -> Result<Cow<'b, str>> {
+    encoding
+        .decode_without_bom_handling_and_without_replacement(bytes)
+        .ok_or(Error::NonDecodable(None))
+}
 
-        bytes
+/// Decodes a slice with an unknown encoding, removing the BOM if it is present
+/// in the bytes.
+///
+/// Returns an error in case of malformed sequences in the `bytes`.
+#[cfg(feature = "encoding")]
+pub fn decode_with_bom_removal<'b>(bytes: &'b [u8]) -> Result<Cow<'b, str>> {
+    if let Some(encoding) = detect_encoding(bytes) {
+        let bytes = remove_bom(bytes, encoding);
+        decode(bytes, encoding)
+    } else {
+        decode(bytes, UTF_8)
+    }
+}
+
+#[cfg(feature = "encoding")]
+fn split_at_bom<'b>(bytes: &'b [u8], encoding: &'static Encoding) -> (&'b [u8], &'b [u8]) {
+    if encoding == UTF_8 && bytes.starts_with(&[0xEF, 0xBB, 0xBF]) {
+        bytes.split_at(3)
+    } else if encoding == UTF_16LE && bytes.starts_with(&[0xFF, 0xFE]) {
+        bytes.split_at(2)
+    } else if encoding == UTF_16BE && bytes.starts_with(&[0xFE, 0xFF]) {
+        bytes.split_at(2)
+    } else {
+        (&[], bytes)
     }
 }
 
+#[cfg(feature = "encoding")]
+fn remove_bom<'b>(bytes: &'b [u8], encoding: &'static Encoding) -> &'b [u8] {
+    let (_, bytes) = split_at_bom(bytes, encoding);
+    bytes
+}
+
 /// This implementation is required for tests of other parts of the library
 #[cfg(test)]
 #[cfg(feature = "serialize")]
@@ -158,7 +181,7 @@ impl Decoder {
 ///
 /// If encoding is detected, `Some` is returned, otherwise `None` is returned.
 #[cfg(feature = "encoding")]
-pub(crate) fn detect_encoding(bytes: &[u8]) -> Option<&'static Encoding> {
+pub fn detect_encoding(bytes: &[u8]) -> Option<&'static Encoding> {
     match bytes {
         // with BOM
         _ if bytes.starts_with(&[0xFE, 0xFF]) => Some(UTF_16BE),
@@ -173,3 +196,5 @@ pub(crate) fn detect_encoding(bytes: &[u8]) -> Option<&'static Encoding> {
         _ => None,
     }
 }
+
+// TODO: add tests from these functions