Struct yrs::types::xml::XmlElement

#[repr(transparent)]
pub struct XmlElement(_);

XML element data type. It represents an XML node, which can contain key-value attributes (interpreted as strings) as well as other nested XML elements or rich text (represented by XmlText type).

In terms of conflict resolution, XmlElement uses following rules:

• Attribute updates use logical last-write-wins principle, meaning the past updates are automatically overridden and discarded by newer ones, while concurrent updates made by different peers are resolved into a single value using document id seniority to establish an order.
• Child node insertion uses sequencing rules from other Yrs collections - elements are inserted using interleave-resistant algorithm, where order of concurrent inserts at the same index is established using peer’s document id seniority.

Implementations

impl XmlElement

pub fn to_string(&self) -> String

Converts current XML node into a textual representation. This representation if flat, it doesn’t include any indentation.

pub fn tag(&self) -> &str

A tag name of a current top-level XML node, eg. node <p></p> has “p” as it’s tag name.

pub fn remove_attribute<K: AsRef<str>>(
    &self,
    txn: &mut Transaction,
    attr_name: &K
)

Removes an attribute recognized by an attr_name from a current XML element.

pub fn insert_attribute<K: Into<Rc<str>>, V: AsRef<str>>(
    &self,
    txn: &mut Transaction,
    attr_name: K,
    attr_value: V
)

Inserts an attribute entry into current XML element.

pub fn get_attribute(&self, attr_name: &str) -> Option<String>

Returns a value of an attribute given its attr_name. Returns None if no such attribute can be found inside of a current XML element.

pub fn attributes(&self) -> Attributes<'_>

Returns an unordered iterator over all attributes (key-value pairs), that can be found inside of a current XML element.

pub fn next_sibling(&self) -> Option<Xml>

Returns a next sibling of a current XML element, if any exists.

pub fn prev_sibling(&self) -> Option<Xml>

Returns a previous sibling of a current XML element, if any exists.

pub fn parent(&self) -> Option<XmlElement>

Returns a parent XML element, current node can be found within. Returns None, if current node is a root.

pub fn first_child(&self) -> Option<Xml>

Returns a first child XML node (either XmlElement or XmlText), that can be found in a current XML element. Returns None if current element is empty.

pub fn len(&self) -> u32

Returns a number of child XML nodes, that can be found inside of a current XML element. This is a flat count - successor nodes (children of a children) are not counted.

pub fn successors(&self) -> TreeWalker<'_>

Returns an iterator that can be used to traverse over the successors of a current XML element. This includes recursive step over children of its children. The recursive iteration is depth-first.

Example:

/* construct node with a shape:
   <div>
      <p>Hello <b>world</b></p>
      again
   </div>
*/
use yrs::{XmlElement, Doc, Xml};

let doc = Doc::new();
let mut txn = doc.transact();
let mut html = txn.get_xml_element("div");
let p = html.push_elem_back(&mut txn, "p");
let txt = p.push_text_back(&mut txn);
txt.push(&mut txn, "Hello ");
let b = p.push_elem_back(&mut txn, "b");
let txt = b.push_text_back(&mut txn);
txt.push(&mut txn, "world");
let txt = html.push_text_back(&mut txn);
txt.push(&mut txn, "again");

for node in html.successors() {
    match node {
        Xml::Element(elem) => println!("- {}", elem.tag()),
        Xml::Text(txt) => println!("- {}", txt.to_string())
    }
}
/* will print:
   - UNDEFINED // (XML root element)
   - p
   - Hello
   - b
   - world
   - again
*/

pub fn insert_elem<S: Into<Rc<str>>>(
    &self,
    txn: &mut Transaction,
    index: u32,
    name: S
) -> XmlElement

Inserts another XmlElement with a given tag name into a current one at the given index and returns it. If index is equal to 0, new element will be inserted as a first child. If index is equal to length of current XML element, new element will be inserted as a last child. This method will panic if index is greater than the length of current XML element.

pub fn insert_text(&self, txn: &mut Transaction, index: u32) -> XmlText

Inserts a XmlText into a current XML element at the given index and returns it. If index is equal to 0, new text field will be inserted as a first child. If index is equal to length of current XML element, new text field will be inserted as a last child. This method will panic if index is greater than the length of current XML element.

pub fn remove_range(&self, txn: &mut Transaction, index: u32, len: u32)

Removes a range (defined by len) of XML nodes from the current XML element, starting at the given index. Returns the result which may contain an error if a number of elements removed is lesser than the expected one provided in len parameter.

pub fn push_elem_back<S: Into<Rc<str>>>(
    &self,
    txn: &mut Transaction,
    name: S
) -> XmlElement

Pushes a new XmlElement with a given tag name as the last child of a current one and returns it.

pub fn push_elem_front<S: Into<Rc<str>>>(
    &self,
    txn: &mut Transaction,
    name: S
) -> XmlElement

Pushes a new XmlElement with a given tag name as the first child of a current one and returns it.

pub fn push_text_back(&self, txn: &mut Transaction) -> XmlText

Pushes a new XmlText field as the last child of a current XML element and returns it.

pub fn push_text_front(&self, txn: &mut Transaction) -> XmlText

Pushes a new XmlText field as the first child of a current XML element and returns it.

pub fn get(&self, index: u32) -> Option<Xml>

Returns an XML node stored under a given index of a current XML element. Returns None if provided index is over the range of a current element.

pub fn observe<F>(&mut self, f: F) -> Subscription<XmlEvent> where
    F: Fn(&Transaction, &XmlEvent) + 'static, 

Subscribes a given callback to be triggered whenever current XML node is changed. A callback is triggered whenever a transaction gets committed. This function does not trigger if changes have been observed by nested shared collections.

Children node changes can be tracked by using [Event::delta] method. Attribute changes can be tracked by using [Event::keys] method.

Returns an [Observer] which, when dropped, will unsubscribe current callback.

pub fn unobserve(&mut self, subscription_id: SubscriptionId)

Unsubscribes a previously subscribed event callback identified by given subscription_id.

Trait Implementations

impl AsMut<Branch> for XmlElement

fn as_mut(&mut self) -> &mut Branch

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<Branch> for XmlElement

fn as_ref(&self) -> &Branch

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for XmlElement

fn clone(&self) -> XmlElement

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for XmlElement

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

Formats the value using the given formatter.

impl From<BranchPtr> for XmlElement

fn from(inner: BranchPtr) -> Self

Converts to this type from the input type.

impl Into<XmlElement> for XmlFragment

fn into(self) -> XmlElement

Converts this type into the (usually inferred) input type.

impl PartialEq<XmlElement> for XmlElement

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl Eq for XmlElement

impl StructuralEq for XmlElement

impl StructuralPartialEq for XmlElement