Struct XmlError 

pub struct XmlError {
    pub domain: ErrorDomain,
    pub level: ErrorLevel,
    pub code: ErrorCode,
    pub message: String,
    pub file: Option<String>,
    pub line: Option<u32>,
    pub column: Option<u32>,
    pub byte_offset: Option<u64>,
    pub xpath_code: Option<String>,
}

A structured XML processing error.

SupXML returns XmlError through Result<_, XmlError> instead of relying on a global error variable like libxml2 does. The domain, level, and code fields let callers react without parsing the human-readable message.

code is an ErrorCode enum whose discriminants match libxml2’s xmlParserErrors numeric values. Callers can match on the enum (idiomatic Rust); the [crates/compat] cdylib converts to libxml2’s xmlError::code: i32 via err.code as i32 — zero cost. See thoughts/c_abi_implementation_plan.md for the design.

Fields

domain: ErrorDomain

Which subsystem produced the error.

level: ErrorLevel

Severity.

code: ErrorCode

Specific error category (libxml2-compatible numeric code on the wire side). When in doubt, ErrorCode::InternalError.

message: String

Human-readable description of the problem.

file: Option<String>

Source file name, if available (e.g. for file-based parsing).

line: Option<u32>

1-based line number where the error occurred, if known.

column: Option<u32>

1-based column number where the error occurred, if known.

byte_offset: Option<u64>

0-based byte offset into the parser’s input buffer where the error occurred, if known.

Reported alongside line / column because the three answer different questions: line/col is what a human reads, byte offset is what tools (editors, LSP servers, dd if=… bs=1 skip=…) act on without re-walking the input. Byte offset also survives line-ending normalization (XML 1.0 § 2.11) and is the only useful coordinate for binary pipelines — gzipped XML, network captures, mmap’d files.

u64 (not usize) so that the ABI surface in crates/compat is stable across 32- and 64-bit targets and survives documents larger than 4 GB on the streaming reader.

Coordinate system

The offset is measured in the parser’s internal UTF-8 buffer, which is the same as the caller’s input byte slice in the common case (input was already UTF-8). If ParseOptions::auto_transcode converted UTF-16 or another encoding to UTF-8 first, the offset is relative to the post-transcode buffer and does not point at the user’s original bytes; the user-facing offset would require a transcoder back-map we don’t have today. Callers operating on already-UTF-8 input — which is the overwhelming majority of XML on the wire — can use this directly.

xpath_code: Option<String>

XPath/XQuery/XSLT error code as a local name in the standard err: namespace (http://www.w3.org/2005/xqt-errors) — e.g. "FOAR0001" for division by zero, "FORG0001" for an invalid cast. Distinct from code, which is the libxml2-numeric category; this is the spec-defined dynamic error a stylesheet’s xsl:catch / try/catch matches on and exposes through $err:code. None when the error has no specific spec code (it then projects as the generic err:FOER0000).

Implementations

impl XmlError

pub fn new( domain: ErrorDomain, level: ErrorLevel, message: impl Into<String>, ) -> Self

Construct an error with the catch-all ErrorCode::InternalError code. Add a more specific code via with_code when there’s a libxml2 numeric value that fits the case.

pub fn with_code(self, code: ErrorCode) -> Self

Attach a specific ErrorCode (libxml2-numeric). Builder-style; returns self for chaining with at.

pub fn with_xpath_code(self, code: impl Into<String>) -> Self

Attach the spec-defined XPath/XSLT error code (an err: local name such as "FOAR0001"). Builder-style; see xpath_code.

pub fn or_xpath_code(self, code: impl Into<String>) -> Self

Attach code only if no spec code is already present. Used at outer choke points (e.g. document() retrieval) that want to label an otherwise-uncoded error without overwriting a more specific code an inner layer already set.

pub fn at( self, file: impl Into<String>, line: u32, column: u32, byte_offset: u64, ) -> Self

Attach source position. All three coordinates are taken together because the scanner derives them from a single byte offset and any error that knows one knows all three; byte_offset is documented on Self::byte_offset.

Trait Implementations

impl Clone for XmlError

fn clone(&self) -> XmlError

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for XmlError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for XmlError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for XmlError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<XmlError> for SchemaCompileError

fn from(e: XmlError) -> Self

Converts to this type from the input type.