Merge pull request #22 from vadz/node-dump-submit

Make dumping xml::nodes more convenient.

docs/manual/mainpage.doxygen

@@ -47,6 +47,7 @@
   - @subpage xslt_apply_we
 - @subpage tips
   - @subpage tips_lifetime
+  - @subpage tips_debugging
 - @subpage whatnext
 
 

docs/manual/tips.doxygen

@@ -54,4 +54,17 @@ other xml::node objects. This is why the lifetime of the xml::node is
 limited to the lifetime of the xml::node::iterator.
 </pre>
 
+@section tips_debugging Debugging
+
+Any xml::node object can be easily examined by dumping it to a string using its
+<code>note_to_string()</code> method or by outputting it into any standard
+stream:
+@code
+    xml::node n = ...;
+    std::cout << "Contents of the node: " << n;
+@endcode
+
+Notice that the note_to_string() function can even be called from a debugger to
+see the contents of the node during a debugging session.
+
 */

include/xmlwrapp/node.h

@@ -839,13 +839,22 @@ class XMLWRAPP_API node
     template <typename T> void sort (T compare)
         { impl::sort_callback<T> cb(compare); sort_fo(cb); }
 
+    /**
+        Convert the node and all its children into XML text and return the
+        string containing them.
+
+        @since 0.8.0
+     */
+    std::string node_to_string() const;
+
     /**
         Convert the node and all its children into XML text and set the given
         string to that text.
 
         @param xml The string to set the node's XML data to.
      */
-    void node_to_string(std::string& xml) const;
+    void node_to_string(std::string& xml) const
+        { xml = node_to_string(); }
 
     /**
         Write a node and all of its children to the given stream.

src/libxml/node.cxx

@@ -849,7 +849,7 @@ void node::sort_fo(cbfo_node_compare& cb)
 }
 
 
-void node::node_to_string(std::string& xml) const
+std::string node::node_to_string() const
 {
     node2doc n2d(pimpl_->xmlnode_);
     xmlDocPtr doc = n2d.get_doc();
@@ -860,16 +860,16 @@ void node::node_to_string(std::string& xml) const
     xmlDocDumpFormatMemory(doc, &xml_string, &xml_string_length, 1);
 
     xmlchar_helper helper(xml_string);
+    std::string xml;
     if (xml_string_length)
         xml.assign(helper.get(), xml_string_length);
+    return xml;
 }
 
 
 std::ostream& operator<<(std::ostream &stream, const xml::node& n)
 {
-    std::string xmldata;
-    n.node_to_string(xmldata);
-    stream << xmldata;
+    stream << n.node_to_string();
     return stream;
 }