quick-xml

https://github.com/tafia/quick-xml
Admin
quick-xml is a high-performance XML pull reader and writer library for Rust that provides nearly...
Tokens:161,883
Snippets:1,137
Trust Score:7.5
License:MIT
Update:4 hours ago
Show doc for...
Tokens:
Raw
### Run quick-xml examples

Source: https://github.com/tafia/quick-xml/blob/master/examples/README.md

Commands to run the examples in the quick-xml repository. The serde_roundtrip example requires the 'serialize' feature, and the read_utf16 example requires the 'encoding' feature.

```console
cargo run --example getting_started
cargo run --example serde_roundtrip --features serialize
cargo run --example read_utf16      --features encoding
```

--------------------------------

### with

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Runs a closure as if the given start event's bindings were pushed, then pops them.

```APIDOC
## `with`

### Description
Runs a closure as if the given start event's bindings were pushed, then pops them.

### Method
`pub fn with<F, R>(&mut self, start: &BytesStart, mut action: F) -> Result<R, NamespaceError> where F: FnMut(&Self) -> R`

### Parameters
- `start` (&BytesStart) - Required - The start event with namespace declarations.
- `action` (F) - Required - The closure to execute.

### Returns
`Result<R, NamespaceError>` - The result of the closure, or an error.
```

--------------------------------

### read_text usage example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/reader.md

Example usage of `read_text` with `Reader::from_str`. Configures `trim_text(true)`, creates start tag, reads event, then reads text content. Outputs `"<p>Hello</p>"`.

```rust
use quick_xml::events::BytesStart;
use quick_xml::reader::Reader;

let mut reader = Reader::from_str("<html><p>Hello</p></html>");
reader.config_mut().trim_text(true);
let start = BytesStart::new("html");
let end = start.to_end().into_owned();

reader.read_event().unwrap();             // <html>
let text = reader.read_text(end.name()).unwrap();
println!("{}", text.into_inner());        // "<p>Hello</p>"
```

--------------------------------

### NamespaceResolver usage example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

This example demonstrates how to create a default NamespaceResolver, add a namespace binding, and resolve an element. It uses the quick_xml::name module and returns a Result with Ok(()) at the end.

```rust
use quick_xml::name::{Namespace, NamespaceResolver, PrefixDeclaration, QName, ResolveResult};

let mut resolver = NamespaceResolver::default();
resolver.add(PrefixDeclaration::Named("ns"), Namespace("my:namespace"))?;

assert_eq!(
    resolver.resolve_element(QName("ns:name")).0,
    ResolveResult::Bound(Namespace("my:namespace")),
);
# quick_xml::Result::Ok(())
```

--------------------------------

### push

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Opens a new scope and registers the `xmlns` declarations from the given start event.

```APIDOC
## `push`

### Description
Opens a new scope and registers the `xmlns` declarations from the given start event.

### Method
`pub fn push(&mut self, start: &BytesStart) -> Result<(), NamespaceError>`

### Parameters
- `start` (&BytesStart) - Required - The start event containing namespace declarations.

### Returns
`Result<(), NamespaceError>` - Ok if successful, Err otherwise.
```

--------------------------------

### create_element usage example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/writer.md

Shows how to create elements with attributes and text content, and nested elements using write_inner_content.

```rust
let mut writer = Writer::new(Cursor::new(Vec::new()));

writer.create_element("tag")
    .with_attribute(("attr1", "value1"))
    .write_text_content(BytesText::new("with some text inside"))?;

writer.create_element("tag")
    .write_inner_content(|writer| {
        writer.create_element("fruit")
            .with_attribute(("quantity", "1"))
            .write_text_content(BytesText::new("apple"))?;
        Ok(())
    })?;
```

--------------------------------

### Matching on Event variants

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Shows how to match on Event variants from a reader. The example prints the element name for Start events, the text content for Text events, and breaks on Eof.

```rust
match reader.read_event().unwrap() {
    Event::Start(e) => println!("start {}", e.name()),
    Event::Text(e) => println!("text {}", e.xml_content(XmlVersion::Implicit1_0)),
    Event::Eof => break,
    _ => {}
}
```

--------------------------------

### detect_encoding usage example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/encoding.md

Shows how to call `detect_encoding` with a UTF-8 BOM and check the BOM length. The example asserts that the BOM length is 3.

```rust
use quick_xml::encoding::detect_encoding;

assert_eq!(detect_encoding(&[0xEF, 0xBB, 0xBF, b'<']).map(|e| e.bom_len()), Some(3));
```

--------------------------------

### Serializer usage example with with_root and indent

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/se.md

Shows constructing a Serializer with an explicit root tag, enabling indentation and text format, then serializing a struct. The output is asserted to match the expected XML.

```rust
use quick_xml::se::Serializer;
use serde::Serialize;

#[derive(Serialize)]
struct Response { message: &'static str }

let mut output = String::new();
let mut serializer = Serializer::with_root(&mut output, Some("response")).unwrap();
serializer.indent(' ', 4).text_format(quick_xml::se::TextFormat::Text);

Response { message: "Success" }.serialize(serializer).unwrap();
assert_eq!(output, "<response>\n    <message>Success</message>\n</response>");
```

--------------------------------

### BytesPI::content

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Returns everything after the target (starts with a space).

