Struct ElementRef

pub struct ElementRef<'s> {
    pub name: &'s str,
    pub text_content: Cow<'s, str>,
    pub attributes: IndexMap<&'s str, &'s str>,
    pub children: Vec<ElementRef<'s>>,
}

An XML element.

This is a result of zero-copy parsing, meaning you might run into lifetime issues.

If you need to own the element separately from the source XML, you can convert it to Element using into_owned.

Fields

name: &'s str

The name of the element, e.g. LuaComponent in <LuaComponent />.

text_content: Cow<'s, str>

The text content of the element, e.g. hello in <SomeComponent>hello</SomeComponent>.

If there are multiple text nodes, they are concatenated into a single string with spaces between them. This is the only case where the parsing is not zero-copy, as the text is discontinuous in the source XML.

If there is no text content, the value is Cow::Borrowed("").

attributes: IndexMap<&'s str, &'s str>

A map of element attributes, e.g. name="comp" in <SomeComponent name="comp" />, where the key is name and the value is comp.

children: Vec<ElementRef<'s>>

A list of child elements, e.g. [<SomeComponent/>, <SomeOtherComponent/>] in

<Entity>
    <SomeComponent/>
    <SomeOtherComponent/>
</Entity>

Implementations

impl<'s> ElementRef<'s>

pub fn new(name: &'s str) -> Self

Create a new element with the given name.

pub fn to_owned(&self) -> Element

Convert this element to an owned Element by cloning all the strings.

Example

let nonstatic_prop = String::from("value");
let element = nxml_ref!(<Entity {&nonstatic_prop} />);

let owned_element = element.to_owned();

assert_static(owned_element);

impl<'s> ElementRef<'s>

pub fn attr(&self, key: &str) -> Option<&str>

A shorthand for getting an attribute value.

Example

let element = nxml_ref!(<Entity key="value"/>);

assert_eq!(element.attr("key"), Some("value"));

pub fn child(&self, name: &str) -> Option<&Self>

Find the first child element with the given name.

Example

let element = nxml_ref!(<Entity><Child>"hello"</Child></Entity>);

assert_eq!(element.child("Child").unwrap().text_content, "hello");

pub fn child_mut(&mut self, name: &str) -> Option<&mut Self>

Find the first child element with the given name, mutable version.

Example

let mut element = nxml_ref!(<Entity><Child/></Entity>);

element.child_mut("Child").unwrap().text_content = "world".into();

assert_eq!(element.child("Child").unwrap().text_content, "world");

pub fn children<'a>( &'a self, name: &'a str, ) -> impl Iterator<Item = &'a Self> + 'a

Iterate over all child elements with the given name.

Example

let element = nxml_ref!(<Entity><Child/><Other/><Child/></Entity>);

assert_eq!(element.children("Child").count(), 2);

pub fn children_mut<'a>( &'a mut self, name: &'a str, ) -> impl Iterator<Item = &'a mut Self> + 'a

Iterate over all child elements with the given name, mutable version.

Example

let mut element = nxml_ref!(<Entity><Child/><Other/><Child/></Entity>);

for child in element.children_mut("Child") {
   child.text_content = "text".into();
}

assert_eq!(element.to_string(), "<Entity><Child>text</Child><Other/><Child>text</Child></Entity>");

pub fn set_attr(&mut self, key: &'s str, value: &'s str)

A shorthand for setting an attribute value.

Example

let mut element = nxml_ref!(<Entity />);

element.set_attr("key", "value");

assert_eq!(element.to_string(), "<Entity key=\"value\"/>");

pub fn remove_attr(&mut self, key: &str) -> Option<&'s str>

A shorthand for removing an attribute value.

Example

let mut element = nxml_ref!(<Entity key="value" other="other" />);

element.remove_attr("key");

assert_eq!(element.to_string(), "<Entity other=\"other\"/>");

pub fn with_attr(self, key: &'s str, value: &'s str) -> Self

Chained version of set_attr.

Example

let element = ElementRef::new("Entity")
    .with_attr("key", "value");

assert_eq!(element.to_string(), "<Entity key=\"value\"/>");

pub fn with_text(self, text: &'s str) -> Self

Chained shorthand for setting the text content.

Example

let element = ElementRef::new("Entity")
    .with_text("hello");

assert_eq!(element.to_string(), "<Entity>hello</Entity>");

pub fn with_child(self, element: Self) -> Self

Chained shorthand for adding a child element.

Example

let element = ElementRef::new("Entity")
     .with_child(ElementRef::new("Child"));

assert_eq!(element.to_string(), "<Entity><Child/></Entity>");

pub fn display(&self) -> PrettyDisplay<'_, Self>

A customizable Display impl that pretty-prints the element.

Example

let element = nxml_ref!(<Entity><Child/></Entity>);

assert_eq!(element.display().indent_width(0).to_string(), "<Entity>\n<Child/>\n</Entity>");

Trait Implementations

impl<'s> Clone for ElementRef<'s>

fn clone(&self) -> ElementRef<'s>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'s> Debug for ElementRef<'s>

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

Formats the value using the given formatter.

impl<'s> Display for ElementRef<'s>

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

Formats the value using the given formatter.

impl<'s, 'e> Div<&str> for &'e ElementRef<'s>

fn div(self, rhs: &str) -> Self::Output

A chainable child element accessor

Example

let element = nxml_ref!(<Entity><Child><Grandchild>"hello"</Grandchild></Child></Entity>);

assert_eq!(&element / "Child" / "Grandchild" % Text, "hello");

type Output = &'e ElementRef<'s>

The resulting type after applying the / operator.

impl<'s, 'e> Div<&str> for &'e mut ElementRef<'s>

fn div(self, rhs: &str) -> Self::Output

A mutable version of the child accessor.

Example

let mut element = nxml_ref!(<Entity><Child><Grandchild>hello</Grandchild></Child></Entity>);

(&mut element / "Child").children.clear();

assert_eq!(element.to_string(), "<Entity><Child/></Entity>");

type Output = &'e mut ElementRef<'s>

The resulting type after applying the / operator.

impl<'s> PartialEq for ElementRef<'s>

fn eq(&self, other: &ElementRef<'s>) -> 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<'s, 'e> Rem<&str> for &'e ElementRef<'s>

fn rem(self, rhs: &str) -> Self::Output

A shorthand for getting an attribute value. Not index because &element / "child" % "key" is better than &(&element / "child")["key"].

Example

let element = nxml_ref!(<Entity key="value"/>);

assert_eq!(&element % "key", "value");

type Output = &'e str

The resulting type after applying the % operator.

impl<'s, 'e> Rem<Text> for &'e ElementRef<'s>

fn rem(self, _: Text) -> Self::Output

A shorthand for getting the text content.

Example

let element = nxml_ref!(<Entity>"hello"</Entity>);

assert_eq!(&element % Text, "hello");

type Output = &'e str

The resulting type after applying the % operator.

impl<'s> Eq for ElementRef<'s>

impl<'s> StructuralPartialEq for ElementRef<'s>