Position tracking: make spans optional.

Better support manual creation of BytesStart by making position
information optional. Also replaces PartialEq derives with manual
implementations to ensure that position information is not taken into
account when comparing BytesStart objects - prevents observable and
possibly breaking changes to comparison behaviour.

Author: Themayu

src/events/mod.rs

@@ -59,23 +59,28 @@ use attributes::{Attribute, Attributes};
 /// The name can be accessed using the [`name`] or [`local_name`] methods.
 /// An iterator over the attributes is returned by the [`attributes`] method.
 ///
+/// If this was created from a reader, its location in the data can be accessed
+/// using the [`span`] method.
+///
 /// [`name`]: Self::name
 /// [`local_name`]: Self::local_name
 /// [`attributes`]: Self::attributes
-#[derive(Clone, Eq, PartialEq)]
+/// [`span`]: Self::span
+#[derive(Clone, Eq)]
 pub struct BytesStart<'a> {
     /// content of the element, before any utf8 conversion
     pub(crate) buf: Cow<'a, [u8]>,
     /// end of the element name, the name starts at that the start of `buf`
     pub(crate) name_len: usize,
-    /// the position of the element in the input, this does not reflect updates to the struct
-    pub(crate) span: Span,
+    /// the position of the element in the input, this does not reflect updates to the struct and
+    /// is not included in equality checking
+    pub(crate) span: Option<Span>,
 }
 
 impl<'a> BytesStart<'a> {
     /// Internal constructor, used by `Reader`. Supplies data in reader's encoding
     #[inline]
-    pub(crate) fn wrap(content: &'a [u8], name_len: usize, span: Span) -> Self {
+    pub(crate) fn wrap(content: &'a [u8], name_len: usize, span: Option<Span>) -> Self {
         BytesStart {
             buf: Cow::Borrowed(content),
             name_len,
@@ -93,7 +98,7 @@ impl<'a> BytesStart<'a> {
         let buf = str_cow_to_bytes(name);
         BytesStart {
             name_len: buf.len(),
-            span: 0..buf.len(),
+            span: None,
             buf,
         }
     }
@@ -110,7 +115,7 @@ impl<'a> BytesStart<'a> {
         let buf = str_cow_to_bytes(content);
 
         BytesStart {
-            span: 0..buf.len(),
+            span: None,
             buf,
             name_len,
         }
@@ -187,14 +192,15 @@ impl<'a> BytesStart<'a> {
         self.name().into()
     }
 
-    /// Gets the range of bytes this element spans in the input stream.
+    /// Gets the range of bytes this element spans in the input stream, if it
+    /// came from one.
     ///
-    /// This does not reflect updates to the struct. I.e. if [`set_name`] is called, this will not
-    /// update the span, as the underlying source is not altered by this operation.
+    /// This does not reflect updates to the struct. For example, if [`set_name`] is called, it
+    /// not update the span, as the underlying source is not altered by the operation.
     ///
     /// [`set_name`]: Self::set_name
     #[inline]
-    pub fn span(&self) -> Span {
+    pub fn span(&self) -> Option<Span> {
         self.span.clone()
     }
 
@@ -307,6 +313,14 @@ impl<'a> Deref for BytesStart<'a> {
     }
 }
 
+// Manually implemented to prevent equality changes between items returned from reader versus
+// items created via public API.
+impl<'a> PartialEq for BytesStart<'a> {
+    fn eq(&self, other: &Self) -> bool {
+        self.buf == other.buf && self.name_len == other.name_len
+    }
+}
+
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 
 /// An XML declaration (`Event::Decl`).

src/reader/mod.rs

@@ -858,6 +858,17 @@ pub(crate) fn is_whitespace(b: u8) -> bool {
     }
 }
 
+/// A function to resolve the span of an XML element from its contents and its opening position.
+#[inline]
+pub(crate) fn resolve_span(buf: &[u8], open_pos: usize) -> Span {
+    const L_BRACKET: usize = '<'.len_utf8();
+    const R_BRACKET: usize = '>'.len_utf8();
+
+    let close_pos = open_pos + L_BRACKET + buf.len() + R_BRACKET;
+
+    open_pos..close_pos
+}
+
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 
 #[cfg(test)]

src/reader/parser.rs

@@ -6,7 +6,7 @@ use crate::errors::{Error, Result};
 use crate::events::{BytesCData, BytesDecl, BytesEnd, BytesStart, BytesText, Event};
 #[cfg(feature = "encoding")]
 use crate::reader::EncodingRef;
-use crate::reader::{is_whitespace, BangType, ParseState};
+use crate::reader::{is_whitespace, resolve_span, BangType, ParseState};
 
 use memchr;
 
@@ -180,13 +180,13 @@ impl Parser {
 
     /// reads `BytesElement` starting with a `?`,
     /// return `Decl` or `PI` event
-    pub fn read_question_mark<'b>(&mut self, buf: &'b [u8], position: usize) -> Result<Event<'b>> {
+    pub fn read_question_mark<'b>(&mut self, buf: &'b [u8], open_pos: usize) -> Result<Event<'b>> {
         let len = buf.len();
-        let end = position + len;
+        let span = resolve_span(buf, open_pos);
         if len > 2 && buf[len - 1] == b'?' {
             if len > 5 && &buf[1..4] == b"xml" && is_whitespace(buf[4]) {
                 let event =
-                    BytesDecl::from_start(BytesStart::wrap(&buf[1..len - 1], 3, position..end));
+                    BytesDecl::from_start(BytesStart::wrap(&buf[1..len - 1], 3, Some(span)));
 
                 // Try getting encoding from the declaration event
                 #[cfg(feature = "encoding")]
@@ -208,10 +208,10 @@ impl Parser {
 
     /// reads `BytesElement` starting with any character except `/`, `!` or ``?`
     /// return `Start` or `Empty` event
-    pub fn read_start<'b>(&mut self, buf: &'b [u8], position: usize) -> Result<Event<'b>> {
+    pub fn read_start<'b>(&mut self, buf: &'b [u8], open_pos: usize) -> Result<Event<'b>> {
         // TODO: do this directly when reading bufreader ...
         let len = buf.len();
-        let end = position + len;
+        let span = resolve_span(buf, open_pos);
         let name_end = buf.iter().position(|&b| is_whitespace(b)).unwrap_or(len);
         if let Some(&b'/') = buf.last() {
             let end = if name_end < len { name_end } else { len - 1 };
@@ -222,13 +222,13 @@ impl Parser {
                 Ok(Event::Start(BytesStart::wrap(
                     &buf[..len - 1],
                     end,
-                    position..end,
+                    Some(span),
                 )))
             } else {
                 Ok(Event::Empty(BytesStart::wrap(
                     &buf[..len - 1],
                     end,
-                    position..end,
+                    Some(span),
                 )))
             }
         } else {
@@ -237,7 +237,7 @@ impl Parser {
             // enabled, we should have that information
             self.opened_starts.push(self.opened_buffer.len());
             self.opened_buffer.extend(&buf[..name_end]);
-            Ok(Event::Start(BytesStart::wrap(buf, name_end, position..end)))
+            Ok(Event::Start(BytesStart::wrap(buf, name_end, Some(span))))
         }
     }