```APIDOC
## `BytesPI::content`

### Description
Returns everything after the target (starts with a space).

### Method
`content`

### Signature
`pub fn content(&self) -> &str`

### Returns
- `&str` - The content after the target.

```

--------------------------------

### Using XmlVersion with xml_content

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/lib.md

Example of using `XmlVersion::Implicit1_0` with `BytesText::xml_content` to normalize text. Requires `trim_text(true)` to observe the effect.

```rust
use quick_xml::events::Event;
use quick_xml::reader::Reader;
use quick_xml::XmlVersion;

let mut reader = Reader::from_str("<a>text \r\n</a>");
reader.config_mut().trim_text(true);
match reader.read_event().unwrap() {
    Event::Text(e) => {
        assert_eq!(e.xml_content(XmlVersion::Implicit1_0).as_ref(), "text ");
    }
    _ => {}
}
```

--------------------------------

### Read XML with quick-xml Reader

Source: https://github.com/tafia/quick-xml/blob/master/README.md

Shows how to read an XML document with `Reader::from_str`, `read_event_into`, and `config_mut().trim_text(true)`. It iterates over events, handles `Start`, `Text`, and `Eof`, and uses `xml_content(XmlVersion::Implicit1_0)` to unescape text. The buffer is cleared each loop to keep memory usage low.

```rust
use quick_xml::events::Event;
use quick_xml::reader::Reader;
use quick_xml::XmlVersion;

let xml = r#"<tag1 att1 = "test">
                <tag2><!--Test comment-->Test</tag2>
                <tag2>Test 2</tag2>
             </tag1>"#;
let mut reader = Reader::from_str(xml);
reader.config_mut().trim_text(true);

let mut count = 0;
let mut txt = Vec::new();
let mut buf = Vec::new();

// Names and text are `&str`, not bytes: quick-xml validates that input is UTF-8.
// The `Reader` does not implement `Iterator` because it outputs borrowed data (`Cow`s)
loop {
    // NOTE: this is the generic case when we don't know about the input BufRead.
    // when the input is a &str or a &[u8], we don't actually need to use another
    // buffer, we could directly call `reader.read_event()`
    match reader.read_event_into(&mut buf) {
        Err(e) => panic!("Error at position {}: {:?}", reader.error_position(), e),
        // exits the loop when reaching end of file
        Ok(Event::Eof) => break,

        Ok(Event::Start(e)) => {
            match e.name().as_ref() {
                "tag1" => println!("attributes values: {:?}",
                                    e.attributes().map(|a| a.unwrap().value)
                                    .collect::<Vec<_>>()),
                "tag2" => count += 1,
                _ => (),
            }
        }
        // `xml_content` unescapes entities; the `XmlVersion` selects the
        // normalization rules (1.0 vs 1.1). Most documents are 1.0.
        Ok(Event::Text(e)) => txt.push(e.xml_content(XmlVersion::Implicit1_0).into_owned()),

        // There are several other `Event`s we do not consider here
        _ => (),
    }
    // if we don't keep a borrow elsewhere, we can clear the buffer to keep memory usage low
    buf.clear();
}
```

--------------------------------

### write_serializable usage example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/writer.md

Shows serializing a struct with serde and writing it inside a root element using write_serializable.

```rust
#[derive(serde::Serialize)]
struct MyData { question: String, answer: u32 }

let mut buffer = Vec::new();
let mut writer = Writer::new_with_indent(&mut buffer, b' ', 4);

let start = BytesStart::new("root");
let end = start.to_end();
writer.write_event(Event::Start(start.clone()))?;
writer.write_serializable("my_data", &data)?;
writer.write_event(Event::End(end))?;
```

--------------------------------

### Async read_event_into_async usage example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/reader.md

Example usage of `read_event_into_async` with `Reader::from_reader`. Loops reading events until `Event::Eof`, clearing buffer each iteration. Requires `async-tokio` feature.

```rust
# #[cfg(feature = "async-tokio")]
# async fn example(stream: impl tokio::io::AsyncBufRead + Unpin) -> quick_xml::Result<()> {
use quick_xml::events::Event;
use quick_xml::reader::Reader;

let mut reader = Reader::from_reader(stream);
let mut buf = Vec::new();
loop {
    match reader.read_event_into_async(&mut buf).await? {
        Event::Eof => break,
        _ => {}
    }
    buf.clear();
}
# Ok(())
# }
```

--------------------------------

### DecodingReader usage example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/encoding.md

Shows how to decode an XML declared as UTF-16 using DecodingReader with Reader. Reads events until EOF, printing errors. Input is in-memory bytes.

```rust
use quick_xml::encoding::DecodingReader;
use quick_xml::events::Event;
use quick_xml::reader::Reader;

// decode an XML declared as UTF-16 (input in memory for the example)
let bytes = b"\xff\xfe...utf-16 bytes...";
let mut reader = Reader::from_reader(DecodingReader::new(&bytes[..]));
let mut buf = Vec::new();
loop {
    match reader.read_event_into(&mut buf) {
        Ok(Event::Eof) => break,
        Ok(_) => {}
        Err(e) => eprintln!("error: {e}"),
    }
    buf.clear();
}
```

--------------------------------

### XML example for skipping text before map-like structures

Source: https://github.com/tafia/quick-xml/blob/master/Changelog.md

