Struct Deserializer

pub struct Deserializer<'de, R, E: EntityResolver = PredefinedEntityResolver>
where
    R: XmlRead<'de>,
{ /* private fields */ }

Available on crate feature serialize only.

A structure that deserializes XML into Rust values.

Implementations

impl<'de, R, E> Deserializer<'de, R, E>

where R: XmlRead<'de>, E: EntityResolver,

pub fn is_empty(&self) -> bool

Returns true if all events was consumed.

pub const fn get_ref(&self) -> &R

Returns the underlying XML reader.

use serde::Deserialize;
use quick_xml::de::Deserializer;
use quick_xml::Reader;

#[derive(Deserialize)]
struct SomeStruct {
    field1: String,
    field2: String,
}

// Try to deserialize from broken XML
let mut de = Deserializer::from_str(
    "<SomeStruct><field1><field2></SomeStruct>"
//   0                           ^= 28        ^= 41
);

let err = SomeStruct::deserialize(&mut de);
assert!(err.is_err());

let reader: &Reader<_> = de.get_ref().get_ref();

assert_eq!(reader.error_position(), 28);
assert_eq!(reader.buffer_position(), 41);

pub fn event_buffer_size(&mut self, limit: Option<NonZeroUsize>) -> &mut Self

Available on crate feature overlapped-lists only.

Set the maximum number of events that could be skipped during deserialization of sequences.

If <element> contains more than specified nested elements, $text or CDATA nodes, then DeError::TooManyEvents will be returned during deserialization of sequence field (any type that uses deserialize_seq for the deserialization, for example, Vec<T>).

This method can be used to prevent a DoS attack and infinite memory consumption when parsing a very large XML to a sequence field.

It is strongly recommended to set limit to some value when you parse data from untrusted sources. You should choose a value that your typical XMLs can have between different elements that corresponds to the same sequence.

Examples

Let’s imagine, that we deserialize such structure:

struct List {
  item: Vec<()>,
}

The XML that we try to parse look like this:

<any-name>
  <item/>
  <!-- Bufferization starts at this point -->
  <another-item>
    <some-element>with text</some-element>
    <yet-another-element/>
  </another-item>
  <!-- Buffer will be emptied at this point; 7 events were buffered -->
  <item/>
  <!-- There is nothing to buffer, because elements follows each other -->
  <item/>
</any-name>

There, when we deserialize the item field, we need to buffer 7 events, before we can deserialize the second <item/>:

• <another-item>
• <some-element>
• $text(with text)
• </some-element>
• <yet-another-element/> (virtual start event)
• <yet-another-element/> (virtual end event)
• </another-item>

Note, that <yet-another-element/> internally represented as 2 events: one for the start tag and one for the end tag. In the future this can be eliminated, but for now we use auto-expanding feature of a reader, because this simplifies deserializer code.

impl<'de> Deserializer<'de, SliceReader<'de>>

