Struct Element

pub struct Element { /* private fields */ }

Represents an XML element.

Usually constructed from either parsing or one of the two constructors an element is part of a tree and represents an XML element and the children contained.

Imagine a structure like this:

<p>Hello <strong>World</strong>!</p>

In this case the structure is more or less represented like this:

Element {
  tag: "p",
  text: "Hello ",
  tail: None,
  children: [
    Element {
      tag: "strong",
      text: "World",
      tail: Some("!")
    }
  ]
}

Namespaces are internally managed and inherited downwards when an element is created.

Implementations

impl Element

pub fn new<'a, Q: AsQName<'a>>(tag: Q) -> Element

Creates a new element without any children but a given tag.

This can be used at all times to create a new element however when you work with namespaces it’s recommended to only use this for the root element and then create further children through new_with_namespaces as otherwise namespaces will not be propagaged downwards properly.

pub fn new_with_namespaces<'a, Q: AsQName<'a>>( tag: Q, reference: &Element, ) -> Element

Creates a new element without any children but inheriting the namespaces from another element.

This has the advantage that internally the map will be shared across elements for as long as no further modifications are taking place.

pub fn from_reader<R: Read>(r: R) -> Result<Element, Error>

Parses some XML data into an Element from a reader.

pub fn to_writer<W: Write>(&self, w: W) -> Result<(), Error>

Dump an element as XML document into a writer.

This will create an XML document with a processing instruction to start it. There is currently no API to only serialize a non standalone element.

Currently the writer has no way to customize what is generated in particular there is no support yet for automatically indenting elements. The reason for this is that there is no way to ignore this information automatically in the absence of DTD support which is not really planned.

pub fn to_writer_with_options<W: Write>( &self, w: W, options: WriteOptions, ) -> Result<(), Error>

Dump an element as XML document into a writer with option.

This will create an XML document with a processing instruction to start it. There is currently no API to only serialize a non standalone element.

Currently the writer has no way to customize what is generated in particular there is no support yet for automatically indenting elements. The reason for this is that there is no way to ignore this information automatically in the absence of DTD support which is not really planned.

pub fn to_string(&self) -> Result<String, Error>

Dump an element as XML document into a string

pub fn text(&self) -> &str

Returns the text of a tag.

Note that this does not trim or modify whitespace so the return value might contain structural information from the XML file.

pub fn set_text<S: Into<String>>(&mut self, value: S) -> &mut Element

Sets a new text value for the tag.

pub fn tail(&self) -> &str

Returns the tail text of a tag.

The tail is the text following an element.

pub fn set_tail<S: Into<String>>(&mut self, value: S) -> &mut Element

Sets a new tail text value for the tag.

pub fn tag(&self) -> &QName<'_>

The tag of the element as qualified name.

Use the QName functionality to extract the information from the tag name you care about (like the local name).

pub fn set_tag<'a>(&mut self, tag: &QName<'a>) -> &mut Element

Sets a new tag for the element.

pub fn child_count(&self) -> usize

Returns the number of children

pub fn get_child(&self, idx: usize) -> Option<&Element>

Returns the nth child.

pub fn get_child_mut(&mut self, idx: usize) -> Option<&mut Element>

Returns the nth child as a mutable reference.

pub fn remove_child(&mut self, idx: usize) -> Option<Element>

Removes a child.

This returns the element if it was removed or None if the index was out of bounds.

pub fn retain_children<F>(&mut self, f: F)

where F: FnMut(&Element) -> bool,

Removes all children that don’t match a predicate.

pub fn retain_children_mut<F>(&mut self, f: F)

where F: FnMut(&mut Element) -> bool,

Removes all children that don’t match a predicate. The predicate is passed a mutable reference to each element.

pub fn append_child(&mut self, child: Element) -> &mut Element

Appends a new child and returns a reference to self.

pub fn append_new_child<'a, Q: AsQName<'a>>( &'a mut self, tag: Q, ) -> &'a mut Element

Appends a new child to the element and returns a reference to it.

This uses Element::new_with_namespaces internally and can then be used like this:

use elementtree::Element;

let ns = "http://example.invalid/#ns";
let mut root = Element::new((ns, "mydoc"));

{
    let mut list = root.append_new_child((ns, "list"));
    for x in 0..3 {
        list.append_new_child((ns, "item")).set_text(format!("Item {}", x));
    }
}

pub fn children(&self) -> Children<'_>

Returns an iterator over all children.

pub fn children_mut(&mut self) -> ChildrenMut<'_>

Returns a mutable iterator over all children.

pub fn find_all<'a, Q: AsQName<'a>>(&'a self, tag: Q) -> FindChildren<'a>

Returns all children with the given name.

pub fn find_all_mut<'a, Q: AsQName<'a>>( &'a mut self, tag: Q, ) -> FindChildrenMut<'a>

Returns all children with the given name.

pub fn find<'a, Q: AsQName<'a>>(&'a self, tag: Q) -> Option<&'a Element>

Finds the first matching child

pub fn find_mut<'a, Q: AsQName<'a>>( &'a mut self, tag: Q, ) -> Option<&'a mut Element>

Finds the first matching child and returns a mut ref

pub fn get_attr<'a, Q: AsQName<'a>>(&'a self, name: Q) -> Option<&'a str>

Look up an attribute by qualified name.

pub fn set_attr<'a, Q: AsQName<'a>, S: Into<String>>( &'a mut self, name: Q, value: S, ) -> &'a mut Element

Sets a new attribute.

This returns a reference to the element so you can chain the calls.

pub fn remove_attr<'a, Q: AsQName<'a>>(&'a mut self, name: Q) -> Option<String>

Removes an attribute and returns the stored string.

pub fn attrs(&self) -> Attrs<'_>

Returns an iterator over all attributes

pub fn attr_count(&self) -> usize

Count the attributes

pub fn register_namespace(&mut self, url: &str, prefix: Option<&str>)

Registers a namespace with the internal namespace map.

Note that there is no API to remove namespaces from an element once the namespace has been set so be careful with modifying this!

This optionally also registers a specific prefix however if that prefix is already used a random one is used instead.

pub fn set_namespace_prefix( &mut self, url: &str, prefix: &str, ) -> Result<(), Error>

Sets a specific namespace prefix. This will also register the namespace if it was unknown so far.

In case a prefix is set that is already set elsewhere an error is returned. It’s recommended that this method is only used on the root node before other prefixes are added.

pub fn get_namespace_prefix(&self, url: &str) -> Option<&str>

Returns the assigned prefix for a namespace.

pub fn navigate<'a, Q: AsQName<'a>>(&'a self, path: &[Q]) -> Option<&'a Element>

Finds the first element that match a given path downwards

Trait Implementations

impl Clone for Element

fn clone(&self) -> Element

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Element

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.