Shown in the bug fix for issue #523, this XML illustrates unwanted text preceding a struct element, which was previously skipped incorrectly by the serde deserializer.

```xml
unwanted text<struct>...</struct>
```

--------------------------------

### read_resolved_event_into

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/ns-reader.md

Reads the next XML event and resolves the namespace of Start, Empty, and End events. All other events get ResolveResult::Unbound.

```APIDOC
## read_resolved_event_into

### Description
Reads the next XML event and resolves the namespace of Start, Empty, and End events. All other events get ResolveResult::Unbound.

### Method
read_resolved_event_into

### Signature
pub fn read_resolved_event_into<'b>(&mut self, buf: &'b mut Vec<u8>) -> Result<(ResolveResult<'_>, Event<'b>)>

### Parameters
- **buf** (`&mut Vec<u8>`) - Required - Buffer to read the event into.

### Returns
- `Result<(ResolveResult<'_>, Event<'b>)>` - The resolve result and the next XML event.
```

--------------------------------

### Write XML with quick-xml Writer

Source: https://github.com/tafia/quick-xml/blob/master/README.md

Shows how to write XML with `Writer` and `BytesStart`/`BytesEnd`. It reads an existing element, copies its attributes, adds a new attribute, and writes a renamed element. The final output is compared to an expected string.

```rust
use quick_xml::events::{Event, BytesEnd, BytesStart};
use quick_xml::reader::Reader;
use quick_xml::writer::Writer;
use std::io::Cursor;

let xml = r#"<this_tag k1="v1" k2="v2"><child>text</child></this_tag>"#;
let mut reader = Reader::from_str(xml);
reader.config_mut().trim_text(true);
let mut writer = Writer::new(Cursor::new(Vec::new()));
loop {
    match reader.read_event() {
        Ok(Event::Start(e)) if e.name().as_ref() == "this_tag" => {

            // creates a new element ... alternatively we could reuse `e` by calling
            // `e.into_owned()`
            let mut elem = BytesStart::new("my_elem");

            // collect existing attributes
            elem.extend_attributes(e.attributes().map(|attr| attr.unwrap()));

            // copy existing attributes, adds a new my-key="some value" attribute
            elem.push_attribute(("my-key", "some value"));

            // writes the event to the writer
            assert!(writer.write_event(Event::Start(elem)).is_ok());
        },
        Ok(Event::End(e)) if e.name().as_ref() == "this_tag" => {
            assert!(writer.write_event(Event::End(BytesEnd::new("my_elem"))).is_ok());
        },
        Ok(Event::Eof) => break,
        // we can either move or borrow the event to write, depending on your use-case
        Ok(e) => assert!(writer.write_event(e).is_ok()),
        Err(e) => panic!("Error at position {}: {:?}", reader.error_position(), e),
    }
}

let result = writer.into_inner().into_inner();
let expected = r#"<my_elem k1="v1" k2="v2" my-key="some value"><child>text</child></my_elem>"#;
assert_eq!(result, expected.as_bytes());
```

--------------------------------

### Run benchmark with cargo bench

Source: https://github.com/tafia/quick-xml/blob/master/compare/README.md

Commands to run the benchmark from the quick_xml checkout directory. The commands navigate to the compare directory and execute cargo bench.

```shell
cd compare
cargo bench
```

--------------------------------

### Serde: Parsing tag value with $text

Source: https://github.com/tafia/quick-xml/blob/master/README.md

Use the special `$text` field name in a serde struct to capture the text content between XML tags. This example demonstrates parsing `<foo abc="xyz">bar</foo>` to get `body` as `"bar"`. The `@abc` rename maps the attribute.

```rust
struct Foo {
    #[serde(rename = "@abc")]
    pub abc: String,
    #[serde(rename = "$text")]
    pub body: String,
}
```

--------------------------------

### Performance benchmarks for quick-xml and xml-rs

Source: https://github.com/tafia/quick-xml/blob/master/README.md

Benchmark results comparing quick-xml with xml-rs and serde-xml-rs. Shows execution times in nanoseconds per iteration. Not actual code, but benchmark output for performance analysis.

```text
// quick-xml benches
test bench_quick_xml            ... bench:     198,866 ns/iter (+/- 9,663)
test bench_quick_xml_escaped    ... bench:     282,740 ns/iter (+/- 61,625)
test bench_quick_xml_namespaced ... bench:     389,977 ns/iter (+/- 32,045)

// same bench with xml-rs
test bench_xml_rs               ... bench:  14,468,930 ns/iter (+/- 321,171)

// serde-xml-rs vs serialize feature
test bench_serde_quick_xml      ... bench:   1,181,198 ns/iter (+/- 138,290)
test bench_serde_xml_rs         ... bench:  15,039,564 ns/iter (+/- 783,485)
```

--------------------------------

### as_bool usage example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events-attributes.md

Example showing `as_bool` returning `Some(true)` for the value `"true"`.

```rust
let attr = Attribute::from(("checked", "true"));
assert_eq!(attr.as_bool(), Some(true));
```

--------------------------------

### Release checklist commands

Source: https://github.com/tafia/quick-xml/blob/master/Changelog.md

Commands for generating documentation and packaging the crate during release. Requires nightly Rust and the docsrs cfg.

