Added xml_document::document_element function

git-svn-id: http://pugixml.googlecode.com/svn/trunk@768 99668b35-9821-0410-8761-19e4c4f06640

4 files changed, 28 insertions, 1 deletions

diff --git a/docs/manual.qbk b/docs/manual.qbk
index 8fb9564..fe45b30 100644
--- a/docs/manual.qbk
+++ b/docs/manual.qbk
@@ -327,7 +327,8 @@ Finally, here is a complete example of XML document and the corresponding tree r
 Despite the fact that there are several node types, there are only three C++ types representing the tree (`xml_document`, `xml_node`, `xml_attribute`); some operations on `xml_node` are only valid for certain node types. They are described below.
 
 [#xml_document]
-`xml_document` is the owner of the entire document structure; it is a non-copyable class. The interface of `xml_document` consists of loading functions (see [sref manual.loading]), saving functions (see [sref manual.saving]) and the interface of `xml_node`, which allows for document inspection and/or modification. Note that while `xml_document` is a sub-class of `xml_node`, `xml_node` is not a polymorphic type; the inheritance is only used to simplify usage.
+[#xml_document::document_element]
+`xml_document` is the owner of the entire document structure; it is a non-copyable class. The interface of `xml_document` consists of loading functions (see [sref manual.loading]), saving functions (see [sref manual.saving]) and the interface of `xml_node`, which allows for document inspection and/or modification. Note that while `xml_document` is a sub-class of `xml_node`, `xml_node` is not a polymorphic type; the inheritance is only used to simplify usage. You can also use the `document_element` function to get the element node that's the immediate child of the document.
 
 [#xml_document::ctor]
 [#xml_document::dtor]
@@ -1630,6 +1631,7 @@ Major release, featuring many XPath enhancements, wide character filename suppor
     # Added parse_full parse flag mask, which extends parse_default with all node type parsing flags except parse_ws_pcdata
     # Added xml_node::hash_value() and xml_attribute::hash_value() functions for use in hash-based containers
     # Added internal_object() and additional constructor for both xml_node and xml_attribute for easier marshalling (useful for language bindings)
+    # Added xml_document::document_element() function
 
 * Performance improvements:
     # xml_node::root() and xml_node::offset_debug() are now O(1) instead of O(logN)
@@ -2117,6 +2119,9 @@ Classes:
     * `void `[link xml_document::save save]`(xml_writer& writer, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;`
     [lbr]
 
+    * `xml_node `[link xml_document::document_element document_element]`() const;`
+    [lbr]
+
 * `struct `[link xml_parse_result]
     * `xml_parse_status `[link xml_parse_result::status status]`;`
     * `ptrdiff_t `[link xml_parse_result::offset offset]`;`
diff --git a/src/pugixml.cpp b/src/pugixml.cpp
index 1142930..f53ce1d 100644
--- a/src/pugixml.cpp
+++ b/src/pugixml.cpp
@@ -4595,6 +4595,15 @@ namespace pugi
 		return true;
 	}
 
+    xml_node xml_document::document_element() const
+    {
+		for (xml_node_struct* i = _root->first_child; i; i = i->next_sibling)
+			if ((i->header & xml_memory_page_type_mask) + 1 == node_element)
+                return xml_node(i);
+
+        return xml_node();
+    }
+
 #ifndef PUGIXML_NO_STL
 	std::string PUGIXML_FUNCTION as_utf8(const wchar_t* str)
 	{
diff --git a/src/pugixml.hpp b/src/pugixml.hpp
index 9b0d0d6..81fc6c3 100644
--- a/src/pugixml.hpp
+++ b/src/pugixml.hpp
@@ -764,6 +764,9 @@ namespace pugi
 		// Save XML to file
 		bool save_file(const char* path, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
 		bool save_file(const wchar_t* path, const char_t* indent = PUGIXML_TEXT("\t"), unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
+
+        // Get document element
+        xml_node document_element() const;
 	};
 
 #ifndef PUGIXML_NO_XPATH
diff --git a/tests/test_document.cpp b/tests/test_document.cpp
index d6163e2..e424836 100644
--- a/tests/test_document.cpp
+++ b/tests/test_document.cpp
@@ -866,3 +866,13 @@ TEST(document_load_exceptions)
     CHECK(thrown);
 }
 #endif
+
+TEST_XML_FLAGS(document_element, "<?xml version='1.0'?><node><child/></node><!---->", parse_default | parse_declaration | parse_comments)
+{
+    CHECK(doc.document_element() == doc.child(STR("node")));
+}
+
+TEST_XML_FLAGS(document_element_absent, "<!---->", parse_comments)
+{
+    CHECK(doc.document_element() == xml_node());
+}