From ca3f051fbf42b9abf7c22e3f58215cf5010f9727 Mon Sep 17 00:00:00 2001 From: "arseny.kapoulkine" Date: Fri, 24 Sep 2010 05:37:50 +0000 Subject: docs: Removed pugixpath.cpp mentions, updated evaluate_* arguments and added xpath_node ctor clarification, updated custom memory management description, updated CDATA printing information, added wide load_file/save_file documentation, added as_utf8/as_wide string overloads, fixed xml_node::root() complexity git-svn-id: http://pugixml.googlecode.com/svn/trunk@752 99668b35-9821-0410-8761-19e4c4f06640 --- docs/manual/access.html | 4 +--- docs/manual/apiref.html | 47 ++++++++++++++++++++++++++++----------------- docs/manual/dom.html | 48 ++++++++++++++++++++++------------------------ docs/manual/loading.html | 36 +++++++++++++++------------------- docs/manual/saving.html | 50 +++++++++++++++++++----------------------------- docs/manual/xpath.html | 44 ++++++++++++++++++++++++------------------ 6 files changed, 113 insertions(+), 116 deletions(-) (limited to 'docs/manual') diff --git a/docs/manual/access.html b/docs/manual/access.html index 4581583..1accecb 100644 --- a/docs/manual/access.html +++ b/docs/manual/access.html @@ -624,9 +624,7 @@

This function returns the node with type node_document, which is the root node of the document the node belongs to (unless the node - is null, in which case null node is returned). Currently this function has - logarithmic complexity, since it simply finds such ancestor of the given - node which itself has no parent. + is null, in which case null node is returned).

While pugixml supports complex XPath expressions, sometimes a simple path diff --git a/docs/manual/apiref.html b/docs/manual/apiref.html index 24120ad..5e595cf 100644 --- a/docs/manual/apiref.html +++ b/docs/manual/apiref.html @@ -800,7 +800,15 @@ = parse_default, xml_encoding encoding = encoding_auto); -

+ +

  • + xml_parse_result load_file(const wchar_t* + path, + unsigned int + options = + parse_default, + xml_encoding encoding + = encoding_auto);

  • @@ -839,6 +847,17 @@ encoding = encoding_auto) const; +
    • +
  • + bool save_file(const wchar_t* + path, + const char_t* indent + = "\t", unsigned + int flags + = format_default, xml_encoding + encoding = + encoding_auto) + const;

    • @@ -892,6 +911,9 @@ xml_encoding encoding;

    +
  • + xml_parse_result(); +
  • operator bool() const;
    • @@ -1107,23 +1129,12 @@

    Functions:

    -
    +

    + $$ overloads, types * as_utf8 * as_wide + * get_memory_allocation_function + * get_memory_deallocation_function + * set_memory_management_functions +

    diff --git a/docs/manual/dom.html b/docs/manual/dom.html index 2d65070..def86a5 100644 --- a/docs/manual/dom.html +++ b/docs/manual/dom.html @@ -371,9 +371,10 @@

    - All tree functions that work with strings work with either C-style null terminated - strings or STL strings of the selected character type. For example, node - name accessors look like this in char mode: + $$ wording - one may think that child() has a string overload All tree functions + that work with strings work with either C-style null terminated strings or + STL strings of the selected character type. For example, node name accessors + look like this in char mode: 

    const char* xml_node::name() const;
 bool xml_node::set_name(const char* value);
@@ -416,7 +417,12 @@
         performs conversion from UTF-8 to UTF-16/32. Invalid UTF sequences are silently
         discarded upon conversion. str
         has to be a valid string; passing null pointer results in undefined behavior.
+        There are also two overloads with the same semantics which accept a string
+        as an argument:
       
    
+
    std::string as_utf8(const std::wstring& str);
+std::wstring as_wide(const std::string& str);
+
    
 
    
@@ -493,7 +499,7 @@
         guarantees beyond the ones provided by callback.
       
    
-        XPath functions may throw xpath_exception
+        $$ XPath functions may throw xpath_exception
         on parsing error; also, XPath implementation uses STL, and thus may throw
         i.e. std::bad_alloc in low memory conditions. Still,
         XPath functions provide strong exception guarantee.
@@ -514,10 +520,10 @@
         functions
 
 
    
-          All memory for tree structure/data is allocated via globally specified
-          functions, which default to malloc/free. You can set your own allocation
-          functions with set_memory_management functions. The function interfaces
-          are the same as that of malloc/free:
+          All memory for tree structure, tree data and XPath objects is allocated
+          via globally specified functions, which default to malloc/free. You can
+          set your own allocation functions with set_memory_management functions.
+          The function interfaces are the same as that of malloc/free:
         
    typedef void* (*allocation_function)(size_t size);
 typedef void (*deallocation_function)(void* ptr);
@@ -533,13 +539,15 @@
 
    
           Allocation function is called with the size (in bytes) as an argument and
           should return a pointer to memory block with alignment that is suitable