```shell
$env:RUSTDOCFLAGS="--cfg docsrs"; cargo +nightly doc --all-features
```

```shell
cargo package
```

```shell
cargo publish
```

--------------------------------

### Serializer options (setters)

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/configuration.md

Configuration methods for the Serde serializer to control XML output formatting. All setters return &mut Self and have defaults as shown.

```APIDOC
## [GET] Serializer options (setters)

### Description
Configuration methods for the Serde serializer to control XML output formatting. All setters return &mut Self and have defaults as shown.

### Method
GET

### Endpoint
Serializer options (setters)

### Parameters
#### Configuration Methods
- **empty_element_handling** (EmptyElementHandling) - Optional - Default: `SelfClosed`. Controls `<e/>` vs `<e />` vs `<e></e>`.
- **expand_empty_elements** (bool) - Optional - Default: `false`. Legacy shortcut: `true` → `Expanded`.
- **text_format** (TextFormat) - Optional - Default: `Text`. Escaped text vs `<![CDATA[…]]>` for text content.
- **indent** ((indent_char: char, indent_size: usize)) - Optional - Default: none. Pretty-printing indent.
- **set_quote_level** (QuoteLevel) - Optional - Default: `Minimal` (documented; constructors initialize internal state with `Partial`). Escaping: `Full` (`<>&"'`), `Partial` (`<>&`), `Minimal` (`<&`).

### Response
#### Success Response (200)
- **&mut Self** - The serializer with updated configuration.

#### Response Example
```json
{
  "serializer": "&mut Self"
}
```
```

--------------------------------

### BytesDecl::from_start

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Creates a `BytesDecl` from a `BytesStart`.

```APIDOC
## `BytesDecl::from_start`

### Description
Creates a `BytesDecl` from a `BytesStart`.

### Method
`from_start`

### Signature
`pub const fn from_start(start: BytesStart<'i>) -> Self`

### Parameters
- `start` (`BytesStart<'i>`) - Required - The start element.

### Returns
- `Self` - A new `BytesDecl` instance.

```

--------------------------------

### new_line

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/writer.md

Pushes a newline inside the start tag between attribute groups. No-op when the Writer has no indentation.

```APIDOC
## new_line

### Description
Pushes a newline inside the start tag between attribute groups. No-op when the Writer has no indentation.

### Method
Builder method

### Signature
`pub fn new_line(mut self) -> Self`

### Returns
`Self` - The updated `ElementWriter`.
```

--------------------------------

### new

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Creates a new BytesStart from a tag name. The name must be a valid XML name.

```APIDOC
## new

### Description
Creates a new BytesStart from a tag name. The name must be a valid XML name.

### Method
Constructor

### Signature
`pub fn new<C: Into<Cow<'i, str>>>(name: C) -> Self`

### Parameters
- **name** (C) - Required - The tag name, must be a valid XML name.

### Returns
- **Self** - A new BytesStart instance.
```

--------------------------------

### with_attributes

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Consumes the BytesStart and adds attributes to it.

```APIDOC
## with_attributes

### Description
Consumes the BytesStart and adds attributes to it.

### Method
Method

### Signature
`pub fn with_attributes<'a, I>(mut self, attributes: I) -> Self where I: IntoIterator, I::Item: Into<Attribute<'a>>`

### Parameters
- **attributes** (I) - Required - An iterator of attributes to add.

### Returns
- **Self** - The BytesStart with attributes added.
```

--------------------------------

### Reader::from_file constructor

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/reader.md

Opens the file and wraps it in a BufReader.

```rust
pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self>
```

--------------------------------

### resolver_mut

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/ns-reader.md

Returns a mutable reference to the namespace resolver. This allows modifying the resolver, for example to set maximum namespace bindings.

```APIDOC
## resolver_mut

### Description
Returns a mutable reference to the namespace resolver. This allows modifying the resolver, for example to set maximum namespace bindings.

### Method
Accessor

### Signature
`pub fn resolver_mut(&mut self) -> &mut NamespaceResolver`

### Parameters
None

### Returns
- **&mut NamespaceResolver** - A mutable reference to the namespace resolver.

### Source
`ns_reader.rs:131`
```

--------------------------------

### from_content

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Creates a BytesStart from raw content (name + attributes) with a given name length. This is unchecked and does not validate the content.

```APIDOC
## from_content

### Description
Creates a BytesStart from raw content (name + attributes) with a given name length. This is unchecked and does not validate the content.

### Method
Constructor

### Signature
`pub fn from_content<C: Into<Cow<'i, str>>>(content: C, name_len: usize) -> Self`

### Parameters
- **content** (C) - Required - Raw content including name and attributes.
- **name_len** (usize) - Required - Length of the tag name.

### Returns
- **Self** - A new BytesStart instance.
```

--------------------------------

### Reader::error_position

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/reader.md

Returns the position of the last error, pointing at the start of the offending markup. Returns 0 if no error has occurred.

```APIDOC
## Reader::error_position

### Description
Returns the position of the last error (points at the start of the offending markup); always `<= buffer_position()`, `0` if no error yet.

### Method
Accessor

### Signature
```rust
pub const fn error_position(&self) -> u64
```

### Parameters
None

