Struct XmlBytesReader 

pub struct XmlBytesReader<'src> { /* private fields */ }

Implementations

impl<'src> XmlBytesReader<'src>

pub fn from_str(input: &'src str) -> XmlBytesReader<'src>

Create a reader from a string slice. The string must remain alive for the lifetime of the reader and all events it produces.

pub fn from_bytes(src: &'src [u8]) -> Result<XmlBytesReader<'src>, XmlError>

Create a reader from a byte slice. Returns an error if the bytes are not valid UTF-8.

pub unsafe fn from_bytes_unchecked(src: &'src [u8]) -> XmlBytesReader<'src>

Create a reader from a byte slice, skipping the upfront UTF-8 validation that from_bytes performs.

Why this is faster

from_bytes runs a single O(n) std::str::from_utf8 over the entire input before any events are produced. On large documents that pass is measurable. This entry point removes it.

Just-in-time validation by the caller

This constructor does not validate later either — the safety contract is that the bytes already are UTF-8 when you call it. The contract lets the caller validate however and whenever they want, including not at all when the encoding is already guaranteed by the upstream source. Common patterns:

Already a &str — UTF-8 is guaranteed by Rust’s type system:

let xml: &str = "<r/>";
let reader = unsafe { XmlBytesReader::from_bytes_unchecked(xml.as_bytes()) };

Validate up front yourself — useful when you want a custom error type or want to avoid duplicate work later:

let bytes: &[u8] = b"<r/>";
std::str::from_utf8(bytes).expect("input must be UTF-8");
let reader = unsafe { XmlBytesReader::from_bytes_unchecked(bytes) };

Validate each chunk as it streams in — the per-chunk passes total the same O(n) work as one big pass, but you can interleave validation with I/O instead of paying it all at the end:

let mut buf = Vec::new();
while let Some(chunk) = next_chunk() {
    std::str::from_utf8(&chunk).expect("chunk must be UTF-8");
    buf.extend_from_slice(&chunk);
}
let reader = unsafe { XmlBytesReader::from_bytes_unchecked(&buf) };

In all of these the upfront pass inside from_bytes is duplicated work, and this constructor lets you elide it.

Safety

src must be valid UTF-8. Passing non-UTF-8 bytes is undefined behaviour — the reader hands out &str slices into the input that the rest of the program will treat as UTF-8.

pub unsafe fn from_bytes_in_place_unchecked( src: &'src mut [u8], ) -> XmlBytesReader<'src>

Construct a reader in destructive in-place mode. The resulting reader is permitted to mutate src during parsing (entity decoding, normalization) — the caller transfers exclusive write access for the reader’s lifetime. Use this alongside parse_bytes_in_place in crate::parser.

Safety

src must be valid UTF-8. Same contract as from_bytes_unchecked.

pub fn with_options(self, opts: ParseOptions) -> XmlBytesReader<'src>

pub fn xml_decl(&self) -> Option<&XmlDeclInfo>

XML declaration fields parsed from the prolog. Returns None before the first event has been read, or if the document has no <?xml ... ?> declaration. Calling this after at least one successful next() (or read_event) call is guaranteed to reflect the document’s actual declaration state.

pub fn dtd(&self) -> &Dtd

Borrow the DTD declarations captured from the internal subset.

Empty when the document had no <!DOCTYPE … [ … ]>, or had a doctype with no <!ELEMENT>/<!ATTLIST> declarations. The returned crate::dtd::Dtd feeds [crate::dtd::validate].

pub fn src_bytes(&self) -> &'src [u8]

The original source bytes the reader is parsing. Used by callers that need byte-offset → line/column translation for diagnostics or for stamping Node::line at element creation.

pub fn src_offset(&self) -> usize

Current byte offset into the original source. Pairs with src_bytes and crate::scanner::compute_line_col for on-demand line/column translation by higher-level validators (XSD, custom checkers). Inside an entity-replacement stream this returns the position of the entity reference in the user-visible document — see [crate::scanner::Scanner::src_offset].

pub fn last_start_offset(&self) -> Option<usize>

Source byte offset of the most recently emitted StartElement’s < character. None before the first start tag, or for start tags read from inside an entity-replacement stream (where source offsets are meaningless).

Validators snapshot this immediately after next() / next_into() returns a StartElement to anchor downstream diagnostics at the right source position — src_offset() by that point has advanced past the start tag’s closing >, which puts errors on the wrong line for multi-line start tags or root elements preceded by whitespace.

pub fn take_dtd(&mut self) -> Dtd

Consume self’s DTD, leaving an empty one behind. Used by parser.rs::parse_bytes to hand ownership over to the resulting [Document].

pub fn recovered_errors(&self) -> &[XmlError]

Errors logged while ParseOptions::recovery_mode was enabled. Empty in strict mode (the default) — errors there surface as Err from next() and abort the parse.

In recover mode this list grows as the parser encounters non-fatal well-formedness violations and applies heuristic repair to keep going. Inspect after parsing finishes to learn what the document had wrong; or poll periodically during streaming.

Order is the order errors were encountered. Each entry’s level is ErrorLevel::Error (recoverable) or ErrorLevel::Warning (informational). Fatal errors are never logged here — they always come back through Err.

pub fn next(&mut self) -> Result<BytesEvent<'_, 'src>, XmlError>

Read the next event with lazy attribute access.

Returns an BytesEvent borrowing the reader for its lifetime. Start tag events carry an BytesAttrs iterator — iterate it to read attributes, ignore it to skip attribute parsing entirely.

For an eager API that fills a caller-owned buffer with parsed attributes, see next_into.

pub fn next_into( &mut self, buf: &mut Vec<BytesAttr<'src>>, ) -> Result<BytesEventInto<'src>, XmlError>

Read the next event, eagerly parsing start-tag attributes into buf.

buf is cleared on every call. For StartElement events buf is filled with the element’s attributes in source order; for other events buf is left empty. Pass the same Vec across many calls to reuse its allocation.

For lazy attribute access (zero work when you never read attrs), see next.