-          for pointer storage and size that is greater or equal to the requested
-          one. If the allocation fails, the function has to return null pointer (throwing
-          an exception from allocation function results in undefined behavior). Deallocation
-          function is called with the pointer that was returned by the previous call
-          or with a null pointer; null pointer deallocation should be handled as
-          a no-op. If memory management functions are not thread-safe, library thread
-          safety is not guaranteed.
+          for storage of primitive types (usually a maximum of pointer and double types alignment is sufficient) and
+          size that is greater or equal to the requested one. If the allocation fails,
+          the function has to return null pointer (throwing an exception from allocation
+          function results in undefined behavior).
+        
    
+
    
+          Deallocation function is called with the pointer that was returned by the
+          previous call; it is never called with a null pointer. If memory management
+          functions are not thread-safe, library thread safety is not guaranteed.
         
    
 
    
           This is a simple example of custom memory management (samples/custom_memory_management.cpp):
@@ -572,16 +580,6 @@
           are destroyed, the new deallocation function will be called with the memory
           obtained by the old allocation function, resulting in undefined behavior.
         
    
-
    
 
    
 [Note]
 
 
    
-
-
-
-
-
-
    [Note]Note
    
-            Currently memory for XPath objects is allocated using default operators
-            new/delete; this will change in the next version.
-          
    
 
 
    
 
    
diff --git a/docs/manual/loading.html b/docs/manual/loading.html
index a3c1515..547b355 100644
--- a/docs/manual/loading.html
+++ b/docs/manual/loading.html
@@ -65,20 +65,27 @@
 
    
-
    
-        The most common source of XML data is files; pugixml provides a separate
-        function for loading XML document from file:
+
    
+        The most common source of XML data is files; pugixml provides dedicated functions
+        for loading XML document from file:
       
    
 
    xml_parse_result xml_document::load_file(const char* path, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
+xml_parse_result xml_document::load_file(const wchar_t* path, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
 
    
 
    
-        This function accepts file path as its first argument, and also two optional
+        These functions accept file path as its first argument, and also two optional
         arguments, which specify parsing options (see  Parsing options) and
         input data encoding (see  Encodings). The path has the target
         operating system format, so it can be a relative or absolute one, it should
         have the delimiters of target system, it should have the exact case if target
-        file system is case-sensitive, etc. File path is passed to system file opening
-        function as is.
+        file system is case-sensitive, etc.
+      
    
+
    
+        File path is passed to system file opening function as is in case of the
+        first function (which accepts const
+        char* path); the second function either uses
+        a special file opening function if it is provided by the runtime library
+        or converts the path to UTF-8 and uses the system file opening function.
       
    
 
    
         load_file destroys the existing
@@ -88,20 +95,6 @@
         (i.e. last successfully parsed position in the input file, if parsing fails).
         See  Handling parsing errors for error handling details.
       
    
-
    
-
-
-
-
-
-
    [Note]Note
    
-          As of version 0.9, there is no function for loading XML document from wide
-          character path. Unfortunately, there is no portable way to do this; the
-          version 1.0 will provide such function only for platforms with the corresponding
-          functionality. You can use stream-loading functions as a workaround if
-          your STL implementation can open file streams via wchar_t
-          paths.
-        
    
 
    
         This is an example of loading XML document from file (samples/load_file.cpp):
       
    
@@ -297,7 +290,7 @@
 
    
-
    
+
    
         All document loading functions return the parsing result via xml_parse_result object. It contains parsing
         status, the offset of last successfully parsed character from the beginning
         of the source stream, and the encoding of the source stream:
@@ -308,6 +301,7 @@
     ptrdiff_t offset;
     xml_encoding encoding;
 
+    xml_parse_result();
     operator bool() const;
     const char* description() const;
 };
diff --git a/docs/manual/saving.html b/docs/manual/saving.html
index e12b31d..584cb2c 100644
--- a/docs/manual/saving.html
+++ b/docs/manual/saving.html
@@ -56,35 +56,38 @@
       For proper output, make sure all node and attribute names are set to meaningful
       values.
     
    
-
    
-
-
-
-
-
-
    [Caution]Caution
    
-        Currently the content of CDATA sections is not escaped, so CDATA sections
-        with values that contain "]]>"
-        will result in malformed document. This will be fixed in version 1.0.
-      
    
+
    
+      CDATA sections with values that contain "]]>"
+      are split into several sections as follows: section with value "pre]]>post" is written as <![CDATA[pre]]]]><![CDATA[>post]]>.
+      While this alters the structure of the document (if you load the document after
+      saving it, there will be two CDATA sections instead of one), this is the only
+      way to escape CDATA contents.
+    
    
 
    
 
    
-
    
-        If you want to save the whole document to a file, you can use the following
-        function:
+
    