### Returns
- `u64` - The position of the last error, or 0 if no error.
```

--------------------------------

### to_owned

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Creates an owned clone of the BytesStart with a 'static lifetime.

```APIDOC
## to_owned

### Description
Creates an owned clone of the BytesStart with a 'static lifetime.

### Method
Method

### Signature
`pub fn to_owned(&self) -> BytesStart<'static>`

### Parameters
None

### Returns
- **BytesStart<'static>** - An owned clone.
```

--------------------------------

### BytesCData usage example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Creates a CDATA event and writes it, then splits content containing ']]>' into multiple CDATA sections using escaped().

```rust
let cdata = BytesCData::new("Some <b>raw</b> text");
writer.write_event(Event::CData(cdata))?;

// content containing the closing sequence must be split:
for section in BytesCData::escaped("a]]>b") {
    writer.write_event(Event::CData(section))?;
}
```

--------------------------------

### read_text

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/reader.md

Reads the content between start and end tags, including any markup, as-is (no unescaping). Equivalent to `read_to_end(end)` then slicing the input.

```APIDOC
## read_text

### Description
Reads content between start and end tags *including any markup*, as-is (no unescaping). Equivalent to `read_to_end(end)` then slicing the input.

### Method
Rust function

### Signature
```rust
pub fn read_text(&mut self, end: QName) -> Result<BytesText<'a>>
```

### Parameters
- `end` (QName) - Required - The name of the end tag.

### Returns
- `Result<BytesText<'a>>` - The text content, or an error.

### Example
```rust
use quick_xml::events::BytesStart;
use quick_xml::reader::Reader;

let mut reader = Reader::from_str("<html><p>Hello</p></html>");
reader.config_mut().trim_text(true);
let start = BytesStart::new("html");
let end = start.to_end().into_owned();

reader.read_event().unwrap();             // <html>
let text = reader.read_text(end.name()).unwrap();
println!("{}", text.into_inner());        // "<p>Hello</p>"
```
```

--------------------------------

### borrow

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Borrows the BytesStart with a shorter lifetime.

```APIDOC
## borrow

### Description
Borrows the BytesStart with a shorter lifetime.

### Method
Method

### Signature
`pub fn borrow(&self) -> BytesStart<'_>`

### Parameters
None

### Returns
- **BytesStart<'_>** - A borrowed BytesStart.
```

--------------------------------

### Deserialize from a reader with from_reader

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/de.md

Example of using `from_reader` with a `std::io::Cursor` to deserialize XML from bytes. The XML is parsed into a `Root` type.

```rust
let xml = r#"<Root><answer>42</answer></Root>"#;
let val: Root = from_reader(std::io::Cursor::new(xml.as_bytes())).unwrap();
```

--------------------------------

### into_owned

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Converts the BytesStart into an owned version with a 'static lifetime.

```APIDOC
## into_owned

### Description
Converts the BytesStart into an owned version with a 'static lifetime.

### Method
Method

### Signature
`pub fn into_owned(self) -> BytesStart<'static>`

### Parameters
None

### Returns
- **BytesStart<'static>** - An owned BytesStart.
```

--------------------------------

### BytesText usage example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Shows creating a BytesText with new(), which escapes special characters, and then normalizing content with xml_content() using XmlVersion::Implicit1_0.

```rust
let text = BytesText::new("a < b & c");
assert_eq!(&*text, "a &lt; b &amp; c");
let normalized = text.xml_content(XmlVersion::Implicit1_0);
```

--------------------------------

### level

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Returns the current nesting depth.

```APIDOC
## `level`

### Description
Returns the current nesting depth.

### Method
`pub const fn level(&self) -> u16`

### Returns
`u16` - The current nesting depth.
```

--------------------------------

### Writer::write_event

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/writer.md

Writes a single XML event (e.g., Start, End, Text) to the underlying writer. This is the low-level event API for writing XML.

```APIDOC
## Writer::write_event

### Description
Writes a single XML event (e.g., Start, End, Text) to the underlying writer. This is the low-level event API for writing XML.

### Method
Method

### Parameters
- `event` (Event) - Required - The XML event to write. Must be one of the `quick_xml::events::Event` variants.

### Returns
- `Result<()>` - Ok on success, or an error if writing fails.

### Example
```rust
use quick_xml::events::{BytesStart, Event};
use quick_xml::writer::Writer;
use std::io::Cursor;

let mut writer = Writer::new(Cursor::new(Vec::new()));
let start = BytesStart::new("root");
writer.write_event(Event::Start(start)).unwrap();
```
```

--------------------------------

### DecodingReader::new

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/encoding.md

Creates a new DecodingReader that starts as UTF-8 and auto-detects the encoding on first read. This is useful for decoding non-ASCII-compatible encodings like UTF-16.

```APIDOC
## DecodingReader::new

### Description
Creates a new `DecodingReader` that starts as UTF-8 and auto-detects the encoding on first read. This is useful for decoding non-ASCII-compatible encodings like UTF-16.

### Method
`pub fn new(inner: R) -> Self`

### Parameters
- `inner` (R) - The underlying byte stream to decode.

### Returns
- `Self` - A new `DecodingReader` instance.

