Struct svgdom::Node

pub struct Node(_);

Representation of an SVG node.

This is main block of the library.

It's designed as classical DOM node. We have links to parent node, first child, last child, previous sibling and next sibling. So DOM nodes manipulations are very fast.

Node consist of: - The NodeType, which indicates it's type. It can't be changed. - Optional TagName, used only by the element nodes. - Unique ID of the element node. Can be set to the nodes with other types, but without any affect. - List of the SVG attributes. - List of the unknown attributes. - Optional text data, which is used by non-element nodes.

Most of the API are designed to work with SVG elements and attributes. Processing of non-SVG data is pretty hard/verbose, since it's an SVG DOM, not an XML.

Methods

impl Node

fn document(&self) -> Document

Returns a Document that owns this node.

Panics

Panics if the node is currently mutability borrowed.

fn parent(&self) -> Option<Node>

Returns a parent node, unless this node is the root of the tree.

This method also returns NodeType::Root.

Panics

Panics if the node is currently mutability borrowed.

fn parent_element<T>(&self, tag_name: T) -> Option<Node> where TagName: From<T>

Returns a parent element with selected tag name.

Returns None if this node is the root of the tree or there is no parent nodes with such tag name.

Panics

Panics if any of the parent nodes is currently mutability borrowed.

fn has_parent(&self) -> bool

Returns true if node has parent node.

This method ignores root node.

Panics

Panics if the node is currently mutability borrowed.

Examples

use svgdom::Document;

