Struct Element

pub struct Element { /* private fields */ }

Represents an XML element. It acts as a pointer to actual element data stored in Document.

This struct only contains a unique usize id and implements trait Copy. So you do not need to bother with having a reference.

Because the actual data of the element is stored in Document, most methods takes &Document or &mut Document as its first argument.

Note that an element may only interact with elements of the same document, but the crate doesn’t know which document an element is from. Trying to push an element from a different Document may result in unexpected errors.

Examples

Find children nodes with attribute

use xml_doc::{Document, Element};

let doc = Document::parse_str(r#"<?xml version="1.0"?>
<data>
  <item class="value">a</item>
  <item class="value">b</item>
  <item></item>
</data>
"#).unwrap();

let data = doc.root_element().unwrap();
let value_items: Vec<Element> = data.children(&doc)
    .iter()
    .filter_map(|node| node.as_element())
    .filter(|elem| elem.attribute(&doc, "class") == Some("value"))
    .collect();

Implementations

impl Element

pub fn new<S: Into<String>>(doc: &mut Document, full_name: S) -> Self

Create a new empty element with full_name.

If full_name contains :, everything before that will be interpreted as a namespace prefix.

pub fn build<S: Into<String>>(doc: &mut Document, name: S) -> ElementBuilder<'_>

Chain methods to build an element easily. The chain can be finished with .finish() or .push_to(parent).

Example

use xml_doc::{Document, Element, Node};

let mut doc = Document::new();

let elem = Element::build(&mut doc, "root")
    .attribute("id", "main")
    .attribute("class", "main")
    .finish();

doc.push_root_node(elem.as_node());

pub fn is_container(&self) -> bool

Returns true if element is a container.

See Document::container() for more information on ‘container’.

pub fn as_node(&self) -> Node

Equivalent to Node::Element(self)

pub fn separate_prefix_name(full_name: &str) -> (&str, &str)

Seperate full_name by :, returning (prefix, name).

The first str is "" if full_name has no prefix.

impl Element

Below are methods that take &Document as its first argument.

pub fn is_root(&self, doc: &Document) -> bool

Returns true if this element is the root node of document.

Note that this crate allows Document to have multiple elements, even though it’s not valid xml.

pub fn full_name<'a>(&self, doc: &'a Document) -> &'a str

Get full name of element, including its namespace prefix. Use Element::name() to get its name without the prefix.

pub fn set_full_name<S: Into<String>>(&self, doc: &mut Document, name: S)

pub fn prefix_name<'a>(&self, doc: &'a Document) -> (&'a str, &'a str)

Get prefix and name of element. If it doesn’t have prefix, will return an empty string.

<prefix: name -> ("prefix", "name")

pub fn prefix<'a>(&self, doc: &'a Document) -> &'a str

Get namespace prefix of element, without name.

<prefix:name> -> "prefix"

pub fn set_prefix<S: Into<String>>(&self, doc: &mut Document, prefix: S)

Set prefix of element, preserving its name.

prefix should not have a :, or everything after : will be interpreted as part of element name.

If prefix is an empty string, removes prefix.

pub fn name<'a>(&self, doc: &'a Document) -> &'a str

Get name of element, without its namespace prefix. Use Element::full_name() to get its full name with prefix.

<prefix:name> -> "name"

pub fn set_name<S: Into<String>>(&self, doc: &mut Document, name: S)

Set name of element, preserving its prefix.

name should not have a :, or everything before : may be interpreted as namespace prefix.

pub fn attributes<'a>(&self, doc: &'a Document) -> &'a HashMap<String, String>

Get attributes of element.

The attribute names may have namespace prefix. To strip the prefix and only its name, call Element::separate_prefix_name.

use xml_doc::{Document, Element};

let mut doc = Document::new();
let element = Element::build(&mut doc, "name")
    .attribute("id", "name")
    .attribute("pre:name", "value")
    .finish();

let attrs = element.attributes(&doc);
for (full_name, value) in attrs {
    let (prefix, name) = Element::separate_prefix_name(full_name);
    // ("", "id"), ("pre", "name")
}

pub fn attribute<'a>(&self, doc: &'a Document, name: &str) -> Option<&'a str>

Get attribute value of an element by its full name. (Namespace prefix isn’t stripped)

pub fn set_attribute<S, T>(&self, doc: &mut Document, name: S, value: T)

where S: Into<String>, T: Into<String>,

Add or set attribute.

If name contains a :, everything before : will be interpreted as namespace prefix.

pub fn mut_attributes<'a>( &self, doc: &'a mut Document, ) -> &'a mut HashMap<String, String>