### Example
```rust
let bytes = b"\xff\xfe...utf-16 bytes...";
let reader = DecodingReader::new(&bytes[..]);
```
```

--------------------------------

### Configure Reader via config_mut()

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/configuration.md

Use Reader::config_mut() to adjust parsing behavior. Set trim_text(true) to strip leading/trailing whitespace from Text events, enable comment validation, and keep empty elements as Empty events (default).

```rust
let mut reader = Reader::from_str(xml);
let cfg = reader.config_mut();
cfg.trim_text(true);
cfg.check_comments = true;          // validate comments
cfg.expand_empty_elements = false;  // default: keep <tag/> as Empty events
```

--------------------------------

### XML example for deserializing top-level sequences of enums

Source: https://github.com/tafia/quick-xml/blob/master/Changelog.md

Shown in the bug fix for issue #500, this XML demonstrates a top-level sequence of enum values (A, B, C) that previously failed to deserialize correctly.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- list of enum Enum { A, B, С } -->
<A/>
<B/>
<C/>
```

--------------------------------

### Writer::config() / Writer::config_mut()

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/configuration.md

Access the writer configuration to control formatting of empty elements. Use config() for read-only access and config_mut() to modify settings.

```APIDOC
## [GET] Writer::config() / Writer::config_mut()

### Description
Access the writer configuration to control formatting of empty elements. Use config() for read-only access and config_mut() to modify settings.

### Method
GET

### Endpoint
Writer::config() / Writer::config_mut()

### Parameters
#### Configuration Fields
- **add_space_before_slash_in_empty_elements** (bool) - Optional - Default: `false`. When `true`, outputs `<tag />`; when `false`, outputs `<tag/>`. W3C recommends `true` for XHTML compatibility.

### Response
#### Success Response (200)
- **add_space_before_slash_in_empty_elements** (bool) - Current setting for space before slash in empty elements.

#### Response Example
```json
{
  "add_space_before_slash_in_empty_elements": false
}
```
```

--------------------------------

### resolve_prefix

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Resolves a namespace prefix to its namespace.

```APIDOC
## `resolve_prefix`

### Description
Resolves a namespace prefix to its namespace.

### Method
`pub fn resolve_prefix(&self, prefix: Option<Prefix>, use_default: bool) -> ResolveResult<'_>`

### Parameters
- `prefix` (Option<Prefix>) - Required - The prefix to resolve; None for default namespace.
- `use_default` (bool) - Required - Whether to use the default namespace when prefix is None.

### Returns
`ResolveResult<'_>` - The resolution result.
```

--------------------------------

### read_to_end

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/reader.md

Consumes events until the matching end tag for the given QName, handling nested elements with the same name. Returns the byte span of the content between the start and end tags.

```APIDOC
## read_to_end

### Description
Call after reading a `Start` event; consumes events until the matching `End` (handling nested elements with the same name literally). Returns the byte span of the content between `>` and `<`. If the end tag is never found, returns `Error::IllFormed(IllFormedError::MissingEndTag)`. The `end` parameter must be the name in reader encoding — normally obtained via `BytesStart::to_end()`.

### Method
Rust function

### Signature
```rust
pub fn read_to_end(&mut self, end: QName) -> Result<Span>
```

### Parameters
- `end` (QName) - Required - The name of the end tag to match.

### Returns
- `Result<Span>` - The byte span of the content between the tags, or an error.
```

--------------------------------

### read_text_into signature

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/reader.md

Method signature for `read_text_into` on `Reader<R: BufRead>`. Buffered counterpart of `read_text`. Content is appended to `buf`, which may already contain start tag.

```rust
pub fn read_text_into<'b>(&mut self, end: QName, buf: &'b mut Vec<u8>) -> Result<BytesText<'b>>
```

--------------------------------

### max_namespace_bindings

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Returns the current maximum number of in-scope user namespace bindings allowed.

```APIDOC
## `max_namespace_bindings`

### Description
Returns the current maximum number of in-scope user namespace bindings allowed.

### Method
`pub const fn max_namespace_bindings(&self) -> usize`

### Returns
`usize` - The current limit.
```

--------------------------------

### add

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Binds a namespace prefix at the current nesting level. An empty namespace clears the binding.

```APIDOC
## `add`

### Description
Binds a namespace prefix at the current nesting level. An empty namespace clears the binding.

### Method
`pub fn add(&mut self, prefix: PrefixDeclaration, namespace: Namespace) -> Result<(), NamespaceError>`

### Parameters
- `prefix` (PrefixDeclaration) - Required - The prefix to bind.
- `namespace` (Namespace) - Required - The namespace to bind to; empty clears the binding.

### Returns
`Result<(), NamespaceError>` - Ok if binding succeeded, Err otherwise.

### Example
```rust
use quick_xml::name::{Namespace, NamespaceResolver, PrefixDeclaration};

let mut resolver = NamespaceResolver::default();
resolver.add(PrefixDeclaration::Named("ns"), Namespace("my:namespace"))?;
```
```

--------------------------------

### Write XML events to a Writer

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/writer.md

Creates a Writer over a Cursor and copies events from a Reader to the writer. Uses the low-level write_event API. The example reads an XML string and writes each event until EOF.

```rust
use quick_xml::events::{BytesEnd, BytesStart, Event};
use quick_xml::reader::Reader;
use quick_xml::writer::Writer;
use std::io::Cursor;

let xml = r#"<root><child>text</child></root>"#;
let mut reader = Reader::from_str(xml);
let mut writer = Writer::new(Cursor::new(Vec::new()));