let doc = Document::from_data(
b"<svg>
    <rect/>
</svg>").unwrap();

let svg = doc.first_child().unwrap();
let rect = svg.first_child().unwrap();
assert_eq!(svg.has_parent(), false);
assert_eq!(rect.has_parent(), true);

fn children(&self) -> Children

Returns an iterator to this node’s children.

Panics

Panics if the node is currently mutability borrowed.

fn has_children(&self) -> bool

Returns true is this node has children nodes.

Panics

Panics if the node is currently mutability borrowed.

fn first_child(&self) -> Option<Node>

Returns a reference to the first child of this node, unless it has no child.

Panics

Panics if the node is currently mutability borrowed.

fn last_child(&self) -> Option<Node>

Returns a reference to the last child of this node, unless it has no child.

Panics

Panics if the node is currently mutability borrowed.

fn previous_sibling(&self) -> Option<Node>

Returns a reference to the previous sibling of this node, unless it is a first child.

Panics

Panics if the node is currently mutability borrowed.

fn next_sibling(&self) -> Option<Node>

Returns a reference to the previous sibling of this node, unless it is a first child.

Panics

Panics if the node is currently mutability borrowed.

fn same_node(&self, other: &Node) -> bool

Returns whether two references point to the same node.

fn detach(&self)

Detaches a node from its parent and siblings. Children are not affected.

Panics

Panics if the node or one of its adjoining nodes is currently borrowed.

fn remove(&self)

Removes this node and all it children from the tree.

Same as detach(), but also unlinks all linked nodes and attributes.

Panics

Panics if the node or one of its adjoining nodes or any children node is currently borrowed.

fn append(&self, new_child: &Node)

Appends a new child to this node, after existing children.

Panics

Panics if the node, the new child, or one of their adjoining nodes is currently borrowed.

fn prepend(&self, new_child: Node)

Prepends a new child to this node, before existing children.

Panics

Panics if the node, the new child, or one of their adjoining nodes is currently borrowed.

fn insert_after(&self, new_sibling: Node)

Insert a new sibling after this node.

Panics

Panics if the node, the new sibling, or one of their adjoining nodes is currently borrowed.

fn insert_before(&self, new_sibling: Node)

Insert a new sibling before this node.

Panics

Panics if the node, the new sibling, or one of their adjoining nodes is currently borrowed.

fn node_type(&self) -> NodeType

Returns node's type.

You can't change type of the node. Only create new one.

Panics

Panics if the node is currently mutability borrowed.

fn text(&self) -> Option<Ref<String>>

Returns a text data of the node, if there are any.

Nodes with Element type can't contain text data.

Panics

Panics if the node is currently mutability borrowed.

fn has_text_children(&self) -> bool

Returns true if there are any children text nodes.

This method is recursive.

Panics

Panics if the node or any descendants nodes are currently mutability borrowed.

Examples

use svgdom::Document;

let doc = Document::from_data(
b"<svg>
    <g>
        <text>Some text</text>
    </g>
    <rect/>
</svg>").unwrap();

let svg = doc.first_child().unwrap();
let g = svg.first_child().unwrap();
assert_eq!(g.has_text_children(), true);

let text = g.first_child().unwrap();
assert_eq!(text.has_text_children(), true);

let rect = g.next_sibling().unwrap();
assert_eq!(rect.has_text_children(), false);

fn set_id<S: Into<String>>(&self, id: S)

Sets an ID of the element.

Only element nodes can contain ID.

Panics

Panics if the node is currently borrowed.

fn id(&self) -> Ref<String>

Returns an ID of the element node.

Panics

Panics if the node is currently mutability borrowed.

fn has_id(&self) -> bool

Returns true if node has a not empty ID.

Panics

Panics if the node is currently mutability borrowed.

fn is_element(&self) -> bool

Returns true if node has Element type.

Shorthand for node.node_type() == NodeType::Element.

Panics

Panics if the node is currently mutability borrowed.

fn set_tag_name<T>(&self, tag_name: T) where TagName: From<T>

Sets a tag name of the element node.

Only element nodes can contain tag name.

Panics

Panics if the node is currently borrowed.

fn tag_name(&self) -> Option<Ref<TagName>>

Returns a tag name of the element node.

Panics

Panics if the node is currently mutability borrowed.

fn tag_id(&self) -> Option<ElementId>

Returns a tag name id of the SVG element node.

Panics

Panics if the node is currently mutability borrowed.

fn is_tag_id(&self, eid: ElementId) -> bool

Returns true if node has the same tag name id as supplied.

Panics

Panics if the node is currently mutability borrowed.

fn is_tag_name(&self, tag_name: &TagName) -> bool

Returns true if node has the same tag name as supplied.

Panics

Panics if the node is currently mutability borrowed.

fn has_child_with_tag_name(&self, tag_name: &TagName) -> bool

Returns true if node has a direct child with the same tag name as supplied.

Panics

Panics if the node is currently mutability borrowed.

fn set_attribute<T>(&self, id: AttributeId, value: T) where AttributeValue: From<T>

Inserts new SVG attribute into attributes list.

This method will overwrite an existing attribute with the same id.

Use it to insert/create new attributes. For existing attributes use Node::set_attribute_object().

You can't use this method to set referenced attributes. Use Node::set_link_attribute() instead.

Panics

Panics if the node is currently borrowed.

fn set_attribute_object(&self, attr: Attribute)

Inserts new SVG attribute into attributes list.

This method will overwrite an existing attribute with the same id.

Panics

• Panics if the node is currently borrowed.
• Panics if attribute has a Link value. Use Node::set_link_attribute() for such attributes.

fn set_link_attribute(&self, id: AttributeId, node: Node) -> Result<(), Error>

Inserts new referenced SVG attribute into attributes list.

This method will overwrite an existing attribute with the same id.

Panics

Panics if the node is currently borrowed.

Examples

use svgdom::{Document, ValueId};
use svgdom::AttributeId as AId;
use svgdom::ElementId as EId;

// Create simple document.
let doc = Document::new();
let gradient = doc.create_element(EId::LinearGradient);
let rect = doc.create_element(EId::Rect);

doc.append(&gradient);
doc.append(&rect);

gradient.set_id("lg1");
rect.set_id("rect1");

// Set `fill` attribute value to `none`.
// For now everything like in any other XML DOM library.
rect.set_attribute(AId::Fill, ValueId::None);

// Now we want to fill our rect with gradient.
// To do this we need to set link attribute:
rect.set_link_attribute(AId::Fill, gradient.clone()).unwrap();

// Now our fill attribute has a link to `gradient` node.
// Not as text, aka `url(#lg1)`, but actual reference.

// This adds support for fast checking of elements usage. Which is very useful.

// `gradient` is now used, since we link it.
assert_eq!(gradient.is_used(), true);
// Also, we can check how many elements are uses this `gradient`.
assert_eq!(gradient.uses_count(), 1);
// And even get this elements:
assert_eq!(gradient.linked_nodes().next().unwrap(), rect);

// `rect` is unused, because no one has referenced attribute that has link to it.
assert_eq!(rect.is_used(), false);

// Now, if we set other attribute value, `gradient` will be automatically unlinked.
rect.set_attribute(AId::Fill, ValueId::None);
// No one uses it anymore.
assert_eq!(gradient.is_used(), false);

fn linked_nodes(&self) -> LinkAttributes

Returns iterator over linked nodes.

Panics

Panics if the node is currently mutability borrowed.

fn find_reference_attribute(&self, node: &Node) -> Option<AttributeId>

Returns AttributeId of the first available node in current node's attributes.

Panics

Panics if the node is currently mutability borrowed.

fn attribute_value(&self, id: AttributeId) -> Option<AttributeValue>

Returns copy of attribute value by id.

Use it only for simple AttributeValue types, and not for String and Path, since their copying will be very expensive.

Prefer Node::attributes().

Panics

Panics if the node is currently mutability borrowed.

fn attribute(&self, id: AttributeId) -> Option<Attribute>

Returns copy of attribute by id.

Use it only for attributes with simple AttributeValue types, and not for String and Path, since their copying will be very expensive.

Prefer Node::attributes().

Panics

Panics if the node is currently mutability borrowed.

fn attributes(&self) -> Ref<Attributes>

Returns a reference to Attributes of current the node.

Panics

Panics if the node is currently mutability borrowed.

fn attributes_mut(&self) -> RefMut<Attributes>

Returns a mutable reference to Attributes of current the node.

Panics

Panics if the node is currently borrowed.

fn parent_attribute(&self, id: AttributeId) -> Option<Attribute>

Returns first occurrence of the selected AttributeId from it's parents.

This function will check all parent, not only direct parent.

Examples

use svgdom::{Document, TagName, ElementId, AttributeId, Attribute};
use svgdom::types::Color;

let doc = Document::from_data(
b"<svg stroke='blue'>
    <g fill='red'>
        <rect/>
    </g>
</svg>").unwrap();

let rect = doc.first_child().unwrap().child_by_tag_name(&TagName::Id(ElementId::Rect)).unwrap();
assert_eq!(rect.parent_attribute(AttributeId::Fill).unwrap(),
           Attribute::new(AttributeId::Fill, Color::new(255, 0, 0)));
assert_eq!(rect.parent_attribute(AttributeId::Stroke).unwrap(),
           Attribute::new(AttributeId::Stroke, Color::new(0, 0, 255)));
assert_eq!(rect.parent_attribute(AttributeId::Filter).is_some(), false);

fn has_attribute(&self, id: AttributeId) -> bool

Returns true if node has attribute with such id.

Panics

Panics if the node is currently mutability borrowed.

fn has_visible_attribute(&self, id: AttributeId) -> bool

Returns true if node has attribute with such id and this attribute is visible.

Panics

Panics if the node is currently mutability borrowed.

fn has_attributes(&self, ids: &[AttributeId]) -> bool

Returns true if node has any of the provided attributes.

Panics

Panics if the node is currently mutability borrowed.

fn has_attribute_with_value<T>(&self, id: AttributeId, value: T) -> bool where AttributeValue: From<T>

Returns true if node has attribute with such id and such value.

Panics

Panics if the node is currently mutability borrowed.

fn remove_attribute(&self, id: AttributeId)

Removes an attribute from the node.

It will also unlink it, if it was an referenced attribute.

Panics

Panics if the node is currently borrowed.

fn remove_attributes(&self, ids: &[AttributeId])

Removes attributes from the node.

Panics

Panics if the node is currently borrowed.

fn unknown_attributes(&self) -> Ref<HashMap<String, String>>

Returns a reference to an unknown attributes object.

Panics

Panics if the node is currently mutability borrowed.

fn unknown_attributes_mut(&self) -> RefMut<HashMap<String, String>>

Returns a mutable reference to an unknown attributes object.

Panics

Panics if the node is currently borrowed.

fn is_used(&self) -> bool

Returns true if current node is linked to any of DOM nodes.

See Node::set_link_attribute() for details.

Panics

Panics if the node is currently mutability borrowed.

fn uses_count(&self) -> usize

Returns number of the nodes, which is linked to this node.

See Node::set_link_attribute() for details.

Panics

Panics if the node is currently mutability borrowed.

fn is_referenced(&self) -> bool

Returns true if the current node is referenced.

Referenced elements is elements that does not rendered by itself, rather defines rendering properties for other.

List: altGlyphDef, clipPath, cursor, filter, linearGradient, marker, mask, pattern, radialGradient and symbol.

Details: https://www.w3.org/TR/SVG/struct.html#Head

Examples

use svgdom::Document;

let doc = Document::from_data(b"<svg><linearGradient/></svg>").unwrap();
let mut iter = doc.descendants();
assert_eq!(iter.next().unwrap().is_referenced(), false); // svg
assert_eq!(iter.next().unwrap().is_referenced(), true); // linearGradient

fn is_basic_shape(&self) -> bool

Returns true if the current node is a basic shape.

List: rect, circle, ellipse, line, polyline, polygon.

Details: https://www.w3.org/TR/SVG/shapes.html

Examples

use svgdom::Document;

let doc = Document::from_data(b"<svg><rect/></svg>").unwrap();
let mut iter = doc.descendants();
assert_eq!(iter.next().unwrap().is_basic_shape(), false); // svg
assert_eq!(iter.next().unwrap().is_basic_shape(), true); // rect

fn child_by_tag_name(&self, tag_name: &TagName) -> Option<Node>

Returns Node if current node contains child with selected TagName.

This function is recursive. Current node excluded.

Examples

use svgdom::{Document, TagName, ElementId};

let doc = Document::from_data(
b"<svg>
    <g>
        <rect/>
    </g>
    <myelem/>
</svg>").unwrap();

let svg = doc.first_child().unwrap();
// current node will be skipped
assert_eq!(svg.child_by_tag_name(&TagName::Id(ElementId::Svg)).is_some(), false);
// we'll get true since current method is recursive
assert_eq!(svg.child_by_tag_name(&TagName::Id(ElementId::Rect)).is_some(), true);
// check for not existing element
assert_eq!(svg.child_by_tag_name(&TagName::Id(ElementId::Path)).is_some(), false);
// check for non-svg element
assert_eq!(svg.child_by_tag_name(&TagName::from("myelem")).is_some(), true);

fn child_by_tag_id(&self, id: ElementId) -> Option<Node>

Returns Node if current node contains child with selected ElementId.

Shorthand for Node::child_by_tag_name(&TagName::Id(id)).

fn descendants(&self) -> Descendants

Returns an iterator over descendant elements.

Examples

use svgdom::{Document, ElementId};

let doc = Document::from_data(
b"<!--comment-->
<svg>
  <g>
    <nonsvg/>
    <rect/>
  </g>
  <text>Text</text>
  <nonsvg/>
</svg>").unwrap();

let mut iter = doc.descendants();
assert_eq!(iter.next().unwrap().is_tag_id(ElementId::Svg), true);
assert_eq!(iter.next().unwrap().is_tag_id(ElementId::G), true);
assert_eq!(iter.next().unwrap().is_tag_id(ElementId::Rect), true);
assert_eq!(iter.next().unwrap().is_tag_id(ElementId::Text), true);
assert_eq!(iter.next().is_none(), true);

fn descendants_all(&self) -> DescendantsAll

Returns an iterator over descendant nodes.

fn traverse(&self) -> Traverse

Returns an iterator over descendant nodes.

More complex alternative of the Node::descendants_all().

Trait Implementations

impl Clone for Node

Cloning a Node only increments a reference count. It does not copy the data.

fn clone(&self) -> Node

Returns a copy of the value.

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

Performs copy-assignment from source.

impl PartialEq for Node

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

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

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

This method tests for !=.

impl Debug for Node

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

Formats the value using the given formatter.