Struct XmlReader 

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

Streaming XML reader with string-typed events. Thin wrapper around XmlBytesReader — the engine runs in raw bytes and we re-label each event’s payload as Cow<'src, str> at the boundary. The conversion is a no-op: bytes are valid UTF-8 by the Scanner’s construction-time invariant.

Implementations

impl<'src> XmlReader<'src>

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

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<Self>

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]) -> Self

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

Safety

The bytes pointed to by src must be valid UTF-8 for the lifetime of the returned reader and for any Event it emits. Violating this invariant is undefined behaviour — Event payloads are &str slices into the input, produced via std::str::from_utf8_unchecked.

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

Destructive in-place reader. The reader is permitted to mutate src during parsing — used by crate::parser::parse_bytes_in_place.

Safety

src must be valid UTF-8. Caller transfers exclusive write access to src for the reader’s lifetime.

pub fn with_options(self, opts: ParseOptions) -> Self

Override the ParseOptions that the reader was constructed with. Use this to lower limits or skip checks for trusted input.

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

XML declaration fields parsed from the prolog. Returns None before the first event has been read, or when the document has no <?xml ... ?> declaration. See XmlBytesReader::xml_decl for the underlying definition.

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

Non-fatal errors logged while parsing with ParseOptions::recovery_mode = true. Empty in strict mode (errors are returned via Err from next/next_into instead). See XmlBytesReader::recovered_errors for full semantics.

pub fn src_offset(&self) -> usize

Current byte offset into the original source. Use with line_col (or src_bytes

• crate::scanner::compute_line_col) to attribute diagnostics to a source position.

For start-of-element offsets specifically, prefer last_start_offset: it returns the < of the most recent StartElement, whereas src_offset will already be past the start tag’s closing > by the time you read it.

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

Source byte offset of the < of the most recently emitted StartElement. None before the first start tag, or when the start tag was read from inside an entity-replacement stream. Pairs with line_col_at to anchor diagnostics at the right source position.

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

The original source bytes the reader is parsing. Pairs with src_offset for translating byte positions into line/column.

pub fn line_col(&self) -> (u32, u32)

Translate the current reader position into a 1-based (line, column) pair. Lazy: scans the prefix from byte 0 to the current offset once per call (cost ~O(offset)). Cheap enough for error paths; not for tight loops.

pub fn line_col_at(&self, offset: usize) -> (u32, u32)

Translate an arbitrary byte offset (typically captured earlier via src_offset) into 1-based (line, column). Same cost model as line_col.

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

Read the next event with lazy attribute access.

Returns an Event borrowing the reader for its lifetime. Start tag events carry an Attrs 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<Attr<'src>>, ) -> Result<EventInto<'src>>

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.