Modifying document data

-pugixml 1.2 manual \| +pugixml 1.4 manual \| Overview \| Installation \| Document: @@ -28,15 +28,16 @@ - Modifying document data +Modifying document data - - Setting node data - Setting attribute data - Adding nodes/attributes - Removing nodes/attributes - Working with text contents - Cloning nodes/attributes + + Setting node data + Setting attribute data + Adding nodes/attributes + Removing nodes/attributes + Working with text contents + Cloning nodes/attributes + Assembling document from fragments The document in pugixml is fully mutable: you can completely change the document @@ -60,11 +61,12 @@ - Setting node data +Setting node 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 + + 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 a name or value, node_element and node_declaration nodes always have a name but never have a value, node_pcdata, @@ -96,31 +98,31 @@ This is an example of setting node name and value (samples/modify_base.cpp): - pugi::xml_node node = doc.child("node"); -// change node name -std::cout << node.set_name("notnode"); +// change node name +std::cout << node.set_name("notnode"); std::cout << ", new node name: " << node.name() << std::endl; -// change comment text -std::cout << doc.last_child().set_value("useless comment"); +// change comment text +std::cout << doc.last_child().set_value("useless comment"); std::cout << ", new comment text: " << doc.last_child().value() << std::endl; -// we can't change value of the element or name of the comment -std::cout << node.set_value("1") << ", " << doc.last_child().set_name("2") << std::endl; +// we can't change value of the element or name of the comment +std::cout << node.set_value("1") << ", " << doc.last_child().set_name("2") << std::endl; - Setting attribute data +Setting attribute data - - All attributes have name and value, both of which are strings (value may - be empty). You can set them with the following functions: + + All + attributes have name and value, both of which are strings (value may be empty). + You can set them with the following functions: bool xml_attribute::set_name(const char_t* rhs); bool xml_attribute::set_value(const char_t* rhs); @@ -142,6 +144,8 @@ bool xml_attribute::set_value(unsigned int rhs); bool xml_attribute::set_value(double rhs); bool xml_attribute::set_value(bool rhs); +bool xml_attribute::set_value(long long rhs); +bool xml_attribute::set_value(unsigned long long rhs); The above functions convert the argument to string and then call the base @@ -167,14 +171,14 @@	Note
- There are no portable 64-bit types in C++, so there is no corresponding - `set_value` function. If - your platform has a 64-bit integer, you can easily write such a function - yourself. + `set_value` overloads with + `long long` + type are only available if your platform has reliable support for the type, + including string conversions.

+ For convenience, all set_value functions have the corresponding assignment operators:

These operators simply call the right set_value @@ -193,20 +199,19 @@ This is an example of setting attribute name and value (samples/modify_base.cpp):

- Adding nodes/attributes +Adding nodes/attributes

- Nodes and attributes do not exist without a document tree, so you can't create +

+ 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:

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

Adding fails if the target node is null;

samples/modify_add.cpp

// add node with some name
-pugi::xml_node node = doc.append_child("node");
+// add node with some name
+pugi::xml_node node = doc.append_child("node");
 
-// add description node with text child
-pugi::xml_node descr = node.append_child("description");
+// add description node with text child
+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("param", descr);
+// add param node before the description
+pugi::xml_node param = node.insert_child_before("param", descr);
 
-// add attributes to param node
-param.append_attribute("name") = "version";
+// add attributes to param node
+param.append_attribute("name") = "version";
 param.append_attribute("value") = 1.1;
 param.insert_attribute_after("type", param.attribute("name")) = "float";
 
@@ -333,10 +338,11 @@

- Removing nodes/attributes +Removing nodes/attributes

- If you do not want your document to contain some node or attribute, you can +

+ If + you do not want your document to contain some node or attribute, you can remove it with one of the following functions:

bool xml_node::remove_attribute(const xml_attribute& a);
@@ -350,7 +356,7 @@
         attributes) from the document, and returns the operation result. Removing
         fails if one of the following is true:
       
-
+
 
             The node the function is called on is null;
           
