Struct quick_xml::de::Deserializer

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

Available on crate feature serialize only.

A structure that deserializes XML into Rust values.

Implementations

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

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(s: &'de str) -> Self

Create new deserializer that will borrow data from the specified string

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.

Trait Implementations

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

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_char<V>(self, visitor: V) -> Result<V::Value, DeError>where
    V: Visitor<'de>,

Character represented as strings.

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

Returns DeError::Unsupported

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

Forwards deserialization to the deserialize_bytes.

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

Identifiers represented as strings.

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 text content
• any CDATA content

Events handling

Event	XML	Handling
DeEvent::Start	<tag>...</tag>	Calls visitor.visit_unit(), consumes all events up to corresponding End event
DeEvent::End	</tag>	Emits UnexpectedEnd("tag")
DeEvent::Text	text content	Calls visitor.visit_unit(). Text content is ignored
DeEvent::CData	<![CDATA[cdata content]]>	Calls visitor.visit_unit(). CDATA content is ignored
DeEvent::Eof		Emits UnexpectedEof

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

Representation of the names 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_ignored_any<V>(self, visitor: V) -> Result<V::Value, DeError>where
    V: Visitor<'de>,

Always call visitor.visit_unit() because returned value ignored in any case.

This method consumes any single event except the Start event, in which case all events up to corresponding End event will be consumed.

This method returns error if current event is End or Eof

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_newtype_struct<V>(
    self,
    _name: &'static str,
    visitor: V
) -> Result<V::Value, DeError>where
    V: Visitor<'de>,

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

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_map<V>(self, visitor: V) -> Result<V::Value, DeError>where
    V: Visitor<'de>,

Hint that the Deserialize type is expecting a map of key-value pairs.

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> SeqAccess<'de> for &'a mut Deserializer<'de, R>where
    R: XmlRead<'de>,

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.