Modifying document data

As discussed before, nodes can have name and value, both of which are strings. - Depending on node type, name or value may be absent. node_document - nodes do not have name or value, node_element - and node_declaration nodes - always have a name but never have a value, node_pcdata, - node_cdata and node_comment nodes never have a name but - always have a value (it may be empty though), node_pi + Depending on node type, name or value may be absent. node_document + nodes do not have a name or value, node_element + and node_declaration nodes always + have a name but never have a value, node_pcdata, + node_cdata, node_comment + and node_doctype nodes never have a name + but always have a value (it may be empty though), node_pi nodes always have a name and a value (again, value may be empty). In order to set node's name or value, you can use the following functions:

- There is no equivalent of child_value + There is no equivalent of child_value function for modifying text children of the node.

@@ -185,7 +186,7 @@ These operators simply call the right set_value function and return the attribute they're called on; the return value of set_value is ignored, so - errors are not detected. + errors are ignored.

This is an example of setting attribute name and value (samples/modify_base.cpp): @@ -214,36 +215,48 @@

- Nodes and attributes do not exist outside of document tree, so you can't - create them without adding them to some document. A node or attribute can - be created at the end of node/attribute list or before/after some other node: +

+ Nodes and attributes do not exist without a document tree, so you can't create + them without adding them to some document. A node or attribute can be created + at the end of node/attribute list or before/after some other node:

xml_attribute xml_node::append_attribute(const char_t* name); +xml_attribute xml_node::prepend_attribute(const char_t* name); xml_attribute xml_node::insert_attribute_after(const char_t* name, const xml_attribute& attr); xml_attribute xml_node::insert_attribute_before(const char_t* name, const xml_attribute& attr); xml_node xml_node::append_child(xml_node_type type = node_element); +xml_node xml_node::prepend_child(xml_node_type type = node_element); xml_node xml_node::insert_child_after(xml_node_type type, const xml_node& node); xml_node xml_node::insert_child_before(xml_node_type type, const xml_node& node); + +xml_node xml_node::append_child(const char_t* name); +xml_node xml_node::prepend_child(const char_t* name); +xml_node xml_node::insert_child_after(const char_t* name, const xml_node& node); +xml_node xml_node::insert_child_before(const char_t* name, const xml_node& node);

append_attribute and append_child create a new node/attribute at the end of the corresponding list of the node the method is called on; - insert_attribute_after, + prepend_attribute and prepend_child create a new node/attribute + at the beginning of the list; insert_attribute_after, insert_attribute_before, insert_child_after and insert_attribute_before add the node/attribute - before or after specified node/attribute. + before or after the specified node/attribute.

Attribute functions create an attribute with the specified name; you can specify the empty name and change the name later if you want to. Node functions - create the node with the specified type; since node type can't be changed, - you have to know the desired type beforehand. Also note that not all types - can be added as children; see below for clarification. + with the type argument create + the node with the specified type; since node type can't be changed, you have + to know the desired type beforehand. Also note that not all types can be + added as children; see below for clarification. Node functions with the + name argument create the + element node (node_element) with the + specified name.

- All functions return the handle to newly created object on success, and null + All functions return the handle to the created object on success, and null handle on failure. There are several reasons for failure:

- Only node_element nodes - can contain attributes, so attribute adding fails if node is not an element; + Only node_element nodes can contain + attributes, so attribute adding fails if node is not an element;
- Only node_document and - node_element nodes can - contain children, so child node adding fails if target node is not an - element or a document; + Only node_document and node_element + nodes can contain children, so child node adding fails if the target + node is not an element or a document;
- node_document and node_null nodes can not be inserted - as children, so passing node_document - or node_null value as - type results in operation failure; + node_document and node_null + nodes can not be inserted as children, so passing node_document + or node_null value as type results in operation failure;
- node_declaration nodes - can only be added as children of the document node; attempt to insert - declaration node as a child of an element node fails; + node_declaration nodes can only + be added as children of the document node; attempt to insert declaration + node as a child of an element node fails;
Adding node/attribute results in memory allocation, which may fail;
- Insertion functions fail if the specified node or attribute is not in - the target node's children/attribute list. + Insertion functions fail if the specified node or attribute is null or + is not in the target node's children/attribute list.

// add node with some name -pugi::xml_node node = doc.append_child(); -node.set_name("node"); +pugi::xml_node node = doc.append_child("node"); // add description node with text child -pugi::xml_node descr = node.append_child(); -descr.set_name("description"); +pugi::xml_node descr = node.append_child("description"); descr.append_child(pugi::node_pcdata).set_value("Simple node"); // add param node before the description -pugi::xml_node param = node.insert_child_before(pugi::node_element, descr); -param.set_name("param"); +pugi::xml_node param = node.insert_child_before("param", descr); // add attributes to param node param.append_attribute("name") = "version"; @@ -400,29 +408,32 @@

Cloning nodes/attributes

With the help of previously described functions, it is possible to create trees with any contents and structure, including cloning the existing data. However since this is an often needed operation, pugixml provides built-in node/attribute cloning facilities. Since nodes and attributes do not exist - outside of document tree, you can't create a standalone copy - you have to + without a document tree, you can't create a standalone copy - you have to immediately insert it somewhere in the tree. For this, you can use one of the following functions:

xml_attribute xml_node::append_copy(const xml_attribute& proto);
+xml_attribute xml_node::prepend_copy(const xml_attribute& proto);
 xml_attribute xml_node::insert_copy_after(const xml_attribute& proto, const xml_attribute& attr);
 xml_attribute xml_node::insert_copy_before(const xml_attribute& proto, const xml_attribute& attr);
+
 xml_node xml_node::append_copy(const xml_node& proto);
+xml_node xml_node::prepend_copy(const xml_node& proto);
 xml_node xml_node::insert_copy_after(const xml_node& proto, const xml_node& node);
 xml_node xml_node::insert_copy_before(const xml_node& proto, const xml_node& node);

These functions mirror the structure of append_child, - insert_child_before and related - functions - they take the handle to the prototype object, which is to be - cloned, insert a new attribute/node at the appropriate place, and then copy - the attribute data or the whole node subtree to the new object. The functions - return the handle to the resulting duplicate object, or null handle on failure. + prepend_child, insert_child_before and related functions + - they take the handle to the prototype object, which is to be cloned, insert + a new attribute/node at the appropriate place, and then copy the attribute + data or the whole node subtree to the new object. The functions return the + handle to the resulting duplicate object, or null handle on failure.

The attribute is copied along with the name and value; the node is copied @@ -445,7 +456,7 @@

Node cloning starts with insertion of the node of the same type as that of the prototype; for this reason, cloning functions can not be directly - used to clone entire documents, since node_document + used to clone entire documents, since node_document is not a valid insertion type. The example below provides a workaround.

@@ -524,7 +535,8 @@

Adding nodes/attributes

Cloning nodes/attributes