loop {
    match reader.read_event() {
        Ok(Event::Eof) => break,
        Ok(e) => { writer.write_event(e).unwrap(); }
        Err(e) => panic!("{}", e),
    }
}
let result = writer.into_inner().into_inner();
```

--------------------------------

### Writer::new_with_indent(inner, indent_char, indent_size)

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/configuration.md

Creates a writer with indentation configured at construction time. Indentation is fixed and cannot be changed via config.

```APIDOC
## [GET] Writer::new_with_indent(inner, indent_char, indent_size)

### Description
Creates a writer with indentation configured at construction time. Indentation is fixed and cannot be changed via config.

### Method
GET

### Endpoint
Writer::new_with_indent(inner, indent_char, indent_size)

### Parameters
#### Constructor Parameters
- **inner** (Writer) - Required - The underlying writer.
- **indent_char** (char) - Required - Character used for indentation.
- **indent_size** (usize) - Required - Number of indent characters per level.

### Response
#### Success Response (200)
- **writer** (Writer) - A writer with indentation enabled.

#### Response Example
```json
{
  "writer": "Writer instance"
}
```
```

--------------------------------

### read_text signature

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/reader.md

Method signature for `read_text` on `Reader<&'a [u8]>`. Reads content between start and end tags including markup, as-is (no unescaping). Equivalent to `read_to_end(end)` then slicing input.

```rust
pub fn read_text(&mut self, end: QName) -> Result<BytesText<'a>>
```

--------------------------------

### BytesDecl::version()

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/configuration.md

Returns the version value from the XML declaration.

```APIDOC
## [METHOD] BytesDecl::version()

### Description
Returns the version value from the XML declaration.

### Method
Method call

### Endpoint
BytesDecl::version()

### Parameters
No parameters.

### Request Example
No request body.

### Response
#### Success Response
- **version** (string) - The version value from the declaration.

#### Response Example
No response body.
```

--------------------------------

### to_writer_with_root(root_tag, …)

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/configuration.md

Serializes data to a writer with an explicit root element name. The root tag is provided as a parameter.

```APIDOC
## [GET] to_writer_with_root(root_tag, …)

### Description
Serializes data to a writer with an explicit root element name. The root tag is provided as a parameter.

### Method
GET

### Endpoint
to_writer_with_root(root_tag, …)

### Parameters
#### Function Parameters
- **root_tag** (string) - Required - The name of the root element.
- **…** (additional parameters) - Required - Additional serialization parameters.

### Response
#### Success Response (200)
- **result** (Result) - The serialization result.

#### Response Example
```json
{
  "result": "Ok"
}
```
```

--------------------------------

### unescape_with custom resolver example

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/escape.md

Demonstrates `unescape_with` with a custom resolver that overrides predefined entities and adds a custom one. Predefined entities are tried after the custom resolver, and character references cannot be overridden. Entities are not resolved recursively.

```rust
use quick_xml::escape::{resolve_xml_entity, unescape_with};

let resolve = |entity: &str| match entity {
    "lt" => Some("FOO"),                 // override predefined
    "baz" => Some("&lt;"),               // custom entity
    _ => resolve_xml_entity(entity),
};
assert_eq!(
    unescape_with("&amp;&lt;&baz;", resolve).unwrap(),
    "&FOO&lt;"
);
```

--------------------------------

### bindings_of

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Returns an iterator over namespace bindings declared exactly at the given nesting level.

```APIDOC
## `bindings_of`

### Description
Returns an iterator over namespace bindings declared exactly at the given nesting level.

### Method
`pub const fn bindings_of(&self, level: u16) -> NamespaceBindingsOfLevelIter<'_>`

### Parameters
- `level` (u16) - Required - The nesting level to inspect.

### Returns
`NamespaceBindingsOfLevelIter<'_>` - An iterator yielding `(PrefixDeclaration<'_>, Namespace<'_>)` pairs.
```

--------------------------------

### Read events with namespace resolution using NsReader

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/ns-reader.md

Creates an NsReader from a string, enables text trimming, and loops over resolved events to print local names and bound namespaces. The example uses read_resolved_event_into and matches on ResolveResult::Bound and Event::Eof.

```rust
use quick_xml::events::Event;
use quick_xml::name::{Namespace, ResolveResult};
use quick_xml::reader::NsReader;

