Struct elementtree::Element
source · pub struct Element { /* private fields */ }
Expand description
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§
source§impl Element
impl Element
sourcepub fn new<'a, Q: AsQName<'a>>(tag: Q) -> 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.
sourcepub fn new_with_namespaces<'a, Q: AsQName<'a>>(
tag: Q,
reference: &Element
) -> Element
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.
sourcepub fn from_reader<R: Read>(r: R) -> Result<Element, Error>
pub fn from_reader<R: Read>(r: R) -> Result<Element, Error>
Parses some XML data into an Element
from a reader.
sourcepub fn to_writer<W: Write>(&self, w: W) -> Result<(), Error>
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.
sourcepub fn to_writer_with_options<W: Write>(
&self,
w: W,
options: WriteOptions
) -> Result<(), Error>
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.
sourcepub fn text(&self) -> &str
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.
sourcepub fn set_text<S: Into<String>>(&mut self, value: S) -> &mut Element
pub fn set_text<S: Into<String>>(&mut self, value: S) -> &mut Element
Sets a new text value for the tag.
sourcepub fn tail(&self) -> &str
pub fn tail(&self) -> &str
Returns the tail text of a tag.
The tail is the text following an element.
sourcepub fn set_tail<S: Into<String>>(&mut self, value: S) -> &mut Element
pub fn set_tail<S: Into<String>>(&mut self, value: S) -> &mut Element
Sets a new tail text value for the tag.
sourcepub fn tag(&self) -> &QName<'_>
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).
sourcepub fn child_count(&self) -> usize
pub fn child_count(&self) -> usize
Returns the number of children
sourcepub fn get_child_mut(&mut self, idx: usize) -> Option<&mut Element>
pub fn get_child_mut(&mut self, idx: usize) -> Option<&mut Element>
Returns the nth child as a mutable reference.
sourcepub fn remove_child(&mut self, idx: usize) -> Option<Element>
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.
sourcepub fn retain_children<F>(&mut self, f: F)where
F: FnMut(&Element) -> bool,
pub fn retain_children<F>(&mut self, f: F)where
F: FnMut(&Element) -> bool,
Removes all children that don’t match a predicate.
sourcepub fn retain_children_mut<F>(&mut self, f: F)where
F: FnMut(&mut Element) -> bool,
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.
sourcepub fn append_child(&mut self, child: Element) -> &mut Element
pub fn append_child(&mut self, child: Element) -> &mut Element
Appends a new child and returns a reference to self.
sourcepub fn append_new_child<'a, Q: AsQName<'a>>(
&'a mut self,
tag: Q
) -> &'a mut Element
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));
}
}
sourcepub fn children_mut(&mut self) -> ChildrenMut<'_> ⓘ
pub fn children_mut(&mut self) -> ChildrenMut<'_> ⓘ
Returns a mutable iterator over all children.
sourcepub fn find_all<'a, Q: AsQName<'a>>(&'a self, tag: Q) -> FindChildren<'a> ⓘ
pub fn find_all<'a, Q: AsQName<'a>>(&'a self, tag: Q) -> FindChildren<'a> ⓘ
Returns all children with the given name.
sourcepub fn find_all_mut<'a, Q: AsQName<'a>>(
&'a mut self,
tag: Q
) -> FindChildrenMut<'a> ⓘ
pub fn find_all_mut<'a, Q: AsQName<'a>>(
&'a mut self,
tag: Q
) -> FindChildrenMut<'a> ⓘ
Returns all children with the given name.
sourcepub fn find<'a, Q: AsQName<'a>>(&'a self, tag: Q) -> Option<&'a Element>
pub fn find<'a, Q: AsQName<'a>>(&'a self, tag: Q) -> Option<&'a Element>
Finds the first matching child
sourcepub fn find_mut<'a, Q: AsQName<'a>>(
&'a mut self,
tag: Q
) -> Option<&'a mut Element>
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
sourcepub fn get_attr<'a, Q: AsQName<'a>>(&'a self, name: Q) -> Option<&'a str>
pub fn get_attr<'a, Q: AsQName<'a>>(&'a self, name: Q) -> Option<&'a str>
Look up an attribute by qualified name.
sourcepub fn set_attr<'a, Q: AsQName<'a>, S: Into<String>>(
&'a mut self,
name: Q,
value: S
) -> &'a mut Element
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.
sourcepub fn remove_attr<'a, Q: AsQName<'a>>(&'a mut self, name: Q) -> Option<String>
pub fn remove_attr<'a, Q: AsQName<'a>>(&'a mut self, name: Q) -> Option<String>
Removes an attribute and returns the stored string.
sourcepub fn attr_count(&self) -> usize
pub fn attr_count(&self) -> usize
Count the attributes
sourcepub fn register_namespace(&mut self, url: &str, prefix: Option<&str>)
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.
sourcepub fn set_namespace_prefix(
&mut self,
url: &str,
prefix: &str
) -> Result<(), Error>
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.
sourcepub fn get_namespace_prefix(&self, url: &str) -> Option<&str>
pub fn get_namespace_prefix(&self, url: &str) -> Option<&str>
Returns the assigned prefix for a namespace.
Finds the first element that match a given path downwards