pub fn from_str(source: &'de str) -> Self

Create new deserializer that will borrow data from the specified string.

Deserializer created with this method will not resolve custom entities.

impl<'de, E> Deserializer<'de, SliceReader<'de>, E>

where E: EntityResolver,

pub fn from_str_with_resolver(source: &'de str, entity_resolver: E) -> Self

Create new deserializer that will borrow data from the specified string and use specified entity resolver.

impl<'de, R> Deserializer<'de, IoReader<R>>

where R: BufRead,

pub fn from_reader(reader: R) -> Self

Create new deserializer that will copy data from the specified reader into internal buffer.

If you already have a string use Self::from_str instead, because it will borrow instead of copy. If you have &[u8] which is known to represent UTF-8, you can decode it first before using from_str.

Deserializer created with this method will not resolve custom entities.

impl<'de, R, E> Deserializer<'de, IoReader<R>, E>

where R: BufRead, E: EntityResolver,

pub fn with_resolver(reader: R, entity_resolver: E) -> Self

Create new deserializer that will copy data from the specified reader into internal buffer and use specified entity resolver.

If you already have a string use Self::from_str instead, because it will borrow instead of copy. If you have &[u8] which is known to represent UTF-8, you can decode it first before using from_str.

Trait Implementations

impl<'de, 'a, R, E> Deserializer<'de> for &'a mut Deserializer<'de, R, E>

where R: XmlRead<'de>, E: EntityResolver,

fn deserialize_char<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Character represented as strings.

fn deserialize_string<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Representation of owned strings the same as non-owned.

fn deserialize_bytes<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Forwards deserialization to the deserialize_any.

fn deserialize_byte_buf<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Forwards deserialization to the deserialize_bytes.

fn deserialize_unit_struct<V>( self, _name: &'static str, visitor: V, ) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Representation of the named units the same as unnamed units.

fn deserialize_tuple<V>( self, _len: usize, visitor: V, ) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Representation of tuples the same as sequences.

fn deserialize_tuple_struct<V>( self, _name: &'static str, len: usize, visitor: V, ) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Representation of named tuples the same as unnamed tuples.

fn deserialize_map<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Forwards deserialization to the deserialize_struct with empty name and fields.

fn deserialize_identifier<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Identifiers represented as strings.

fn deserialize_ignored_any<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Forwards deserialization to the deserialize_unit.

fn deserialize_unit<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Unit represented in XML as a xs:element or text/CDATA content. Any content inside xs:element is ignored and skipped.

Produces unit struct from any of following inputs:

• any <tag ...>...</tag>
• any <tag .../>
• any consequent text / CDATA content (can consist of several parts delimited by comments and processing instructions)

Events handling

Event	XML	Handling
DeEvent::Start	<tag>...</tag>	Calls visitor.visit_unit(), consumes all events up to and including corresponding End event
DeEvent::End	</tag>	This is impossible situation, the method will panic if it happens
DeEvent::Text	text content or <![CDATA[cdata content]]> (probably mixed)	Calls visitor.visit_unit(). The content is ignored
DeEvent::Eof		Emits UnexpectedEof

fn deserialize_newtype_struct<V>( self, _name: &'static str, visitor: V, ) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Forwards deserialization of the inner type. Always calls Visitor::visit_newtype_struct with the same deserializer.

type Error = DeError

The error type that can be returned if some error occurs during deserialization.

fn deserialize_i8<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i8 value.

fn deserialize_i16<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i16 value.

fn deserialize_i32<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i32 value.

fn deserialize_i64<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i64 value.

fn deserialize_u8<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a u8 value.

fn deserialize_u16<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a u16 value.

fn deserialize_u32<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a u32 value.

fn deserialize_u64<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a u64 value.

fn deserialize_i128<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an i128 value.

fn deserialize_u128<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an u128 value.

fn deserialize_f32<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a f32 value.

fn deserialize_f64<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a f64 value.

fn deserialize_bool<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a bool value.

fn deserialize_str<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a string value and does not benefit from taking ownership of buffered data owned by the Deserializer.

fn deserialize_struct<V>( self, _name: &'static str, fields: &'static [&'static str], visitor: V, ) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a struct with a particular name and fields.

fn deserialize_enum<V>( self, _name: &'static str, _variants: &'static [&'static str], visitor: V, ) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an enum value with a particular name and possible variants.

fn deserialize_seq<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting a sequence of values.

fn deserialize_option<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Hint that the Deserialize type is expecting an optional value.

fn deserialize_any<V>(self, visitor: V) -> Result<V::Value, DeError>

where V: Visitor<'de>,

Require the Deserializer to figure out how to drive the visitor based on what data type is in the input.

fn is_human_readable(&self) -> bool

Determine whether Deserialize implementations should expect to deserialize their human-readable form.

impl<'de, 'a, R, E> IntoDeserializer<'de, DeError> for &'a mut Deserializer<'de, R, E>

where R: XmlRead<'de>, E: EntityResolver,

type Deserializer = &'a mut Deserializer<'de, R, E>

The type of the deserializer being converted into.

fn into_deserializer(self) -> Self

Convert this value into a deserializer.

impl<'de, 'a, R, E> SeqAccess<'de> for &'a mut Deserializer<'de, R, E>

where R: XmlRead<'de>, E: EntityResolver,

An accessor to sequence elements forming a value for top-level sequence of XML elements.

Technically, multiple top-level elements violates XML rule of only one top-level element, but we consider this as several concatenated XML documents.

type Error = DeError

The error type that can be returned if some error occurs during deserialization.

fn next_element_seed<T>( &mut self, seed: T, ) -> Result<Option<T::Value>, Self::Error>

where T: DeserializeSeed<'de>,

This returns Ok(Some(value)) for the next value in the sequence, or Ok(None) if there are no more remaining items.

fn next_element<T>(&mut self) -> Result<Option<T>, Self::Error>

where T: Deserialize<'de>,

This returns Ok(Some(value)) for the next value in the sequence, or Ok(None) if there are no more remaining items.

fn size_hint(&self) -> Option<usize>

Returns the number of elements remaining in the sequence, if known.