Remove BOM from first-emitted text event

Changelog.md

@@ -181,6 +181,7 @@
   You still can use re-exported definitions from a crate root
 
 - [#459]: Made the `Writer::write()` method non-public as writing random bytes to a document is not generally useful or desirable.
+- [#459]: BOM bytes are no longer emitted as `Event::Text`. To write a BOM, use `Writer::write_bom()`.
 
 ### New Tests
 

src/encoding.rs

@@ -155,7 +155,7 @@ fn split_at_bom<'b>(bytes: &'b [u8], encoding: &'static Encoding) -> (&'b [u8],
 }
 
 #[cfg(feature = "encoding")]
-fn remove_bom<'b>(bytes: &'b [u8], encoding: &'static Encoding) -> &'b [u8] {
+pub(crate) fn remove_bom<'b>(bytes: &'b [u8], encoding: &'static Encoding) -> &'b [u8] {
     let (_, bytes) = split_at_bom(bytes, encoding);
     bytes
 }

src/reader/mod.rs

@@ -1582,12 +1582,13 @@ mod test {
                 }
 
                 #[$test]
+                #[should_panic] // Failure is expected until read_until_open() is smart enough to skip over irrelevant text events.
                 $($async)? fn bom_at_start() {
                     let mut reader = Reader::from_str("\u{feff}");
 
                     assert_eq!(
                         reader.$read_event($buf) $(.$await)? .unwrap(),
-                        Event::Text(BytesText::from_escaped("\u{feff}").into())
+                        Event::Eof
                     );
                 }
 

src/reader/parser.rs

@@ -1,9 +1,7 @@
 #[cfg(feature = "encoding")]
 use encoding_rs::UTF_8;
 
-#[cfg(feature = "encoding")]
-use crate::encoding::detect_encoding;
-use crate::encoding::Decoder;
+use crate::encoding::{self, Decoder};
 use crate::errors::{Error, Result};
 use crate::events::{BytesCData, BytesDecl, BytesEnd, BytesStart, BytesText, Event};
 #[cfg(feature = "encoding")]
@@ -70,23 +68,31 @@ impl Parser {
     ///
     /// [`Text`]: Event::Text
     pub fn read_text<'b>(&mut self, bytes: &'b [u8], first: bool) -> Result<Event<'b>> {
-        #[cfg(feature = "encoding")]
-        if first && self.encoding.can_be_refined() {
-            if let Some(encoding) = detect_encoding(bytes) {
-                self.encoding = EncodingRef::BomDetected(encoding);
-            }
-        }
+        let mut content = bytes;
 
-        let content = if self.trim_text_end {
+        if self.trim_text_end {
             // Skip the ending '<'
             let len = bytes
                 .iter()
                 .rposition(|&b| !is_whitespace(b))
                 .map_or_else(|| bytes.len(), |p| p + 1);
-            &bytes[..len]
-        } else {
-            bytes
-        };
+            content = &bytes[..len];
+        }
+
+        if first {
+            #[cfg(feature = "encoding")]
+            if self.encoding.can_be_refined() {
+                if let Some(encoding) = encoding::detect_encoding(bytes) {
+                    self.encoding = EncodingRef::BomDetected(encoding);
+                    content = encoding::remove_bom(content, encoding);
+                }
+            }
+            #[cfg(not(feature = "encoding"))]
+            if bytes.starts_with(encoding::UTF8_BOM) {
+                content = &bytes[encoding::UTF8_BOM.len()..];
+            }
+        }
+
         Ok(Event::Text(BytesText::wrap(content, self.decoder())))
     }
 

tests/encodings.rs

@@ -1,4 +1,6 @@
+#[allow(unused_imports)]
 use quick_xml::events::Event;
+#[allow(unused_imports)]
 use quick_xml::Reader;
 
 #[cfg(feature = "encoding")]

tests/xmlrs_reader_tests.rs

@@ -51,6 +51,24 @@ fn html5() {
     );
 }
 
+#[test]
+fn bom_removed_from_initial_text() {
+    let expected = r#"
+        |Characters(asdf)
+        |StartElement(paired [attr1="value1", attr2="value2"])
+        |Characters(text)
+        |EndElement(paired)
+        |EndDocument
+    "#;
+
+    // BOM right up against the text
+    test(
+        "\u{FEFF}asdf<paired attr1=\"value1\" attr2=\"value2\">text</paired>",
+        expected,
+        true,
+    );
+}
+
 #[test]
 fn escaped_characters() {
     test(