Xml Node¶

1

import "std/text/xml-node";

XmlNode struct¶

Represents a node in an XML document.

Element nodes carry a tag name, ordered attributes and ordered child nodes (which may themselves be elements or text). Text nodes carry only the decoded character data. Children are owned as heap pointers so the parsed tree is reached via XmlNode*.

Destroying a node recursively destroys everything below it, so a whole tree is released with a single deleteXmlNode call on its root. Accessors like getChild and findChild hand out borrowed pointers that stay owned by their parent, while addChild takes ownership of what it is given.

Note that the root cannot simply be held in a heap XmlNode* and left to the compiler: the heap qualifier only emits a raw deallocation when the variable goes out of scope and never runs the destructor of the pointee, so the children below the root would be lost.

Parsing lives in "std/text/xml/xml-parser" and serialization in "std/text/xml/xml-serializer", so programs only pull in what they use.

Constructors¶

ctor¶

1

public p XmlNode.ctor(XmlNodeKind kind = XmlNodeKind::XML_ELEMENT)

Construct an empty XML node of the given kind

Parameters

dtor¶

1

public p XmlNode.dtor()

Destruct the XML node, releasing every child node and attribute it owns. Since the children are destroyed the same way, this tears down the whole subtree below the node.

Methods¶

getKind¶

1

public f<XmlNodeKind> XmlNode.getKind()

Retrieve the kind of the XML node

Returns: XmlNodeKind — Kind of the node

isElement¶

1

public f<bool> XmlNode.isElement()

Check whether the node is an element node

Returns: bool — true if the node is an element, false otherwise

isText¶

1

public f<bool> XmlNode.isText()

Check whether the node is a text node

Returns: bool — true if the node is text, false otherwise

getName¶

1

public f<const String&> XmlNode.getName()

Retrieve the tag name of the element. Panics if the node is not an element.

Returns: const String& — Tag name

setName¶

1

public p XmlNode.setName(const String& name)

Set the tag name of the element. Panics if the node is not an element.

Parameters

getText¶

1

public f<const String&> XmlNode.getText()

Retrieve the character data of the text node. Panics if the node is not a text node.

Returns: const String& — Text content

setText¶

1

public p XmlNode.setText(const String& text)

Set the character data of the text node. Panics if the node is not a text node.

Parameters

getAttributeCount¶

1

public f<unsigned long> XmlNode.getAttributeCount()

Retrieve the number of attributes on the element. Panics if the node is not an element.

Returns: unsigned long — Number of attributes

getAttributeKey¶

1

public f<const String&> XmlNode.getAttributeKey(unsigned long idx)

Retrieve the name of the attribute at the given index, in document order. Panics if the node is not an element.

Parameters

Returns: const String& — Attribute name

getAttributeValue¶

1

public f<const String&> XmlNode.getAttributeValue(unsigned long idx)

Retrieve the value of the attribute at the given index, in document order. Panics if the node is not an element.

Parameters

Returns: const String& — Attribute value

hasAttribute¶

1

public f<bool> XmlNode.hasAttribute(string name)

Check whether the element has an attribute with the given name

Parameters

Returns: bool — true if the attribute exists, false otherwise

getAttribute¶

1

public f<const String&> XmlNode.getAttribute(string name)

Retrieve the value of the attribute with the given name. Panics if the node is not an element or the attribute does not exist.

Parameters

Returns: const String& — Attribute value

addAttribute¶

1

public p XmlNode.addAttribute(const String& name, const String& value)

Append an attribute to the element. Panics if the node is not an element. The caller is responsible for avoiding duplicate attribute names.

Parameters

getChildCount¶

1

public f<unsigned long> XmlNode.getChildCount()

Retrieve the number of child nodes. Panics if the node is not an element.

Returns: unsigned long — Number of child nodes

getChild¶

1

public f<XmlNode*> XmlNode.getChild(unsigned long idx)

Retrieve the child node at the given index. Panics if the node is not an element.

Parameters

Returns: XmlNode* — Pointer to the child node

getChild¶

1

public f<XmlNode*> XmlNode.getChild(unsigned int idx)

Retrieve the child node at the given index. Panics if the node is not an element.

Parameters

Returns: XmlNode* — Pointer to the child node

addChild¶

1

public p XmlNode.addChild(XmlNode* child)

Append a child node to the element. Panics if the node is not an element. The element takes ownership of the heap-allocated child.

Parameters

findChild¶

1

public f<XmlNode*> XmlNode.findChild(string name)

Find the first child element with the given tag name. Returns nil if none exists. Text-node children are ignored.

Parameters

Returns: XmlNode*

hasChild¶

1

public f<bool> XmlNode.hasChild(string name)

Check whether the element has a direct child element with the given tag name

Parameters

Returns: bool — true if such a child exists, false otherwise

getInnerText¶

1

public f<String> XmlNode.getInnerText()

Concatenated text of all direct text-node children, in document order. Useful for elements like <title>Hello</title> where the natural value is the text content.

Returns: String

Functions¶

deleteXmlNode¶

1

public p deleteXmlNode(XmlNode*& node)

Destroys a heap-allocated XML node together with everything it owns and sets the given handle to nil, so releasing a whole tree only takes one call on its root.

Note that this is what sDelete would normally be used for. It cannot be used here, because a node tree is destroyed recursively and the compiler does not emit an explicit dtor that is only reached through sDestruct.

Parameters

XmlNodeKind enum¶

Tag for the variant stored inside an XmlNode.