Simbody
3.7
|
An element has (1) a tagword, (2) a map of (name,value) pairs called attributes, and (3) a list of child nodes. More...
Public Member Functions | |
Construction and destruction | |
As discussed elsewhere, elements come in two varieties: value elements and compound elements. New value elements can be created easily since they are essentially just a name,value pair. Compound elements require a series of method calls to create the Element node and then add child nodes to it. In either case you may want to add attributes also. | |
Element () | |
Create an empty Element handle; this is suitable only for holding references to other Elements. More... | |
Element (const String &tagWord, const String &value="") | |
Create a value element that uses the given tag word but is not yet part of any XML document, and optionally give it an inital value. More... | |
template<class T > | |
Element (const String &tagWord, const T &value) | |
Create a new value element and set its initial value to the text equivalent of any type T for which a conversion construction String(T) is allowed (generally any type for which a stream insertion operator<<() exists). More... | |
Element | clone () const |
The clone() method makes a deep copy of this Element and its children and returns a new orphan Element with the same contents; ordinary assignment and copy construction are shallow. More... | |
const String & | getElementTag () const |
Get the element tag word. More... | |
void | setElementTag (const String &tag) |
Change the tag word that is used to bracket this element. More... | |
void | insertNodeBefore (const node_iterator &pos, Node node) |
Insert a node into the list of this Element's children, just before the node pointed to by the supplied iterator (or at the end if the iterator is node_end()). More... | |
void | insertNodeAfter (const node_iterator &pos, Node node) |
Insert a node into the list of this Element's children, just after the node pointed to by the supplied iterator (or at the end if the iterator is node_end()). More... | |
void | appendNode (Node node) |
This is an abbreviation for insertNodeAfter(node_end(), node); . More... | |
void | eraseNode (const node_iterator &deleteThis) |
Delete the indicated node, which must be a child of this element, and must not be node_end(). More... | |
Node | removeNode (const node_iterator &removeThis) |
Remove the indicated node from this element without erasing it, returning it as an orphan Node. More... | |
Value elements | |
As described elsewhere, value elements are those that have no child elements and only a single Text node, whose contents can be considered as the element's value. Methods in this section allow you to work conveniently with value elements, getting direct access to the value string or interpreting it as some other type. You can easily modify the value by obtaining a writable refence to the String object that holds it. We provide methods for working with this element's value (if it is a value element) and with an element's children's values (if this element is compound). | |
bool | isValueElement () const |
Determine whether this element qualifies as a "value element", defined as an element containing zero or one Text nodes and no child elements. More... | |
const String & | getValue () const |
Get the text value of this value element. More... | |
String & | updValue () |
Obtain a writable reference to the String containing the value of this value element. More... | |
void | setValue (const String &value) |
Set the text value of this value element. More... | |
template<class T > | |
void | setValueAs (const T &value) |
Set the value of this value element to the text equivalent of any type T for which a conversion construction String(T) is allowed (generally any type for which a stream insertion operator<<() exists). More... | |
template<class T > | |
T | getValueAs () const |
Assuming this is a "value element", convert its text value to the type of the template argument T. More... | |
template<class T > | |
void | getValueAs (T &out) const |
Alternate form of getValueAs() that avoids unnecessary copying and heap allocation for reading in large container objects. More... | |
const String & | getRequiredElementValue (const String &tag) const |
Get the text value of a child value element that must be present in this element. More... | |
String | getOptionalElementValue (const String &tag, const String &def="") const |
Get the text value of a child value element that may be present in this element, otherwise return a default string. More... | |
template<class T > | |
T | getRequiredElementValueAs (const String &tag) const |
Convert the text value of a required child value element to the type of the template argument T. More... | |
template<class T > | |
T | getOptionalElementValueAs (const String &tag, const T &def) const |
Convert the text value of an optional child value element, if present, to the type of the template argument T. More... | |
Attributes | |
You can add, modify, and remove element attributes with the methods in this section. You can work directly with individual attributes by name, or you can iterate through the list of attributes. | |
bool | hasAttribute (const String &name) const |
Return true if this element has an attribute of this name. More... | |
void | setAttributeValue (const String &name, const String &value) |
Set the value of an attribute of this element, creating a new one if this is a new attribute name otherwise modifying an existing one. More... | |
void | eraseAttribute (const String &name) |
Erase an attribute of this element if it exists, otherwise do nothing. More... | |
const String & | getRequiredAttributeValue (const String &name) const |
Get the value of an attribute as a string and throw an error if that attribute is not present. More... | |
template<class T > | |
T | getRequiredAttributeValueAs (const String &name) const |
Convert the text value of a required attribute to the type of the template argument T. More... | |
String | getOptionalAttributeValue (const String &name, const String &def="") const |
Get the value of an attribute as a string if the attribute is present in this element, otherwise return a supplied default value. More... | |
template<class T > | |
T | getOptionalAttributeValueAs (const String &name, const T &def) const |
Convert the value of an optional attribute, if present, from a string to the type of the template argument T. More... | |
Attribute | getRequiredAttribute (const String &name) |
Obtain an Attribute handle referencing a particular attribute of this element; an error will be thrown if no such attribute is present. More... | |
Attribute | getOptionalAttribute (const String &name) |
Obtain an Attribute handle referencing a particular attribute of this element specified by name, or an empty handle if no such attribute is present. More... | |
Array_< Attribute > | getAllAttributes () |
Return an array containing Attribute handles referencing all the attributes of this element. More... | |
attribute_iterator | attribute_begin () |
For iterating through all the attributes of this element. More... | |
attribute_iterator | attribute_end () const |
This attribute_end() iterator indicates the end of a sequence of attributes. More... | |
Compound elements | |
Many elements contain child nodes, including other elements. When there is just a single child Text node and no child elements, we call the element a "value element" and it is easiest to work with using the methods in the "Value elements" section. When there are child elements and/or multiple Text nodes, the element is called a "compound element" and you need a way to iterate and recurse through its contents. The methods in this section support looking through all contained nodes, nodes of specified types, element nodes, or element nodes with a specified tags. You can obtain handles to child Nodes or Elements and then iterate through those recursively. | |
bool | hasElement (const String &tag) const |
Return true if this element has a child element with this tag. More... | |
bool | hasNode (NodeType allowed=AnyNodes) const |
See if this element has any child nodes, or any child nodes of the type(s) allowed by the NodeType filter if one is supplied. More... | |
Element | getRequiredElement (const String &tag) |
Get a reference to a child element that must be present in this element. More... | |
Element | getOptionalElement (const String &tag) |
Get a reference to a child element that may be present in this element; otherwise return an invalid Element handle. More... | |
Array_< Element > | getAllElements (const String &tag="") |
Return an array containing Element handles referencing all the immediate child elements contained in this element, or all the child elements of a particular type (that is, with a given tag word). More... | |
Array_< Node > | getAllNodes (NodeType allowed=AnyNodes) |
Return an array containing Node handles referencing all the immediate child nodes contained in this element, or all the child nodes of a particular type or types. More... | |
element_iterator | element_begin (const String &tag="") |
For iterating through the immediate child elements of this element, or the child elements that have the indicated tag if one is supplied. More... | |
element_iterator | element_end () const |
This element_end() iterator indicates the end of any sequence of elements regardless of the tag restriction on the iterator being used. More... | |
node_iterator | node_begin (NodeType allowed=AnyNodes) |
For iterating through the immediate child nodes of this element, or the child nodes of the type(s) allowed by the NodeType filter if one is supplied. More... | |
node_iterator | node_end () const |
This node_end() iterator indicates the end of any sequence of nodes regardless of the NodeType restriction on the iterator being used. More... | |
Public Member Functions inherited from SimTK::Xml::Node | |
bool | operator== (const Node &other) const |
Comparing Nodes for equality means asking if the two Node handles are referring to exactly the same object; two different nodes that happen to have the same properties will not test equal by this criteria. More... | |
bool | operator!= (const Node &other) const |
Inequality test using same criteria as operator==(). More... | |
Node () | |
Create an empty Node handle that can be used to hold a reference to any kind of Node. More... | |
Node (const Node &src) | |
Copy constructor is shallow; that is, this handle will refer to the same node as the source. More... | |
Node & | operator= (const Node &src) |
Copy assignment is shallow; the handle is first cleared and then will refer to the same node as the source. More... | |
Node | clone () const |
The clone() method makes a deep copy of this Node and its children and returns a new orphan Node with the same contents; ordinary assignment and copy construction is shallow. More... | |
~Node () | |
The Node handle destructor does not recover heap space so if you create orphan nodes and then don't put them in a document there will be a memory leak unless you explicitly destruct them first with clearOrphan(). More... | |
void | clear () |
This method restores the Node handle to its default-constructed state but does not recover any heap space; use clearOrphan() if you know this node was never put into a document. More... | |
void | clearOrphan () |
This method explicitly frees the heap space for an orphan node that was created but never inserted into a document. More... | |
NodeType | getNodeType () const |
Get the Xml::NodeType of this node. More... | |
String | getNodeTypeAsString () const |
Get the Node type as a string; an empty handle returns "NoNode". More... | |
bool | isValid () const |
Return true if this Node handle is referencing some node, false if the Node handle is empty. More... | |
bool | isTopLevelNode () const |
Return true if this Node is owned by the top-level Xml document, false if the Node is owned by an Element or is an orphan, or if the Node handle is empty. More... | |
bool | isOrphan () const |
Return true if this Node is an orphan, meaning that it is not empty, but is not owned by any element or top-level document. More... | |
bool | hasParentElement () const |
Return true if this node has a parent, i.e. More... | |
Element | getParentElement () |
Return a handle referencing this node's parent if it has one, otherwise throws an error; check first with hasParentElement() if you aren't sure. More... | |
const String & | getNodeText () const |
Return a text value associated with this Node (not including its child nodes if any); the behavior depends on the NodeType. More... | |
void | writeToString (String &out, bool compact=false) const |
Serialize this node (and everything it contains) to the given String. More... | |
Static Public Member Functions | |
Conversion to Element from Node | |
If you have a handle to a Node, such as would be returned by a node_iterator, you can check whether that Node is an Element and if so cast it to one. | |
static bool | isA (const Node &) |
Test whether a given Node is an element node. More... | |
static const Element & | getAs (const Node &node) |
Recast a Node to a const Element, throwing an error if the Node is not actually an element node. More... | |
static Element & | getAs (Node &node) |
Recast a writable Node to a writable Element, throwing an error if the Node is not actually an element node. More... | |
Friends | |
class | Node |
class | element_iterator |
Related Functions | |
(Note that these are not member functions.) | |
template<class T > | |
Xml::Element | toXmlElement (const T &thing, const std::string &name) |
Default implementation of serialization to an XML element for objects whose class does not define a member function toXmlElement(name) . More... | |
template<class T > | |
auto | toXmlElementHelper (const T &thing, const std::string &name, bool) -> decltype(std::declval< T >().toXmlElement(name)) |
Helper function for toXmlElement() that selects the member function if it exists. More... | |
template<class T > | |
auto | toXmlElementHelper (const T &thing, const std::string &name, int) -> Xml::Element |
Helper function for toXmlElement() that selects the free function if no member function exists. More... | |
template<class T > | |
void | fromXmlElement (T &thing, Xml::Element &elt, const std::string &requiredName="") |
Default implementation of deserialization from an XML element for objects whose class does not define a member function fromXmlElement(elt,name) . More... | |
template<class T > | |
auto | fromXmlElementHelper (T &thing, Xml::Element &elt, const std::string &requiredTag, bool) -> decltype(std::declval< T >().fromXmlElement(elt, requiredTag)) |
Helper function for fromXmlElement() that selects the member function if it exists. More... | |
template<class T > | |
auto | fromXmlElementHelper (T &thing, Xml::Element &elt, const std::string &requiredTag, int) -> void |
Helper function for fromXmlElement() that selects the free function if no member function exists. More... | |
Related Functions inherited from SimTK::Xml::Node | |
std::ostream & | operator<< (std::ostream &o, const Node &xmlNode) |
Output a "pretty printed" textual representation of the given XML node (and all its contents) to an std::ostream. More... | |
An element has (1) a tagword, (2) a map of (name,value) pairs called attributes, and (3) a list of child nodes.
The tag word, which begins with an underscore or a letter, can serve as either the type or the name of the element depending on context. The nodes can be comments, unknowns, text, and child elements (recursively). It is common for "leaf" elements (elements with no child elements) to be supplied simply for their values, for example mass might be provided via an element "<mass> 29.3 </mass>". We call such elements "value elements" since they have a uniquely identifiable value similar to that of attributes. Value elements have no more than one text node. They may have attributes, and may also have comment and unknown nodes but they cannot have any child elements. This class provides a special set of methods for dealing with value nodes very conveniently; they will fail if you attempt to use them on an element that is not a value element.
|
inline |
Create an empty Element handle; this is suitable only for holding references to other Elements.
Create a value element that uses the given tag word but is not yet part of any XML document, and optionally give it an inital value.
Note that although you provide the initial value as a string, you can access it as any type T to which that string can be converted, using the getValueAs<T>() templatized method.
If no initial value is provided, then the element will be empty so would print as "<tagWord />". If you provide a value (say "contents") here or add one later, it will print as "<tagWord>contents</tagWord>". In general you can add child elements and other node types with subsequent method calls; that would change this element from a value element to a compound element.
|
inline |
Create a new value element and set its initial value to the text equivalent of any type T for which a conversion construction String(T) is allowed (generally any type for which a stream insertion operator<<() exists).
Element SimTK::Xml::Element::clone | ( | ) | const |
const String& SimTK::Xml::Element::getElementTag | ( | ) | const |
Get the element tag word.
This may represent the name or type of the element depending on context.
void SimTK::Xml::Element::setElementTag | ( | const String & | tag | ) |
Change the tag word that is used to bracket this element.
void SimTK::Xml::Element::insertNodeBefore | ( | const node_iterator & | pos, |
Node | node | ||
) |
Insert a node into the list of this Element's children, just before the node pointed to by the supplied iterator (or at the end if the iterator is node_end()).
The iterator must refer to a node that is a child of this Element. This Element takes over ownership of the node which must not already have a parent.
void SimTK::Xml::Element::insertNodeAfter | ( | const node_iterator & | pos, |
Node | node | ||
) |
Insert a node into the list of this Element's children, just after the node pointed to by the supplied iterator (or at the end if the iterator is node_end()).
The iterator must refer to a node that is a child of this Element. This Element takes over ownership of the node which must not already have a parent.
|
inline |
This is an abbreviation for insertNodeAfter(node_end(), node);
.
void SimTK::Xml::Element::eraseNode | ( | const node_iterator & | deleteThis | ) |
Delete the indicated node, which must be a child of this element, and must not be node_end().
The node will be removed from this element and deleted. The iterator is invalid after this call; be sure not to use it again. Also, there must not be any handles referencing the now-deleted node.
Node SimTK::Xml::Element::removeNode | ( | const node_iterator & | removeThis | ) |
Remove the indicated node from this element without erasing it, returning it as an orphan Node.
The node must be a child of this element, and must not be node_end(). The node will be removed from this element and returned as an orphan. The iterator is invalid after this call; be sure not to use it again.
bool SimTK::Xml::Element::isValueElement | ( | ) | const |
Determine whether this element qualifies as a "value element", defined as an element containing zero or one Text nodes and no child elements.
You can treat a value element as you would an attribute – it can be viewed as having a single value, which is just the value of its lone Text node (or a null string if it doesn't have any text).
const String& SimTK::Xml::Element::getValue | ( | ) | const |
Get the text value of this value element.
An error will be thrown if this is not a "value element". See the comments for this class for the definition of a "value element".
String& SimTK::Xml::Element::updValue | ( | ) |
Obtain a writable reference to the String containing the value of this value element.
An error will be thrown if this is not a value element. If the element was initially empty and didn't contain a Text node, one will be added to it here with a null-string value so that we can return a reference to it.
void SimTK::Xml::Element::setValue | ( | const String & | value | ) |
Set the text value of this value element.
An error will be thrown if this is not a value element. If the element was initially empty and didn't contain a Text node, one will be added to it here so that we have a place to hold the value.
|
inline |
Set the value of this value element to the text equivalent of any type T for which a conversion construction String(T) is allowed (generally any type for which a stream insertion operator<<() exists).
|
inline |
Assuming this is a "value element", convert its text value to the type of the template argument T.
It is an error if the text can not be converted, in its entirety, to a single object of type T. (But note that type T may be a container of some sort, like a Vector or Array.)
T | A type that can be read from a stream using the ">>" operator. |
|
inline |
Alternate form of getValueAs() that avoids unnecessary copying and heap allocation for reading in large container objects.
Get the text value of a child value element that must be present in this element.
The child is identified by its tag; if there is more than one this refers to the first one. Then the element is expected to contain either zero or one Text nodes; if none we'll return a null string, otherwise the value of the Text node. Thus an element like "<tag>stuff</tag>" will have the value "stuff". An error will be thrown if either the element is not found or it is not a "value element".
|
inline |
Get the text value of a child value element that may be present in this element, otherwise return a default string.
If the child element is found, it must be a "value element" as defined above.
|
inline |
Convert the text value of a required child value element to the type of the template argument T.
It is an error if the element is present but is not a value element, or if the text cannot be converted, in its entirety, to a single object of type T. (But note that type T may be a container of some sort, like a Vector or Array.)
T | A type that can be read from a stream using the ">>" operator. |
[in] | tag | The tag of the required child text element. |
|
inline |
Convert the text value of an optional child value element, if present, to the type of the template argument T.
It is an error if the child element is present but is not a value element, or if the text cannot be converted, in its entirety, to a single object of type T. (But note that type T may be a container of some sort, like a Vector or Array.) If the child element is not present, then return a supplied default value of type T.
T | A type that can be read from a stream with operator ">>". |
[in] | tag | The tag of the optional child element. |
[in] | def | The value of type T to return if child element is missing. |
bool SimTK::Xml::Element::hasAttribute | ( | const String & | name | ) | const |
Return true if this element has an attribute of this name.
Set the value of an attribute of this element, creating a new one if this is a new attribute name otherwise modifying an existing one.
void SimTK::Xml::Element::eraseAttribute | ( | const String & | name | ) |
Erase an attribute of this element if it exists, otherwise do nothing.
If you need to know if the attribute exists, use hasAttribute(). There is no removeAttribute() that orphans an existing Attribute, but you can easily recreate one with the same name and value.
Get the value of an attribute as a string and throw an error if that attribute is not present.
|
inline |
Convert the text value of a required attribute to the type of the template argument T.
It is an error if the text can not be converted, in its entirety, to a single object of type T. (But note that type T may be a container of some sort, like a Vec3.)
T | A type that can be read from a stream using the ">>" operator. |
|
inline |
Get the value of an attribute as a string if the attribute is present in this element, otherwise return a supplied default value.
[in] | name | The name of the optional attribute. |
[in] | def | The string to return if the attribute is missing. |
|
inline |
Convert the value of an optional attribute, if present, from a string to the type of the template argument T.
It is an error if the text can not be converted, in its entirety, to a single object of type T. (But note that type T may be a container of some sort, like a Vec3.) If the attribute is not present, then return a supplied default value of type T.
T | A type that can be read from a stream with operator ">>". |
[in] | name | The name of the optional attribute. |
[in] | def | The value of type T to return if the attribute is missing. |
Obtain an Attribute handle referencing a particular attribute of this element; an error will be thrown if no such attribute is present.
Obtain an Attribute handle referencing a particular attribute of this element specified by name, or an empty handle if no such attribute is present.
Return an array containing Attribute handles referencing all the attributes of this element.
Attributes are returned in the order that they appear in the element tag. Attribute names within a tag are unique; if the source document had repeated attribute names only the last one to appear is retained and that's the only one we'll find here. This is just a shortcut for
attribute_iterator SimTK::Xml::Element::attribute_begin | ( | ) |
For iterating through all the attributes of this element.
If there are no attributes then the returned attribute_iterator tests equal to attribute_end().
attribute_iterator SimTK::Xml::Element::attribute_end | ( | ) | const |
This attribute_end() iterator indicates the end of a sequence of attributes.
bool SimTK::Xml::Element::hasElement | ( | const String & | tag | ) | const |
Return true if this element has a child element with this tag.
See if this element has any child nodes, or any child nodes of the type(s) allowed by the NodeType filter if one is supplied.
Get a reference to a child element that must be present in this element.
The child is identified by its tag; if there is more than one only the first one is returned. If you want to see all children with this tag, use getAllElements() or use an element_iterator.
Return an array containing Element handles referencing all the immediate child elements contained in this element, or all the child elements of a particular type (that is, with a given tag word).
Elements are returned in the order they are seen in the document. This is just a shortcut for
Return an array containing Node handles referencing all the immediate child nodes contained in this element, or all the child nodes of a particular type or types.
Nodes are returned in the order they are seen in the document. This is just a shortcut for
element_iterator SimTK::Xml::Element::element_begin | ( | const String & | tag = "" | ) |
For iterating through the immediate child elements of this element, or the child elements that have the indicated tag if one is supplied.
If there are no children with the allowed tag then the returned element_iterator tests equal to element_end().
element_iterator SimTK::Xml::Element::element_end | ( | ) | const |
This element_end() iterator indicates the end of any sequence of elements regardless of the tag restriction on the iterator being used.
node_iterator SimTK::Xml::Element::node_begin | ( | NodeType | allowed = AnyNodes | ) |
For iterating through the immediate child nodes of this element, or the child nodes of the type(s) allowed by the NodeType filter if one is supplied.
If there are no children of the allowed types then the returned node_iterator tests equal to node_end().
node_iterator SimTK::Xml::Element::node_end | ( | ) | const |
This node_end() iterator indicates the end of any sequence of nodes regardless of the NodeType restriction on the iterator being used.
|
static |
|
friend |
|
friend |
|
related |
Default implementation of serialization to an XML element for objects whose class does not define a member function toXmlElement(name)
.
A name can be provided for this value; by default that will be used as the element's tag word so make sure it is a legal XML tag. If name
is empty we'll use <value>
as the tag. This default implementation uses Simbody's stream serialization method SimTK::writeUnformatted<T>()
. Specialize this free function or provide a member function if that doesn't provide the behavior you want.
If type T
provides a member function or specialization of this method, it may choose any tag word, in which case the given name if any should be added as an attribute name="name"
("value" is not used in that case if name
is empty).
A helper function toXmlElementHelper<T>
is available for invoking the member function T::toXmlElement()
if it exists, otherwise the appropriate specialization of this free function. Invoke the helper like this:
The third parameter true
is a dummy that allows prioritization of the member function over the free function if both exist, using SFINAE.
|
related |
Helper function for toXmlElement() that selects the member function if it exists.
|
related |
Helper function for toXmlElement() that selects the free function if no member function exists.
|
related |
Default implementation of deserialization from an XML element for objects whose class does not define a member function fromXmlElement(elt,name)
.
The name is optional but if provided then we require that the given element has that name. For this default implementation, we'll expect the element's tag word to be the given name; specializations or member functions are free to use a different tag with the name as an attribute.
This default implementation uses Simbody's stream deserialization method SimTK::readUnformatted<T>()
. Specialize this free function or provide a member function if that doesn't provide the behavior you want.
A helper function fromXmlElementHelper<T>
is available for invoking the member function T::fromXmlElement()
if it exists, otherwise the appropriate specialization of this free function. Invoke the helper like this:
The last parameter true
is a dummy that allows prioritization of the member function over the free function if both exist, using SFINAE.
|
related |
Helper function for fromXmlElement() that selects the member function if it exists.
|
related |
Helper function for fromXmlElement() that selects the free function if no member function exists.