quick-xml 0.40.0

High performance xml reader and writer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

//! High performance XML reader/writer.
//!
//! # Description
//!
//! quick-xml contains two modes of operation:
//!
//! A streaming API based on the [StAX] model. This is suited for larger XML documents which
//! cannot completely read into memory at once.
//!
//! The user has to explicitly _ask_ for the next XML event, similar to a database cursor.
//! This is achieved by the following two structs:
//!
//! - [`Reader`]: A low level XML pull-reader where buffer allocation/clearing is left to user.
//! - [`Writer`]: A XML writer. Can be nested with readers if you want to transform XMLs.
//!
//! Especially for nested XML elements, the user must keep track _where_ (how deep)
//! in the XML document the current event is located.
//!
//! quick-xml contains optional support of asynchronous reading and writing using [tokio].
//! To get it enable the [`async-tokio`](#async-tokio) feature.
//!
//! Furthermore, quick-xml also contains optional [Serde] support to directly
//! serialize and deserialize from structs, without having to deal with the XML events.
//! To get it enable the [`serialize`](#serialize) feature. Read more about mapping Rust types
//! to XML in the documentation of [`de`] module. Also check [`serde_helpers`]
//! module.
//!
//! # Examples
//!
//! - For a reading example see [`Reader`]
//! - For a writing example see [`Writer`]
//!
//! # Features
//!
//! `quick-xml` supports the following features:
//!
//! [StAX]: https://en.wikipedia.org/wiki/StAX
//! [tokio]: https://tokio.rs/
//! [Serde]: https://serde.rs/
//! [`de`]: ./de/index.html
#![cfg_attr(
    feature = "document-features",
    cfg_attr(doc, doc = ::document_features::document_features!(
        feature_label = "<a id=\"{feature}\" href=\"#{feature}\"><strong><code>{feature}</code></strong></a>"
    ))
)]
#![forbid(unsafe_code)]
#![deny(missing_docs)]
#![recursion_limit = "1024"]
// Enable feature requirements in the docs from 1.57
// See https://stackoverflow.com/questions/61417452
// docs.rs defines `docsrs` when building documentation
// Since 1.92 `doc_auto_cfg` was merged into `doc_cfg`
#![cfg_attr(docsrs, feature(doc_cfg))]
#![warn(clippy::missing_const_for_fn)]

#[cfg(feature = "serialize")]
pub mod de;
pub mod encoding;
pub mod errors;
pub mod escape;
pub mod events;
pub mod name;
pub mod parser;
pub mod reader;
#[cfg(feature = "serialize")]
pub mod se;
#[cfg(feature = "serde-types")]
pub mod serde_helpers;
/// Not an official API, public for integration tests
#[doc(hidden)]
pub mod utils;
pub mod writer;

use std::borrow::Cow;

// reexports
pub use crate::encoding::Decoder;
#[cfg(feature = "serialize")]
pub use crate::errors::serialize::{DeError, SeError};
pub use crate::errors::{Error, Result};
pub use crate::reader::{NsReader, Reader};
pub use crate::writer::{ElementWriter, Writer};

/// Version of XML standard
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum XmlVersion {
    /// XML declaration was missed in the entity (root document or referenced
    /// external DTD), so according to the specification, [version 1.0] is assumed.
    /// Most documents in the world are still XML 1.0 documents.
    ///
    /// [version 1.0]: https://www.w3.org/TR/xml/
    Implicit1_0,
    /// XML version was specified as [`1.0`] in the entity (root document or referenced
    /// external DTD).
    ///
    /// [`1.0`]: https://www.w3.org/TR/xml/
    Explicit1_0,
    /// XML version was specified as [`1.1`] in the entity (root document or referenced
    /// external DTD).
    ///
    /// [`1.1`]: https://www.w3.org/TR/xml11/
    Explicit1_1,
}

impl XmlVersion {
    pub(crate) fn normalize_attribute_value<'input, 'entity, F>(
        &self,
        value: &'input str,
        depth: usize,
        resolve_entity: F,
    ) -> std::result::Result<Cow<'input, str>, escape::EscapeError>
    where
        // the lifetime of the output comes from a capture or is `'static`
        F: FnMut(&str) -> Option<&'entity str>,
    {
        match self {
            Self::Explicit1_1 => {
                escape::normalize_xml11_attribute_value(value, depth, resolve_entity)
            }
            _ => escape::normalize_xml10_attribute_value(value, depth, resolve_entity),
        }
    }
}

impl Default for XmlVersion {
    #[inline]
    fn default() -> Self {
        Self::Implicit1_0
    }
}