+        If you want to save the whole document to a file, you can use one of the
+        following functions:
       
    
 
    bool xml_document::save_file(const char* path, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
+bool xml_document::save_file(const wchar_t* path, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
 
    
 
    
-        This function accepts file path as its first argument, and also three optional
+        These functions accept file path as its first argument, and also three optional
         arguments, which specify indentation and other output options (see  Output options)
         and output data encoding (see  Encodings). The path has the target
         operating system format, so it can be a relative or absolute one, it should
         have the delimiters of target system, it should have the exact case if target
-        file system is case-sensitive, etc. File path is passed to system file opening
-        function as is.
+        file system is case-sensitive, etc.
+      
    
+
    
+        File path is passed to system file opening function as is in case of the
+        first function (which accepts const
+        char* path); the second function either uses
+        a special file opening function if it is provided by the runtime library
+        or converts the path to UTF-8 and uses the system file opening function.
       
    
 
    
         save_file opens the target
@@ -96,19 +99,6 @@
         handle as the only constructor argument and then calling save;
         see  Saving document via writer interface for writer interface details.
       
    
-
    
-
-
-
-
-
-
    [Note]Note
    
-          As of version 0.9, there is no function for saving XML document to wide
-          character paths. Unfortunately, there is no portable way to do this; the
-          version 1.0 will provide such function only for platforms with the corresponding
-          functionality. You can use stream-saving functions as a workaround if your
-          STL implementation can open file streams via wchar_t paths.
-        
    
 
    
         This is a simple example of saving XML document to file (samples/save_file.cpp):
       
    
diff --git a/docs/manual/xpath.html b/docs/manual/xpath.html
index 731a969..513bb90 100644
--- a/docs/manual/xpath.html
+++ b/docs/manual/xpath.html
@@ -54,6 +54,9 @@
       at tizag.com, and the XPath
       1.0 specification.
     
    
+
    
+      $$
+    
    
 
    
@@ -120,9 +123,11 @@
         You can also create XPath nodes with one of tree constructors: the default
         constructor, the constructor that takes node argument, and the constructor
         that takes attribute and node arguments (in which case the attribute must
-        belong to the attribute list of the node). However, usually you don't need
-        to create your own XPath node objects, since they are returned to you via
-        selection functions.
+        belong to the attribute list of the node). The constructor from xml_node is implicit, so you can usually
+        pass xml_node to functions
+        that expect xpath_node. Apart
+        from that you usually don't need to create your own XPath node objects, since
+        they are returned to you via selection functions.
       
    
         XPath expressions operate not on single nodes, but instead on node sets.
@@ -309,20 +314,21 @@
 
    
         You can evaluate the query using one of the following functions:
       
    
-
    bool xpath_query::evaluate_boolean(const xml_node& n) const;
-double xpath_query::evaluate_number(const xml_node& n) const;
-string_t xpath_query::evaluate_string(const xml_node& n) const;
-xpath_node_set xpath_query::evaluate_node_set(const xml_node& n) const;
+
    bool xpath_query::evaluate_boolean(const xpath_node& n) const;
+double xpath_query::evaluate_number(const xpath_node& n) const;
+string_t xpath_query::evaluate_string(const xpath_node& n) const;
+xpath_node_set xpath_query::evaluate_node_set(const xpath_node& n) const;
 
    
 
    
-        All functions take the context node as an argument, compute the expression
-        and return the result, converted to the requested type. By XPath specification,
-        value of any type can be converted to boolean, number or string value, but
-        no type other than node set can be converted to node set. Because of this,
-        evaluate_boolean, evaluate_number and evaluate_string
-        always return a result, but evaluate_node_set
-        throws an xpath_exception
-        if the return type is not node set.
+        $$ exception, evaluate_string nostl All functions take the context node as
+        an argument, compute the expression and return the result, converted to the
+        requested type. By XPath specification, value of any type can be converted
+        to boolean, number or string value, but no type other than node set can be
+        converted to node set. Because of this, evaluate_boolean,
+        evaluate_number and evaluate_string always return a result,
+        but evaluate_node_set throws
+        an xpath_exception if the
+        return type is not node set.
       
    
 
    
 
    
 [Note]
 
    
@@ -370,7 +376,7 @@
  Error handling
    
-        As of version 0.9, all XPath errors result in thrown exceptions. The errors
+        $$ As of version 0.9, all XPath errors result in thrown exceptions. The errors
         can arise during expression compilation or node set evaluation. In both cases,
         an xpath_exception object
         is thrown. This is an exception object that implements std::exception
@@ -379,8 +385,8 @@
 
    virtual const char* xpath_exception::what() const throw();
 
    
-        This function returns the error message. Currently it is impossible to get
-        the exact place where query compilation failed. This functionality, along
+        $$ This function returns the error message. Currently it is impossible to
+        get the exact place where query compilation failed. This functionality, along
         with optional error handling without exceptions, will be available in version
         1.0.
       
    
@@ -464,7 +470,7 @@
           
    
-        Some of these incompatibilities will be fixed in version 1.0.
+        $$ Some of these incompatibilities will be fixed in version 1.0.
       
    
-- 
cgit v1.2.3