Lib.rs

Cargo Features

quick-xml has no features set by default.

[dependencies]
quick-xml = { version = "0.31.0", features = ["async-tokio", "encoding", "escape-html", "overlapped-lists", "serde-types", "serialize", "document-features", "arbitrary"] }

async-tokio = tokio

Enables support for asynchronous reading and writing from tokio's IO-Traits by enabling reading events from types implementing tokio::io::AsyncBufRead.

encoding = encoding_rs

Enables support of non-UTF-8 encoded documents. Encoding will be inferred from the XML declaration if it is found, otherwise UTF-8 is assumed.

Currently, only ASCII-compatible encodings are supported. For example, UTF-16 will not work (therefore, quick-xml is not standard compliant).

Thus, quick-xml supports all encodings of encoding_rs except these:

• UTF-16BE
• UTF-16LE
• ISO-2022-JP

You should stop processing a document when one of these encodings is detected, because generated events can be wrong and do not reflect a real document structure!

Because these are the only supported encodings that are not ASCII compatible, you can check for them:

use quick_xml::events::Event;
use quick_xml::reader::Reader;

let xml = to_utf16le_with_bom(r#"<?xml encoding='UTF-16'><element/>"#);
let mut reader = Reader::from_reader(xml.as_ref());
reader.trim_text(true);

let mut buf = Vec::new();
let mut unsupported = false;
loop {
    if !reader.decoder().encoding().is_ascii_compatible() {
        unsupported = true;
        break;
    }
    buf.clear();
    match reader.read_event_into(&mut buf).unwrap() {
        Event::Eof => break,
        _ => {}
    }
}
assert_eq!(unsupported, true);

This restriction will be eliminated once issue #158 is resolved.

Affects encoding::decode, encoding::detect_encoding…

escape-html

Enables support for recognizing all HTML 5 entities in unescape and unescape_with functions. The full list of entities also can be found in https://html.spec.whatwg.org/entities.json.

overlapped-lists

This feature is for the Serde deserializer that enables support for deserializing lists where tags are overlapped with tags that do not correspond to the list.

When this feature is enabled, the XML:

<any-name>
  <item/>
  <another-item/>
  <item/>
  <item/>
</any-name>

could be deserialized to a struct:

#[derive(Deserialize)]
#[serde(rename_all = "kebab-case")]
struct AnyName {
  item: Vec<()>,
  another_item: (),
}

When this feature is not enabled (default), only the first element will be associated with the field, and the deserialized type will report an error (duplicated field) when the deserializer encounters a second <item/>.

Note, that enabling this feature can lead to high and even unlimited memory consumption, because deserializer needs to check all events up to the end of a container tag (</any-name> in this example) to figure out that there are no more items for a field. If </any-name> or even EOF is not encountered, the parsing will never end which can lead to a denial-of-service (DoS) scenario.

Having several lists and overlapped elements for them in XML could also lead to quadratic parsing time, because the deserializer must check the list of events as many times as the number of sequence fields present in the schema.

To reduce negative consequences, always limit the maximum number of events that Deserializer will buffer.

This feature works only with serialize feature and has no effect if serialize is not enabled.

serde-types

Enables serialization of some quick-xml types using serde. This feature is rarely needed.

This feature does NOT provide XML serializer or deserializer. You should use the serialize feature for that instead. Cannot name "serde" to avoid clash with dependency. "dep:" prefix only avalible from Rust 1.60

Enables derive of serde

Affects quick-xml::serde_helpers…

serialize = serde

Enables support for serde serialization and deserialization. When this feature is enabled, quick-xml provides serializer and deserializer for XML.

This feature does NOT enables serializaton of the types inside quick-xml. If you need that, use the serde-types feature. "dep:" prefix only avalible from Rust 1.60

Affects errors::serialize, quick-xml::de, quick-xml::se…

Features from optional dependencies

In crates that don't use the dep: syntax, optional dependencies automatically become Cargo features. These features may have been created by mistake, and this functionality may be removed in the future.

document-features implicit feature

Enables document-features

document-features:

Extract documentation for the feature flags from comments in Cargo.toml

encoding_rs encoding?

serde serde-types? serialize?

tokio async-tokio?

arbitrary implicit feature

Enables arbitrary

arbitrary:

The trait for generating structured data from unstructured data