Struct quick_xml::de::Deserializer

source ·
pub struct Deserializer<'de, R, E: EntityResolver = PredefinedEntityResolver>
where R: XmlRead<'de>,
{ /* private fields */ }
Available on crate feature serialize only.
Expand description

A structure that deserializes XML into Rust values.

Implementations§

source§

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

source

pub fn is_empty(&self) -> bool

Returns true if all events was consumed.

source

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);
source

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.

source§

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

source

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.

source§

impl<'de, E> Deserializer<'de, SliceReader<'de>, E>
where E: EntityResolver,

source

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.

source§

impl<'de, R> Deserializer<'de, IoReader<R>>
where R: BufRead,

source

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.

source§

impl<'de, R, E> Deserializer<'de, IoReader<R>, E>
where R: BufRead, E: EntityResolver,

source

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§

source§

impl<'de, 'a, R, E> Deserializer<'de> for &'a mut Deserializer<'de, R, E>
where R: XmlRead<'de>, E: EntityResolver,

source§

fn deserialize_char<V>(self, visitor: V) -> Result<V::Value, DeError>
where V: Visitor<'de>,

Character represented as strings.

source§

fn deserialize_string<V>(self, visitor: V) -> Result<V::Value, DeError>
where V: Visitor<'de>,

Representation of owned strings the same as non-owned.

source§

fn deserialize_bytes<V>(self, visitor: V) -> Result<V::Value, DeError>
where V: Visitor<'de>,

Forwards deserialization to the deserialize_any.

source§

fn deserialize_byte_buf<V>(self, visitor: V) -> Result<V::Value, DeError>
where V: Visitor<'de>,

Forwards deserialization to the deserialize_bytes.

source§

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.

source§

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

Representation of tuples the same as sequences.

source§

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.

source§

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.

source§

fn deserialize_identifier<V>(self, visitor: V) -> Result<V::Value, DeError>
where V: Visitor<'de>,

Identifiers represented as strings.

source§

fn deserialize_ignored_any<V>(self, visitor: V) -> Result<V::Value, DeError>
where V: Visitor<'de>,

Forwards deserialization to the deserialize_unit.

source§

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
EventXMLHandling
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::Texttext content or <![CDATA[cdata content]]> (probably mixed)Calls visitor.visit_unit(). The content is ignored
DeEvent::EofEmits UnexpectedEof
source§

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.

source§

type Error = DeError

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

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.
source§

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.
source§

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.
source§

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.
source§

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.
source§

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.
source§

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.
source§

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.
source§

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. Read more
source§

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. Read more
source§

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.
source§

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.
source§

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.
source§

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. Read more
source§

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.
source§

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.
source§

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.
source§

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. Read more
source§

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. Read more
source§

fn is_human_readable(&self) -> bool

Determine whether Deserialize implementations should expect to deserialize their human-readable form. Read more
source§

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.

source§

type Error = DeError

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

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. Read more
source§

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. Read more
source§

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

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

Auto Trait Implementations§

§

impl<'de, R, E> Freeze for Deserializer<'de, R, E>
where R: Freeze, E: Freeze,

§

impl<'de, R, E = PredefinedEntityResolver> !RefUnwindSafe for Deserializer<'de, R, E>

§

impl<'de, R, E> Send for Deserializer<'de, R, E>
where R: Send, E: Send,

§

impl<'de, R, E> Sync for Deserializer<'de, R, E>
where R: Sync, E: Sync,

§

impl<'de, R, E> Unpin for Deserializer<'de, R, E>
where R: Unpin, E: Unpin,

§

impl<'de, R, E = PredefinedEntityResolver> !UnwindSafe for Deserializer<'de, R, E>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.