@@ -388,18 +394,17 @@
         This is an example of removing attributes/nodes from the document (samples/modify_remove.cpp):
       
 
-        
 
-// remove description node with the whole subtree
-pugi::xml_node node = doc.child("node");
+// remove description node with the whole subtree
+pugi::xml_node node = doc.child("node");
 node.remove_child("description");
 
-// remove id attribute
-pugi::xml_node param = node.child("param");
+// remove id attribute
+pugi::xml_node param = node.child("param");
 param.remove_attribute("value");
 
-// we can also remove nodes/attributes by handles
-pugi::xml_attribute id = param.attribute("name");
+// we can also remove nodes/attributes by handles
+pugi::xml_attribute id = param.attribute("name");
 param.remove_attribute(id);
 
 
@@ -407,7 +412,7 @@
 
 
 
- Working with text contents
+Working with text contents
 
 
         pugixml provides a special class, xml_text,
@@ -416,8 +421,8 @@
         documentation for accessing document data; this section describes
         the modification interface of xml_text.
       
-
-        Once you have an xml_text
+

+        Once you have an xml_text
         object, you can set the text contents using the following function:
       
 bool xml_text::set(const char_t* rhs);
@@ -434,14 +439,16 @@
         an element node, this function creates the PCDATA child node if necessary
         (i.e. if the element node does not have a PCDATA/CDATA child already).
       
-
-        In addition to a string function, several functions are provided for handling
-        text with numbers and booleans as contents:
+

+        In addition to a string function, several
+        functions are provided for handling text with numbers and booleans as contents:
       
 bool xml_text::set(int rhs);
 bool xml_text::set(unsigned int rhs);
 bool xml_text::set(double rhs);
 bool xml_text::set(bool rhs);
+bool xml_text::set(long long rhs);
+bool xml_text::set(unsigned long long rhs);
 
 
         The above functions convert the argument to string and then call the base
@@ -450,8 +457,8 @@
         functions. You can refer to documentation
         for the attribute functions for details.
       
-
-        For convenience, all set
+

+        For convenience, all set
         functions have the corresponding assignment operators:
       
 xml_text& xml_text::operator=(const char_t* rhs);
@@ -459,6 +466,8 @@
 xml_text& xml_text::operator=(unsigned int rhs);
 xml_text& xml_text::operator=(double rhs);
 xml_text& xml_text::operator=(bool rhs);
+xml_text& xml_text::operator=(long long rhs);
+xml_text& xml_text::operator=(unsigned long long rhs);
 
 
         These operators simply call the right set
@@ -471,30 +480,29 @@
         object to modify text contents (samples/text.cpp):
       
 
-        
 
-// change project version
-project.child("version").text() = 1.2;
+// change project version
+project.child("version").text() = 1.2;
 
-// add description element and set the contents
-// note that we do not have to explicitly add the node_pcdata child
-project.append_child("description").text().set("a test project");
+// add description element and set the contents
+// note that we do not have to explicitly add the node_pcdata child
+project.append_child("description").text().set("a test project");
 
 
       
 
 
 
- Cloning nodes/attributes
+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
-        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:
+

+        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 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);
@@ -528,7 +536,7 @@
         for more information. There are additional caveats specific to cloning
         functions:
       
-
+
 
             Cloning null handles results in operation failure;
           
@@ -551,7 +559,6 @@
         node cloning and usage of other document modification functions:
       
 
-        
 
 bool load_preprocess(pugi::xml_document& doc, const char* path);
 
