summaryrefslogtreecommitdiff
path: root/docs/manual.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'docs/manual.adoc')
-rw-r--r--docs/manual.adoc472
1 files changed, 245 insertions, 227 deletions
diff --git a/docs/manual.adoc b/docs/manual.adoc
index 6ffd844..856d1b3 100644
--- a/docs/manual.adoc
+++ b/docs/manual.adoc
@@ -252,16 +252,16 @@ NOTE: In that example `PUGIXML_API` is inconsistent between several source files
pugixml is written in standard-compliant C{plus}{plus} with some compiler-specific workarounds where appropriate. pugixml is compatible with the C{plus}{plus}11 standard, but does not require C{plus}{plus}11 support. Each version is tested with a unit test suite (with code coverage about 99%) on the following platforms:
* Microsoft Windows:
- * Borland C{plus}{plus} Compiler 5.82
- * Digital Mars C{plus}{plus} Compiler 8.51
- * Intel C{plus}{plus} Compiler 8.0, 9.0 x86/x64, 10.0 x86/x64, 11.0 x86/x64
- * Metrowerks CodeWarrior 8.0
- * Microsoft Visual C{plus}{plus} 6.0, 7.0 (2002), 7.1 (2003), 8.0 (2005) x86/x64, 9.0 (2008) x86/x64, 10.0 (2010) x86/x64, 11.0 (2011) x86/x64/ARM, 12.0 (2013) x86/x64/ARM and some CLR versions
- * MinGW (GCC) 3.4, 4.4, 4.5, 4.6 x64
+** Borland C{plus}{plus} Compiler 5.82
+** Digital Mars C{plus}{plus} Compiler 8.51
+** Intel C{plus}{plus} Compiler 8.0, 9.0 x86/x64, 10.0 x86/x64, 11.0 x86/x64
+** Metrowerks CodeWarrior 8.0
+** Microsoft Visual C{plus}{plus} 6.0, 7.0 (2002), 7.1 (2003), 8.0 (2005) x86/x64, 9.0 (2008) x86/x64, 10.0 (2010) x86/x64, 11.0 (2011) x86/x64/ARM, 12.0 (2013) x86/x64/ARM and some CLR versions
+** MinGW (GCC) 3.4, 4.4, 4.5, 4.6 x64
* Linux (GCC 4.4.3 x86/x64, GCC 4.8.1 x64, Clang 3.2 x64)
* FreeBSD (GCC 4.2.1 x86/x64)
-* Apple MacOSX (GCC 4.0.1 x86/x64/PowerPC)
+* Apple MacOSX (GCC 4.0.1 x86/x64/PowerPC, Clang 3.5 x64)
* Sun Solaris (sunCC x86/x64)
* Microsoft Xbox 360
* Nintendo Wii (Metrowerks CodeWarrior 4.1)
@@ -804,14 +804,14 @@ include::samples/load_options.cpp[tags=code]
[#xml_encoding]
pugixml supports all popular Unicode encodings (UTF-8, UTF-16 (big and little endian), UTF-32 (big and little endian); UCS-2 is naturally supported since it's a strict subset of UTF-16) and handles all encoding conversions. Most loading functions accept the optional parameter `encoding`. This is a value of enumeration type `xml_encoding`, that can have the following values:
-* [anchor encoding_auto] means that pugixml will try to guess the encoding based on source XML data. The algorithm is a modified version of the one presented in Appendix F.1 of XML recommendation; it tries to match the first few bytes of input data with the following patterns in strict order:
- * If first four bytes match UTF-32 BOM (Byte Order Mark), encoding is assumed to be UTF-32 with the endianness equal to that of BOM;
- * If first two bytes match UTF-16 BOM, encoding is assumed to be UTF-16 with the endianness equal to that of BOM;
- * If first three bytes match UTF-8 BOM, encoding is assumed to be UTF-8;
- * If first four bytes match UTF-32 representation of [^<], encoding is assumed to be UTF-32 with the corresponding endianness;
- * If first four bytes match UTF-16 representation of [^<?], encoding is assumed to be UTF-16 with the corresponding endianness;
- * If first two bytes match UTF-16 representation of [^<], encoding is assumed to be UTF-16 with the corresponding endianness (this guess may yield incorrect result, but it's better than UTF-8);
- * Otherwise encoding is assumed to be UTF-8.
+* [anchor encoding_auto] means that pugixml will try to guess the encoding based on source XML data. The algorithm is a modified version of the one presented in http://www.w3.org/TR/REC-xml/#sec-guessing-no-ext-info[Appendix F.1 of XML recommendation]; it tries to match the first few bytes of input data with the following patterns in strict order:
+** If first four bytes match UTF-32 BOM (Byte Order Mark), encoding is assumed to be UTF-32 with the endianness equal to that of BOM;
+** If first two bytes match UTF-16 BOM, encoding is assumed to be UTF-16 with the endianness equal to that of BOM;
+** If first three bytes match UTF-8 BOM, encoding is assumed to be UTF-8;
+** If first four bytes match UTF-32 representation of [^<], encoding is assumed to be UTF-32 with the corresponding endianness;
+** If first four bytes match UTF-16 representation of [^<?], encoding is assumed to be UTF-16 with the corresponding endianness;
+** If first two bytes match UTF-16 representation of [^<], encoding is assumed to be UTF-16 with the corresponding endianness (this guess may yield incorrect result, but it's better than UTF-8);
+** Otherwise encoding is assumed to be UTF-8.
* [anchor encoding_utf8] corresponds to UTF-8 encoding as defined in the Unicode standard; UTF-8 sequences with length equal to 5 or 6 are not standard and are rejected.
* [anchor encoding_utf16_le] corresponds to little-endian UTF-16 encoding as defined in the Unicode standard; surrogate pairs are supported.
@@ -1553,7 +1553,7 @@ The failure conditions resemble those of `append_child`, `insert_child_before` a
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:
-
++
[source]
----
bool append_fragment(pugi::xml_node target, const char* buffer, size_t size)
@@ -1567,7 +1567,7 @@ bool append_fragment(pugi::xml_node target, const char* buffer, size_t size)
----
* Cache the parsing step - instead of keeping in-memory buffers, keep document objects that already contain the parsed fragment:
-
++
[source]
----
bool append_fragment(pugi::xml_node target, const pugi::xml_document& cached_fragment)
@@ -1578,7 +1578,7 @@ bool append_fragment(pugi::xml_node target, const pugi::xml_document& cached_fra
----
* Use `xml_node::append_buffer` directly:
-
++
[source]
----
xml_parse_result xml_node::append_buffer(const void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);
@@ -2140,341 +2140,359 @@ Because of the differences in document object models, performance considerations
[[changes]]
== Changelog
-[h5 15.04.2015 - version 1.6]
+:!numbered:
+
+[[v1.6]]
+=== v1.6 ^15.04.2015^
Maintenance release. Changes:
* Specification changes:
- # Attribute/text values now use more digits when printing floating point numbers to guarantee round-tripping.
- # Text nodes no longer get extra surrounding whitespace when pretty-printing nodes with mixed contents
+ . Attribute/text values now use more digits when printing floating point numbers to guarantee round-tripping.
+ . Text nodes no longer get extra surrounding whitespace when pretty-printing nodes with mixed contents
* Bug fixes:
- # Fixed translate and normalize-space XPath functions to no longer return internal NUL characters
- # Fixed buffer overrun on malformed comments inside DOCTYPE sections
- # DOCTYPE parsing can no longer run out of stack space on malformed inputs (XML parsing is now using bounded stack space)
- # Adjusted processing instruction output to avoid malformed documents if the PI value contains "?>"
+ . Fixed translate and normalize-space XPath functions to no longer return internal NUL characters
+ . Fixed buffer overrun on malformed comments inside DOCTYPE sections
+ . DOCTYPE parsing can no longer run out of stack space on malformed inputs (XML parsing is now using bounded stack space)
+ . Adjusted processing instruction output to avoid malformed documents if the PI value contains "?>"
-[h5 27.11.2014 - version 1.5]
+[[v1.5]]
+=== v1.5 ^27.11.2014^
Major release, featuring a lot of performance improvements and some new features.
* Specification changes:
- # xml_document::load(const char_t*) was renamed to load_string; the old method is still available and will be deprecated in a future release
- # xml_node::select_single_node was renamed to select_node; the old method is still available and will be deprecated in a future release.
+ . xml_document::load(const char_t*) was renamed to load_string; the old method is still available and will be deprecated in a future release
+ . xml_node::select_single_node was renamed to select_node; the old method is still available and will be deprecated in a future release.
* New features:
- # Added xml_node::append_move and other functions for moving nodes within a document
- # Added xpath_query::evaluate_node for evaluating queries with a single node as a result
+ . Added xml_node::append_move and other functions for moving nodes within a document
+ . Added xpath_query::evaluate_node for evaluating queries with a single node as a result
* Performance improvements:
- # Optimized XML parsing (10-40% faster with clang/gcc, up to 10% faster with MSVC)
- # Optimized memory consumption when copying nodes in the same document (string contents is now shared)
- # Optimized node copying (10% faster for cross-document copies, 3x faster for inter-document copies; also it now consumes a constant amount of stack space)
- # Optimized node output (60% faster; also it now consumes a constant amount of stack space)
- # Optimized XPath allocation (query evaluation now results in fewer temporary allocations)
- # Optimized XPath sorting (node set sorting is 2-3x faster in some cases)
- # Optimized XPath evaluation (XPathMark suite is 100x faster; some commonly used queries are 3-4x faster)
+ . Optimized XML parsing (10-40% faster with clang/gcc, up to 10% faster with MSVC)
+ . Optimized memory consumption when copying nodes in the same document (string contents is now shared)
+ . Optimized node copying (10% faster for cross-document copies, 3x faster for inter-document copies; also it now consumes a constant amount of stack space)
+ . Optimized node output (60% faster; also it now consumes a constant amount of stack space)
+ . Optimized XPath allocation (query evaluation now results in fewer temporary allocations)
+ . Optimized XPath sorting (node set sorting is 2-3x faster in some cases)
+ . Optimized XPath evaluation (XPathMark suite is 100x faster; some commonly used queries are 3-4x faster)
* Compatibility improvements:
- # Fixed xml_node::offset_debug for corner cases
- # Fixed undefined behavior while calling memcpy in some cases
- # Fixed MSVC 2015 compilation warnings
- # Fixed contrib/foreach.hpp for Boost 1.56.0
+ . Fixed xml_node::offset_debug for corner cases
+ . Fixed undefined behavior while calling memcpy in some cases
+ . Fixed MSVC 2015 compilation warnings
+ . Fixed contrib/foreach.hpp for Boost 1.56.0
* Bug fixes
- # Adjusted comment output to avoid malformed documents if the comment value contains "--"
- # Fix XPath sorting for documents that were constructed using append_buffer
- # Fix load_file for wide-character paths with non-ASCII characters in MinGW with C{plus}{plus}11 mode enabled
+ . Adjusted comment output to avoid malformed documents if the comment value contains "--"
+ . Fix XPath sorting for documents that were constructed using append_buffer
+ . Fix load_file for wide-character paths with non-ASCII characters in MinGW with C{plus}{plus}11 mode enabled
-[h5 27.02.2014 - version 1.4]
+[[v1.4]]
+=== v1.4 ^27.02.2014^
Major release, featuring various new features, bug fixes and compatibility improvements.
* Specification changes:
- # Documents without element nodes are now rejected with status_no_document_element error, unless parse_fragment option is used
+ . Documents without element nodes are now rejected with status_no_document_element error, unless parse_fragment option is used
* New features:
- # Added XML fragment parsing (parse_fragment flag)
- # Added PCDATA whitespace trimming (parse_trim_pcdata flag)
- # Added long long support for xml_attribute and xml_text (as_llong, as_ullong and set_value/set overloads)
- # Added hexadecimal integer parsing support for as_int/as_uint/as_llong/as_ullong
- # Added xml_node::append_buffer to improve performance of assembling documents from fragments
- # xml_named_node_iterator is now bidirectional
- # Reduced XPath stack consumption during compilation and evaluation (useful for embedded systems)
+ . Added XML fragment parsing (parse_fragment flag)
+ . Added PCDATA whitespace trimming (parse_trim_pcdata flag)
+ . Added long long support for xml_attribute and xml_text (as_llong, as_ullong and set_value/set overloads)
+ . Added hexadecimal integer parsing support for as_int/as_uint/as_llong/as_ullong
+ . Added xml_node::append_buffer to improve performance of assembling documents from fragments
+ . xml_named_node_iterator is now bidirectional
+ . Reduced XPath stack consumption during compilation and evaluation (useful for embedded systems)
* Compatibility improvements:
- # Improved support for platforms without wchar_t support
- # Fixed several false positives in clang static analysis
- # Fixed several compilation warnings for various GCC versions
+ . Improved support for platforms without wchar_t support
+ . Fixed several false positives in clang static analysis
+ . Fixed several compilation warnings for various GCC versions
* Bug fixes:
- # Fixed undefined pointer arithmetic in XPath implementation
- # Fixed non-seekable iostream support for certain stream types, i.e. boost file_source with pipe input
- # Fixed xpath_query::return_type() for some expressions
- # Fixed dllexport issues with xml_named_node_iterator
- # Fixed find_child_by_attribute assertion for attributes with null name/value
+ . Fixed undefined pointer arithmetic in XPath implementation
+ . Fixed non-seekable iostream support for certain stream types, i.e. boost file_source with pipe input
+ . Fixed xpath_query::return_type() for some expressions
+ . Fixed dllexport issues with xml_named_node_iterator
+ . Fixed find_child_by_attribute assertion for attributes with null name/value
-[h5 1.05.2012 - version 1.2]
+[[v1.2]]
+=== v1.2 ^1.05.2012^
Major release, featuring header-only mode, various interface enhancements (i.e. PCDATA manipulation and C{plus}{plus}11 iteration), many other features and compatibility improvements.
* New features:
- # Added xml_text helper class for working with PCDATA/CDATA contents of an element node
- # Added optional header-only mode (controlled by PUGIXML_HEADER_ONLY define)
- # Added xml_node::children() and xml_node::attributes() for C{plus}{plus}11 ranged for loop or BOOST_FOREACH
- # Added support for Latin-1 (ISO-8859-1) encoding conversion during loading and saving
- # Added custom default values for '''xml_attribute::as_*''' (they are returned if the attribute does not exist)
- # Added parse_ws_pcdata_single flag for preserving whitespace-only PCDATA in case it's the only child
- # Added format_save_file_text for xml_document::save_file to open files as text instead of binary (changes newlines on Windows)
- # Added format_no_escapes flag to disable special symbol escaping (complements ~parse_escapes)
- # Added support for loading document from streams that do not support seeking
- # Added '''PUGIXML_MEMORY_*''' constants for tweaking allocation behavior (useful for embedded systems)
- # Added PUGIXML_VERSION preprocessor define
+ . Added xml_text helper class for working with PCDATA/CDATA contents of an element node
+ . Added optional header-only mode (controlled by PUGIXML_HEADER_ONLY define)
+ . Added xml_node::children() and xml_node::attributes() for C{plus}{plus}11 ranged for loop or BOOST_FOREACH
+ . Added support for Latin-1 (ISO-8859-1) encoding conversion during loading and saving
+ . Added custom default values for '''xml_attribute::as_*''' (they are returned if the attribute does not exist)
+ . Added parse_ws_pcdata_single flag for preserving whitespace-only PCDATA in case it's the only child
+ . Added format_save_file_text for xml_document::save_file to open files as text instead of binary (changes newlines on Windows)
+ . Added format_no_escapes flag to disable special symbol escaping (complements ~parse_escapes)
+ . Added support for loading document from streams that do not support seeking
+ . Added '''PUGIXML_MEMORY_*''' constants for tweaking allocation behavior (useful for embedded systems)
+ . Added PUGIXML_VERSION preprocessor define
* Compatibility improvements:
- # Parser does not require setjmp support (improves compatibility with some embedded platforms, enables clr:pure compilation)
- # STL forward declarations are no longer used (fixes SunCC/RWSTL compilation, fixes clang compilation in C{plus}{plus}11 mode)
- # Fixed AirPlay SDK, Android, Windows Mobile (WinCE) and C{plus}{plus}/CLI compilation
- # Fixed several compilation warnings for various GCC versions, Intel C{plus}{plus} compiler and Clang
+ . Parser does not require setjmp support (improves compatibility with some embedded platforms, enables clr:pure compilation)
+ . STL forward declarations are no longer used (fixes SunCC/RWSTL compilation, fixes clang compilation in C{plus}{plus}11 mode)
+ . Fixed AirPlay SDK, Android, Windows Mobile (WinCE) and C{plus}{plus}/CLI compilation
+ . Fixed several compilation warnings for various GCC versions, Intel C{plus}{plus} compiler and Clang
* Bug fixes:
- # Fixed unsafe bool conversion to avoid problems on C{plus}{plus}/CLI
- # Iterator dereference operator is const now (fixes Boost filter_iterator support)
- # xml_document::save_file now checks for file I/O errors during saving
+ . Fixed unsafe bool conversion to avoid problems on C{plus}{plus}/CLI
+ . Iterator dereference operator is const now (fixes Boost filter_iterator support)
+ . xml_document::save_file now checks for file I/O errors during saving
-[h5 1.11.2010 - version 1.0]
+[[v1.0]]
+=== v1.0 ^1.11.2010^
Major release, featuring many XPath enhancements, wide character filename support, miscellaneous performance improvements, bug fixes and more.
* XPath:
- # XPath implementation is moved to pugixml.cpp (which is the only source file now); use PUGIXML_NO_XPATH if you want to disable XPath to reduce code size
- # XPath is now supported without exceptions (PUGIXML_NO_EXCEPTIONS); the error handling mechanism depends on the presence of exception support
- # XPath is now supported without STL (PUGIXML_NO_STL)
- # Introduced variable support
- # Introduced new xpath_query::evaluate_string, which works without STL
- # Introduced new xpath_node_set constructor (from an iterator range)
- # Evaluation function now accept attribute context nodes
- # All internal allocations use custom allocation functions
- # Improved error reporting; now a last parsed offset is returned together with the parsing error
+ . XPath implementation is moved to pugixml.cpp (which is the only source file now); use PUGIXML_NO_XPATH if you want to disable XPath to reduce code size
+ . XPath is now supported without exceptions (PUGIXML_NO_EXCEPTIONS); the error handling mechanism depends on the presence of exception support
+ . XPath is now supported without STL (PUGIXML_NO_STL)
+ . Introduced variable support
+ . Introduced new xpath_query::evaluate_string, which works without STL
+ . Introduced new xpath_node_set constructor (from an iterator range)
+ . Evaluation function now accept attribute context nodes
+ . All internal allocations use custom allocation functions
+ . Improved error reporting; now a last parsed offset is returned together with the parsing error
* Bug fixes:
- # Fixed memory leak for loading from streams with stream exceptions turned on
- # Fixed custom deallocation function calling with null pointer in one case
- # Fixed missing attributes for iterator category functions; all functions/classes can now be DLL-exported
- # Worked around Digital Mars compiler bug, which lead to minor read overfetches in several functions
- # load_file now works with 2+ Gb files in MSVC/MinGW
- # XPath: fixed memory leaks for incorrect queries
- # XPath: fixed xpath_node() attribute constructor with empty attribute argument
- # XPath: fixed lang() function for non-ASCII arguments
+ . Fixed memory leak for loading from streams with stream exceptions turned on
+ . Fixed custom deallocation function calling with null pointer in one case
+ . Fixed missing attributes for iterator category functions; all functions/classes can now be DLL-exported
+ . Worked around Digital Mars compiler bug, which lead to minor read overfetches in several functions
+ . load_file now works with 2+ Gb files in MSVC/MinGW
+ . XPath: fixed memory leaks for incorrect queries
+ . XPath: fixed xpath_node() attribute constructor with empty attribute argument
+ . XPath: fixed lang() function for non-ASCII arguments
* Specification changes:
- # CDATA nodes containing ]]> are printed as several nodes; while this changes the internal structure, this is the only way to escape CDATA contents
- # Memory allocation errors during parsing now preserve last parsed offset (to give an idea about parsing progress)
- # If an element node has the only child, and it is of CDATA type, then the extra indentation is omitted (previously this behavior only held for PCDATA children)
+ . CDATA nodes containing ]]> are printed as several nodes; while this changes the internal structure, this is the only way to escape CDATA contents
+ . Memory allocation errors during parsing now preserve last parsed offset (to give an idea about parsing progress)
+ . If an element node has the only child, and it is of CDATA type, then the extra indentation is omitted (previously this behavior only held for PCDATA children)
* Additional functionality:
- # Added xml_parse_result default constructor
- # Added xml_document::load_file and xml_document::save_file with wide character paths
- # Added as_utf8 and as_wide overloads for std::wstring/std::string arguments
- # Added DOCTYPE node type (node_doctype) and a special parse flag, parse_doctype, to add such nodes to the document during parsing
- # 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
- # Added xml_node::prepend_attribute, xml_node::prepend_child and xml_node::prepend_copy functions
- # Added xml_node::append_child, xml_node::prepend_child, xml_node::insert_child_before and xml_node::insert_child_after overloads for element nodes (with name instead of type)
- # Added xml_document::reset() function
+ . Added xml_parse_result default constructor
+ . Added xml_document::load_file and xml_document::save_file with wide character paths
+ . Added as_utf8 and as_wide overloads for std::wstring/std::string arguments
+ . Added DOCTYPE node type (node_doctype) and a special parse flag, parse_doctype, to add such nodes to the document during parsing
+ . 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
+ . Added xml_node::prepend_attribute, xml_node::prepend_child and xml_node::prepend_copy functions
+ . Added xml_node::append_child, xml_node::prepend_child, xml_node::insert_child_before and xml_node::insert_child_after overloads for element nodes (with name instead of type)
+ . Added xml_document::reset() function
* Performance improvements:
- # xml_node::root() and xml_node::offset_debug() are now O(1) instead of O(logN)
- # Minor parsing optimizations
- # Minor memory optimization for strings in DOM tree (set_name/set_value)
- # Memory optimization for string memory reclaiming in DOM tree (set_name/set_value now reallocate the buffer if memory waste is too big)
- # XPath: optimized document order sorting
- # XPath: optimized child/attribute axis step
- # XPath: optimized number-to-string conversions in MSVC
- # XPath: optimized concat for many arguments
- # XPath: optimized evaluation allocation mechanism: constant and document strings are not heap-allocated
- # XPath: optimized evaluation allocation mechanism: all temporaries' allocations use fast stack-like allocator
+ . xml_node::root() and xml_node::offset_debug() are now O(1) instead of O(logN)
+ . Minor parsing optimizations
+ . Minor memory optimization for strings in DOM tree (set_name/set_value)
+ . Memory optimization for string memory reclaiming in DOM tree (set_name/set_value now reallocate the buffer if memory waste is too big)
+ . XPath: optimized document order sorting
+ . XPath: optimized child/attribute axis step
+ . XPath: optimized number-to-string conversions in MSVC
+ . XPath: optimized concat for many arguments
+ . XPath: optimized evaluation allocation mechanism: constant and document strings are not heap-allocated
+ . XPath: optimized evaluation allocation mechanism: all temporaries' allocations use fast stack-like allocator
* Compatibility:
- # Removed wildcard functions (xml_node::child_w, xml_node::attribute_w, etc.)
- # Removed xml_node::all_elements_by_name
- # Removed xpath_type_t enumeration; use xpath_value_type instead
- # Removed format_write_bom_utf8 enumeration; use format_write_bom instead
- # Removed xml_document::precompute_document_order, xml_attribute::document_order and xml_node::document_order functions; document order sort optimization is now automatic
- # Removed xml_document::parse functions and transfer_ownership struct; use xml_document::load_buffer_inplace and xml_document::load_buffer_inplace_own instead
- # Removed as_utf16 function; use as_wide instead
+ . Removed wildcard functions (xml_node::child_w, xml_node::attribute_w, etc.)
+ . Removed xml_node::all_elements_by_name
+ . Removed xpath_type_t enumeration; use xpath_value_type instead
+ . Removed format_write_bom_utf8 enumeration; use format_write_bom instead
+ . Removed xml_document::precompute_document_order, xml_attribute::document_order and xml_node::document_order functions; document order sort optimization is now automatic
+ . Removed xml_document::parse functions and transfer_ownership struct; use xml_document::load_buffer_inplace and xml_document::load_buffer_inplace_own instead
+ . Removed as_utf16 function; use as_wide instead
-[h5 1.07.2010 - version 0.9]
+[[v0.9]]
+=== v0.9 ^1.07.2010^
Major release, featuring extended and improved Unicode support, miscellaneous performance improvements, bug fixes and more.
* Major Unicode improvements:
- # Introduced encoding support (automatic/manual encoding detection on load, manual encoding selection on save, conversion from/to UTF8, UTF16 LE/BE, UTF32 LE/BE)
- # Introduced wchar_t mode (you can set PUGIXML_WCHAR_MODE define to switch pugixml internal encoding from UTF8 to wchar_t; all functions are switched to their Unicode variants)
- # Load/save functions now support wide streams
+ . Introduced encoding support (automatic/manual encoding detection on load, manual encoding selection on save, conversion from/to UTF8, UTF16 LE/BE, UTF32 LE/BE)
+ . Introduced wchar_t mode (you can set PUGIXML_WCHAR_MODE define to switch pugixml internal encoding from UTF8 to wchar_t; all functions are switched to their Unicode variants)
+ . Load/save functions now support wide streams
* Bug fixes:
- # Fixed document corruption on failed parsing bug
- # XPath string <-> number conversion improvements (increased precision, fixed crash for huge numbers)
- # Improved DOCTYPE parsing: now parser recognizes all well-formed DOCTYPE declarations
- # Fixed xml_attribute::as_uint() for large numbers (i.e. 2^32-1)
- # Fixed xml_node::first_element_by_path for path components that are prefixes of node names, but are not exactly equal to them.
+ . Fixed document corruption on failed parsing bug
+ . XPath string <-> number conversion improvements (increased precision, fixed crash for huge numbers)
+ . Improved DOCTYPE parsing: now parser recognizes all well-formed DOCTYPE declarations
+ . Fixed xml_attribute::as_uint() for large numbers (i.e. 2^32-1)
+ . Fixed xml_node::first_element_by_path for path components that are prefixes of node names, but are not exactly equal to them.
* Specification changes:
- # parse() API changed to load_buffer/load_buffer_inplace/load_buffer_inplace_own; load_buffer APIs do not require zero-terminated strings.
- # Renamed as_utf16 to as_wide
- # Changed xml_node::offset_debug return type and xml_parse_result::offset type to ptrdiff_t
- # Nodes/attributes with empty names are now printed as :anonymous
+ . parse() API changed to load_buffer/load_buffer_inplace/load_buffer_inplace_own; load_buffer APIs do not require zero-terminated strings.
+ . Renamed as_utf16 to as_wide
+ . Changed xml_node::offset_debug return type and xml_parse_result::offset type to ptrdiff_t
+ . Nodes/attributes with empty names are now printed as :anonymous
* Performance improvements:
- # Optimized document parsing and saving
- # Changed internal memory management: internal allocator is used for both metadata and name/value data; allocated pages are deleted if all allocations from them are deleted
- # Optimized memory consumption: sizeof(xml_node_struct) reduced from 40 bytes to 32 bytes on x86
- # Optimized debug mode parsing/saving by order of magnitude
+ . Optimized document parsing and saving
+ . Changed internal memory management: internal allocator is used for both metadata and name/value data; allocated pages are deleted if all allocations from them are deleted
+ . Optimized memory consumption: sizeof(xml_node_struct) reduced from 40 bytes to 32 bytes on x86
+ . Optimized debug mode parsing/saving by order of magnitude
* Miscellaneous:
- # All STL includes except <exception> in pugixml.hpp are replaced with forward declarations
- # xml_node::remove_child and xml_node::remove_attribute now return the operation result
+ . All STL includes except <exception> in pugixml.hpp are replaced with forward declarations
+ . xml_node::remove_child and xml_node::remove_attribute now return the operation result
* Compatibility:
- # parse() and as_utf16 are left for compatibility (these functions are deprecated and will be removed in version 1.0)
- # Wildcard functions, document_order/precompute_document_order functions, all_elements_by_name function and format_write_bom_utf8 flag are deprecated and will be removed in version 1.0
- # xpath_type_t enumeration was renamed to xpath_value_type; xpath_type_t is deprecated and will be removed in version 1.0
+ . parse() and as_utf16 are left for compatibility (these functions are deprecated and will be removed in version 1.0)
+ . Wildcard functions, document_order/precompute_document_order functions, all_elements_by_name function and format_write_bom_utf8 flag are deprecated and will be removed in version 1.0
+ . xpath_type_t enumeration was renamed to xpath_value_type; xpath_type_t is deprecated and will be removed in version 1.0
-[h5 8.11.2009 - version 0.5]
+[[v0.5]]
+=== v0.5 ^8.11.2009^
Major bugfix release. Changes:
* XPath bugfixes:
- # Fixed translate(), lang() and concat() functions (infinite loops/crashes)
- # Fixed compilation of queries with empty literal strings ("")
- # Fixed axis tests: they never add empty nodes/attributes to the resulting node set now
- # Fixed string-value evaluation for node-set (the result excluded some text descendants)
- # Fixed self:: axis (it behaved like ancestor-or-self::)
- # Fixed following:: and preceding:: axes (they included descendent and ancestor nodes, respectively)
- # Minor fix for namespace-uri() function (namespace declaration scope includes the parent element of namespace declaration attribute)
- # Some incorrect queries are no longer parsed now (i.e. foo: *)
- # Fixed text()/etc. node test parsing bug (i.e. foo[text()] failed to compile)
- # Fixed root step (/) - it now selects empty node set if query is evaluated on empty node
- # Fixed string to number conversion ("123 " converted to NaN, "123 .456" converted to 123.456 - now the results are 123 and NaN, respectively)
- # Node set copying now preserves sorted type; leads to better performance on some queries
+ . Fixed translate(), lang() and concat() functions (infinite loops/crashes)
+ . Fixed compilation of queries with empty literal strings ("")
+ . Fixed axis tests: they never add empty nodes/attributes to the resulting node set now
+ . Fixed string-value evaluation for node-set (the result excluded some text descendants)
+ . Fixed self:: axis (it behaved like ancestor-or-self::)
+ . Fixed following:: and preceding:: axes (they included descendent and ancestor nodes, respectively)
+ . Minor fix for namespace-uri() function (namespace declaration scope includes the parent element of namespace declaration attribute)
+ . Some incorrect queries are no longer parsed now (i.e. foo: *)
+ . Fixed text()/etc. node test parsing bug (i.e. foo[text()] failed to compile)
+ . Fixed root step (/) - it now selects empty node set if query is evaluated on empty node
+ . Fixed string to number conversion ("123 " converted to NaN, "123 .456" converted to 123.456 - now the results are 123 and NaN, respectively)
+ . Node set copying now preserves sorted type; leads to better performance on some queries
* Miscellaneous bugfixes:
- # Fixed xml_node::offset_debug for PI nodes
- # Added empty attribute checks to xml_node::remove_attribute
- # Fixed node_pi and node_declaration copying
- # Const-correctness fixes
+ . Fixed xml_node::offset_debug for PI nodes
+ . Added empty attribute checks to xml_node::remove_attribute
+ . Fixed node_pi and node_declaration copying
+ . Const-correctness fixes
* Specification changes:
- # xpath_node::select_nodes() and related functions now throw exception if expression return type is not node set (instead of assertion)
- # xml_node::traverse() now sets depth to -1 for both begin() and end() callbacks (was 0 at begin() and -1 at end())
- # In case of non-raw node printing a newline is output after PCDATA inside nodes if the PCDATA has siblings
- # UTF8 -> wchar_t conversion now considers 5-byte UTF8-like sequences as invalid
+ . xpath_node::select_nodes() and related functions now throw exception if expression return type is not node set (instead of assertion)
+ . xml_node::traverse() now sets depth to -1 for both begin() and end() callbacks (was 0 at begin() and -1 at end())
+ . In case of non-raw node printing a newline is output after PCDATA inside nodes if the PCDATA has siblings
+ . UTF8 -> wchar_t conversion now considers 5-byte UTF8-like sequences as invalid
* New features:
- # Added xpath_node_set::operator[] for index-based iteration
- # Added xpath_query::return_type()
- # Added getter accessors for memory-management functions
+ . Added xpath_node_set::operator[] for index-based iteration
+ . Added xpath_query::return_type()
+ . Added getter accessors for memory-management functions
-[h5 17.09.2009 - version 0.42]
+[[v0.42]]
+=== v0.42 ^17.09.2009^
Maintenance release. Changes:
* Bug fixes:
- # Fixed deallocation in case of custom allocation functions or if delete[] / free are incompatible
- # XPath parser fixed for incorrect queries (i.e. incorrect XPath queries should now always fail to compile)
- # Const-correctness fixes for find_child_by_attribute
- # Improved compatibility (miscellaneous warning fixes, fixed cstring include dependency for GCC)
- # Fixed iterator begin/end and print function to work correctly for empty nodes
+ . Fixed deallocation in case of custom allocation functions or if delete[] / free are incompatible
+ . XPath parser fixed for incorrect queries (i.e. incorrect XPath queries should now always fail to compile)
+ . Const-correctness fixes for find_child_by_attribute
+ . Improved compatibility (miscellaneous warning fixes, fixed cstring include dependency for GCC)
+ . Fixed iterator begin/end and print function to work correctly for empty nodes
* New features:
- # Added PUGIXML_API/PUGIXML_CLASS/PUGIXML_FUNCTION configuration macros to control class/function attributes
- # Added xml_attribute::set_value overloads for different types
+ . Added PUGIXML_API/PUGIXML_CLASS/PUGIXML_FUNCTION configuration macros to control class/function attributes
+ . Added xml_attribute::set_value overloads for different types
-[h5 8.02.2009 - version 0.41]
+[[v0.41]]
+=== v0.41 ^8.02.2009^
Maintenance release. Changes:
* Bug fixes:
- # Fixed bug with node printing (occasionally some content was not written to output stream)
+ . Fixed bug with node printing (occasionally some content was not written to output stream)
-[h5 18.01.2009 - version 0.4]
+[[v0.4]]
+=== v0.4 ^18.01.2009^
Changes:
* Bug fixes:
- # Documentation fix in samples for parse() with manual lifetime control
- # Fixed document order sorting in XPath (it caused wrong order of nodes after xpath_node_set::sort and wrong results of some XPath queries)
+ . Documentation fix in samples for parse() with manual lifetime control
+ . Fixed document order sorting in XPath (it caused wrong order of nodes after xpath_node_set::sort and wrong results of some XPath queries)
* Node printing changes:
- # Single quotes are no longer escaped when printing nodes
- # Symbols in second half of ASCII table are no longer escaped when printing nodes; because of this, format_utf8 flag is deleted as it's no longer needed and format_write_bom is renamed to format_write_bom_utf8.
- # Reworked node printing - now it works via xml_writer interface; implementations for FILE* and std::ostream are available. As a side-effect, xml_document::save_file now works without STL.
+ . Single quotes are no longer escaped when printing nodes
+ . Symbols in second half of ASCII table are no longer escaped when printing nodes; because of this, format_utf8 flag is deleted as it's no longer needed and format_write_bom is renamed to format_write_bom_utf8.
+ . Reworked node printing - now it works via xml_writer interface; implementations for FILE* and std::ostream are available. As a side-effect, xml_document::save_file now works without STL.
* New features:
- # Added unsigned integer support for attributes (xml_attribute::as_uint, xml_attribute::operator=)
- # Now document declaration (<?xml ...?>) is parsed as node with type node_declaration when parse_declaration flag is specified (access to encoding/version is performed as if they were attributes, i.e. doc.child("xml").attribute("version").as_float()); corresponding flags for node printing were also added
- # Added support for custom memory management (see set_memory_management_functions for details)
- # Implemented node/attribute copying (see xml_node::insert_copy_* and xml_node::append_copy for details)
- # Added find_child_by_attribute and find_child_by_attribute_w to simplify parsing code in some cases (i.e. COLLADA files)
- # Added file offset information querying for debugging purposes (now you're able to determine exact location of any xml_node in parsed file, see xml_node::offset_debug for details)
- # Improved error handling for parsing - now load(), load_file() and parse() return xml_parse_result, which contains error code and last parsed offset; this does not break old interface as xml_parse_result can be implicitly casted to bool.
+ . Added unsigned integer support for attributes (xml_attribute::as_uint, xml_attribute::operator=)
+ . Now document declaration (<?xml ...?>) is parsed as node with type node_declaration when parse_declaration flag is specified (access to encoding/version is performed as if they were attributes, i.e. doc.child("xml").attribute("version").as_float()); corresponding flags for node printing were also added
+ . Added support for custom memory management (see set_memory_management_functions for details)
+ . Implemented node/attribute copying (see xml_node::insert_copy_* and xml_node::append_copy for details)
+ . Added find_child_by_attribute and find_child_by_attribute_w to simplify parsing code in some cases (i.e. COLLADA files)
+ . Added file offset information querying for debugging purposes (now you're able to determine exact location of any xml_node in parsed file, see xml_node::offset_debug for details)
+ . Improved error handling for parsing - now load(), load_file() and parse() return xml_parse_result, which contains error code and last parsed offset; this does not break old interface as xml_parse_result can be implicitly casted to bool.
-[h5 31.10.2007 - version 0.34]
+[[v0.34]]
+=== v0.34 ^31.10.2007^
Maintenance release. Changes:
* Bug fixes:
- # Fixed bug with loading from text-mode iostreams
- # Fixed leak when transfer_ownership is true and parsing is failing
- # Fixed bug in saving (\r and \n are now escaped in attribute values)
- # Renamed free() to destroy() - some macro conflicts were reported
+ . Fixed bug with loading from text-mode iostreams
+ . Fixed leak when transfer_ownership is true and parsing is failing
+ . Fixed bug in saving (\r and \n are now escaped in attribute values)
+ . Renamed free() to destroy() - some macro conflicts were reported
* New features:
- # Improved compatibility (supported Digital Mars C{plus}{plus}, MSVC 6, CodeWarrior 8, PGI C{plus}{plus}, Comeau, supported PS3 and XBox360)
- # PUGIXML_NO_EXCEPTION flag for platforms without exception handling
+ . Improved compatibility (supported Digital Mars C{plus}{plus}, MSVC 6, CodeWarrior 8, PGI C{plus}{plus}, Comeau, supported PS3 and XBox360)
+ . PUGIXML_NO_EXCEPTION flag for platforms without exception handling
-[h5 21.02.2007 - version 0.3]
+[[v0.3]]
+=== v0.3 ^21.02.2007^
Refactored, reworked and improved version. Changes:
* Interface:
- # Added XPath
- # Added tree modification functions
- # Added no STL compilation mode
- # Added saving document to file
- # Refactored parsing flags
- # Removed xml_parser class in favor of xml_document
- # Added transfer ownership parsing mode
- # Modified the way xml_tree_walker works
- # Iterators are now non-constant
+ . Added XPath
+ . Added tree modification functions
+ . Added no STL compilation mode
+ . Added saving document to file
+ . Refactored parsing flags
+ . Removed xml_parser class in favor of xml_document
+ . Added transfer ownership parsing mode
+ . Modified the way xml_tree_walker works
+ . Iterators are now non-constant
* Implementation:
- # Support of several compilers and platforms
- # Refactored and sped up parsing core
- # Improved standard compliancy
- # Added XPath implementation
- # Fixed several bugs
+ . Support of several compilers and platforms
+ . Refactored and sped up parsing core
+ . Improved standard compliancy
+ . Added XPath implementation
+ . Fixed several bugs
-[h5 6.11.2006 - version 0.2]
+[[v0.2]]
+=== v0.2 ^6.11.2006^
First public release. Changes:
* Bug fixes:
- # Fixed child_value() (for empty nodes)
- # Fixed xml_parser_impl warning at W4
+ . Fixed child_value() (for empty nodes)
+ . Fixed xml_parser_impl warning at W4
* New features:
- # Introduced child_value(name) and child_value_w(name)
- # parse_eol_pcdata and parse_eol_attribute flags + parse_minimal optimizations
- # Optimizations of strconv_t
+ . Introduced child_value(name) and child_value_w(name)
+ . parse_eol_pcdata and parse_eol_attribute flags + parse_minimal optimizations
+ . Optimizations of strconv_t
-[h5 15.07.2006 - version 0.1]
+[[v0.1]]
+=== v0.1 ^15.07.2006^
First private release for testing purposes
+:numbered:
+
[[apiref]]
== API Reference