let mut reader = NsReader::from_str(r#"<x:tag1 xmlns:x="www.xxxx"><x:tag2/></x:tag1>"#);
reader.config_mut().trim_text(true);

let mut buf = Vec::new();
loop {
    match reader.read_resolved_event_into(&mut buf).unwrap() {
        (ResolveResult::Bound(Namespace(ns)), Event::Start(e)) => {
            println!("local={} ns={}", e.local_name().as_ref(), ns);
        }
        (_, Event::Eof) => break,
        _ => (),
    }
    buf.clear();
}
```

--------------------------------

### pop

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Closes the top scope, removing its namespace bindings.

```APIDOC
## `pop`

### Description
Closes the top scope, removing its namespace bindings.

### Method
`pub fn pop(&mut self)`
```

--------------------------------

### set_level

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Adjusts the current nesting depth, truncating bindings of deeper levels.

```APIDOC
## `set_level`

### Description
Adjusts the current nesting depth, truncating bindings of deeper levels.

### Method
`pub fn set_level(&mut self, level: u16)`

### Parameters
- `level` (u16) - Required - The new depth level.
```

--------------------------------

### BytesPI: create and inspect a processing instruction

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Creates a processing instruction with target `xml-stylesheet` and iterates its attributes. `BytesPI::new` requires content without `?>`; `target()` returns the name part and `attributes()` parses the data as key/value pairs.

```rust
let pi = BytesPI::new(r#"xml-stylesheet href="style.css""#);
assert_eq!(pi.target(), "xml-stylesheet");
for attr in pi.attributes() {
    println!("{:?}", attr.unwrap());
}
```

--------------------------------

### QName::prefix

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Returns the prefix part of the qualified name, i.e., the content before the first colon. Returns `None` if no prefix is present.

```APIDOC
## QName::prefix

### Description
Returns the prefix part of the qualified name, i.e., the content before the first colon.

### Method
`pub fn prefix(&self) -> Option<Prefix<'a>>`

### Parameters
- `&self` - Reference to the `QName`.

### Returns
- `Option<Prefix<'a>>` - The prefix if present, otherwise `None`.

### Example
```rust
let name = QName("prefix:local");
let prefix = name.prefix();
```
```

--------------------------------

### config

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/ns-reader.md

Returns the inner reader's configuration. This allows inspecting the current configuration settings.

```APIDOC
## config

### Description
Returns the inner reader's configuration. This allows inspecting the current configuration settings.

### Method
Accessor

### Signature
`pub const fn config(&self) -> &Config`

### Parameters
None

### Returns
- **&Config** - A reference to the configuration.

### Source
`ns_reader.rs:42`
```

--------------------------------

### Serializer::text_format

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/se.md

Sets the text format for `$text` content (regular escaped text or CDATA). Returns a mutable reference to the serializer for chaining.

```APIDOC
## Serializer::text_format

### Description
Sets the text format for `$text` content (regular escaped text or CDATA). Returns a mutable reference to the serializer for chaining.

### Method
Configuration method

### Signature
`pub fn text_format(&mut self, format: TextFormat) -> &mut Self`

### Parameters
- `format` (`TextFormat`) - Required - The text format to use.

### Returns
- `&mut Self` - The serializer for chaining.

### Source
`se/mod.rs:787`
```

--------------------------------

### to_writer / to_string

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/configuration.md

Serializes data to a writer or string, deducing the root element name from the struct name.

```APIDOC
## [GET] to_writer / to_string

### Description
Serializes data to a writer or string, deducing the root element name from the struct name.

### Method
GET

### Endpoint
to_writer / to_string

### Parameters
#### Function Parameters
- **…** (additional parameters) - Required - Serialization parameters.

### Response
#### Success Response (200)
- **result** (Result) - The serialization result.

#### Response Example
```json
{
  "result": "Ok"
}
```
```

--------------------------------

### set_max_namespace_bindings

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Sets the maximum number of in-scope user namespace bindings. Pass `usize::MAX` to disable the limit.

```APIDOC
## `set_max_namespace_bindings`

### Description
Sets the maximum number of in-scope user namespace bindings. Pass `usize::MAX` to disable the limit.

### Method
`pub fn set_max_namespace_bindings(&mut self, limit: usize) -> &mut Self`

### Parameters
- `limit` (usize) - Required - The new limit.

### Returns
`&mut Self` - The resolver for chaining.
```

--------------------------------

### bindings

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Returns an iterator over all in-scope namespace bindings, excluding the built-in `xml` and `xmlns`.

```APIDOC
## `bindings`

### Description
Returns an iterator over all in-scope namespace bindings, excluding the built-in `xml` and `xmlns`.

### Method
`pub const fn bindings(&self) -> NamespaceBindingsIter<'_>`

### Returns
`NamespaceBindingsIter<'_>` - An iterator yielding `(PrefixDeclaration<'_>, Namespace<'_>)` pairs.
```

--------------------------------

### resolve

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/name.md

Resolves a qualified name to its namespace and local name.

```APIDOC
## `resolve`

### Description
Resolves a qualified name to its namespace and local name.

### Method
`pub fn resolve<'n>(&self, name: QName<'n>, use_default: bool) -> (ResolveResult<'_>, LocalName<'n>)`

### Parameters
- `name` (QName<'n>) - Required - The qualified name to resolve.
- `use_default` (bool) - Required - Whether to use the default namespace when no prefix is present.

### Returns
`(ResolveResult<'_>, LocalName<'n>)` - The resolution result and the local name.
```

--------------------------------

### extend_attributes

Source: https://github.com/tafia/quick-xml/blob/master/_autodocs/api-reference/events.md

Extends the attributes of the BytesStart with additional attributes.

```APIDOC
## extend_attributes

### Description
Extends the attributes of the BytesStart with additional attributes.

### Method
Method

### Signature
`pub fn extend_attributes<'a, I>(&mut self, attributes: I) -> &mut BytesStart<'i> where I: IntoIterator, I::Item: Into<Attribute<'a>>`

### Parameters
- **attributes** (I) - Required - An iterator of attributes to add.

### Returns
- **&mut BytesStart<'i>** - Mutable reference to self for chaining.
```
Tokens:
Raw