pub fn namespace<'a>(&self, doc: &'a Document) -> Option<&'a str>

Gets the namespace of this element.

Shorthand for self.namespace_for_prefix(doc, self.prefix(doc)).

pub fn namespace_decls<'a>( &self, doc: &'a Document, ) -> &'a HashMap<String, String>

Gets HashMap of xmlns:prefix=namespace declared in this element’s attributes.

Default namespace has empty string as key.

pub fn mut_namespace_decls<'a>( &self, doc: &'a mut Document, ) -> &'a mut HashMap<String, String>

pub fn set_namespace_decl<S, T>( &self, doc: &mut Document, prefix: S, namespace: T, )

where S: Into<String>, T: Into<String>,

pub fn namespace_for_prefix<'a>( &self, doc: &'a Document, prefix: &str, ) -> Option<&'a str>

Get namespace value given prefix, for this element. “xml” and “xmlns” returns its default namespace.

pub fn text_content(&self, doc: &Document) -> String

Concatenate all text content of this element, including its child elements text_content().

Implementation of Node.textContent

pub fn set_text_content<S: Into<String>>(&self, doc: &mut Document, text: S)

Clears all its children and inserts a Node::Text with given text.

impl Element

Below are methods related to finding nodes in tree.

pub fn parent(&self, doc: &Document) -> Option<Element>

pub fn has_parent(&self, doc: &Document) -> bool

self.parent(doc).is_some()

pub fn children<'a>(&self, doc: &'a Document) -> &'a Vec<Node>

Get child Nodes of this element.

pub fn children_recursive<'a>(&self, doc: &'a Document) -> Vec<&'a Node>

Get all child nodes recursively. (i.e. includes its children’s children.)

pub fn has_children(&self, doc: &Document) -> bool

!self.children(doc).is_empty()

pub fn child_elements(&self, doc: &Document) -> Vec<Element>

Get only child Elements of this element.

This calls .children().iter().filter_map().collect(). Use Element::children() if performance is important.

pub fn child_elements_recursive(&self, doc: &Document) -> Vec<Element>

Get child Elements recursively. (i.e. includes its child element’s child elements)

pub fn find(&self, doc: &Document, name: &str) -> Option<Element>

Find first direct child element with name name.

pub fn find_all(&self, doc: &Document, name: &str) -> Vec<Element>

Find all direct child element with name name.

impl Element

Below are functions that modify its tree-structure.

Because an element has reference to both its parent and its children, an element’s parent and children is not directly exposed for modification. But in return, it is not possible for a document to be in an inconsistant state, where an element’s parent doesn’t have the element as its children.

pub fn push_child(&self, doc: &mut Document, node: Node) -> Result<()>

Equivalent to vec.push().

Errors

• Error::HasAParent: When you want to replace an element’s parent with another, call element.detatch() to make it parentless first. This is to make it explicit that you are changing an element’s parent, not adding another.
• Error::ContainerCannotMove: The container element’s parent must always be None.

pub fn push_to(&self, doc: &mut Document, parent: Element) -> Result<()>

Equivalent to parent.push_child().

Errors

• Error::HasAParent: When you want to replace an element’s parent with another, call element.detatch() to make it parentless first. This is to make it explicit that you are changing an element’s parent, not adding another.
• Error::ContainerCannotMove: The container element’s parent must always be None.

pub fn insert_child( &self, doc: &mut Document, index: usize, node: Node, ) -> Result<()>

Equivalent to vec.insert().

Panics

Panics if index > self.children().len()

Errors

• Error::HasAParent: When you want to replace an element’s parent with another, call element.detatch() to make it parentless first. This is to make it explicit that you are changing an element’s parent, not adding another.
• Error::ContainerCannotMove: The container element’s parent must always be None.

pub fn remove_child(&self, doc: &mut Document, index: usize) -> Node

Equivalent to vec.remove().

Panics

Panics if index >= self.children().len().

pub fn pop_child(&self, doc: &mut Document) -> Option<Node>

Equivalent to vec.pop().

pub fn clear_children(&self, doc: &mut Document) -> Vec<Node>

Remove all children and return them.

pub fn detatch(&self, doc: &mut Document) -> Result<()>

Removes itself from its parent. Note that you can’t attach this element to other documents.

Errors

• Error::ContainerCannotMove: You can’t detatch container element

Trait Implementations

impl Clone for Element

fn clone(&self) -> Element

Returns a duplicate of the value.

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.

impl PartialEq for Element

fn eq(&self, other: &Element) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Element

impl Eq for Element

impl StructuralPartialEq for Element