@@ -563,23 +570,23 @@
         {
             pugi::xml_node include = child;
 
-            // load new preprocessed document (note: ideally this should handle relative paths)
-            const char* path = include.value();
+            // load new preprocessed document (note: ideally this should handle relative paths)
+            const char* path = include.value();
 
             pugi::xml_document doc;
             if (!load_preprocess(doc, path)) return false;
 
-            // insert the comment marker above include directive
-            node.insert_child_before(pugi::node_comment, include).set_value(path);
+            // insert the comment marker above include directive
+            node.insert_child_before(pugi::node_comment, include).set_value(path);
 
-            // copy the document above the include directive (this retains the original order!)
-            for (pugi::xml_node ic = doc.first_child(); ic; ic = ic.next_sibling())
+            // copy the document above the include directive (this retains the original order!)
+            for (pugi::xml_node ic = doc.first_child(); ic; ic = ic.next_sibling())
             {
                 node.insert_copy_before(ic, include);
             }
 
-            // remove the include node and move to the next child
-            child = child.next_sibling();
+            // remove the include node and move to the next child
+            child = child.next_sibling();
 
             node.remove_child(include);
         }
@@ -596,18 +603,83 @@
 
 bool load_preprocess(pugi::xml_document& doc, const char* path)
 {
-    pugi::xml_parse_result result = doc.load_file(path, pugi::parse_default | pugi::parse_pi); // for <?include?>
-    
+    pugi::xml_parse_result result = doc.load_file(path, pugi::parse_default | pugi::parse_pi); // for <?include?>
+
     return result ? preprocess(doc) : false;
 }
 
 
       
 
+
+
+Assembling document from fragments
+
+
+        pugixml provides several ways to assemble
+        an XML document from other XML documents. Assuming there is a set of document
+        fragments, represented as in-memory buffers, the implementation choices are
+        as follows:
+      
+
+            Use a temporary document to parse the data from a string, then clone
+            the nodes to a destination node. For example:
+          
+bool append_fragment(pugi::xml_node target, const char* buffer, size_t size)
+{
+    pugi::xml_document doc;
+    if (!doc.load_buffer(buffer, size)) return false;
+
+    for (pugi::xml_node child = doc.first_child(); child; child = child.next_sibling())
+        target.append_copy(child);
+}
+
+
+            Cache the parsing step - instead of keeping in-memory buffers, keep document
+            objects that already contain the parsed fragment:
+          
+bool append_fragment(pugi::xml_node target, const pugi::xml_document& cached_fragment)
+{
+    for (pugi::xml_node child = cached_fragment.first_child(); child; child = child.next_sibling())
+        target.append_copy(child);
+}
+
+
+            Use xml_node::append_buffer directly:
+          
+xml_parse_result xml_node::append_buffer(const void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
+
+
+        The first method is more convenient, but slower than the other two. The relative
+        performance of append_copy
+        and append_buffer depends
+        on the buffer format - usually append_buffer
+        is faster if the buffer is in native encoding (UTF-8 or wchar_t, depending
+        on PUGIXML_WCHAR_MODE). At
+        the same time it might be less efficient in terms of memory usage - the implementation
+        makes a copy of the provided buffer, and the copy has the same lifetime as
+        the document - the memory used by that copy will be reclaimed after the document
+        is destroyed, but no sooner. Even deleting all nodes in the document, including
+        the appended ones, won't reclaim the memory.
+      
+
+        append_buffer behaves in
+        the same way as xml_document::load_buffer
+        - the input buffer is a byte buffer, with size in bytes; the buffer is not
+        modified and can be freed after the function returns.
+      
+
+        Since append_buffer
+        needs to append child nodes to the current node, it only works if the current
+        node is either document or element node. Calling append_buffer
+        on a node with any other type results in an error with status_append_invalid_root
+        status.
+      
+
 
 
-
@@ -615,7 +687,7 @@
 

 Copyright © 2012 Arseny Kapoulkine
+ Copyright © 2014 Arseny Kapoulkine
         Distributed under the MIT License
       
 
 

 
-pugixml 1.2 manual |
+pugixml 1.4 manual |
 		Overview |
 		Installation |
 		Document:
-- 
cgit v1.2.3

- Modifying document data +Modifying document data

- Setting node data +Setting node data

- Setting attribute data +Setting attribute data

- Adding nodes/attributes +Adding nodes/attributes

- Removing nodes/attributes +Removing nodes/attributes

- Working with text contents +Working with text contents

- Cloning nodes/attributes +Cloning nodes/attributes

+Assembling document from fragments +