anchor.diff:  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)
  
positive.code: [[changes]]
  == Changelog
  
  [h5 15.04.2015 - version 1.6]
  
  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
  
  * 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 "?>"
  
  [h5 27.11.2014 - version 1.5]
  
  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.
  
  * 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
  
  * 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)
  
  * 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
  
  * 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
  
  [h5 27.02.2014 - version 1.4]
  
  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
  
  * 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)
  
  * 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
  
  * 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
  
  [h5 1.05.2012 - version 1.2]
  
  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
  
  * 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
  
  * 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
  
  [h5 1.11.2010 - version 1.0]
  
  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
  
  * 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
  
  * 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)
  
  * 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
  
  * 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
  
  * 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
  
  [h5 1.07.2010 - version 0.9]
  
  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
  
  * 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.
  
  * 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
  
  * 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
  
  * 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
  
  * 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
  
  [h5 8.11.2009 - version 0.5]
  
  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
  
  * 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
  
  * 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
  
  * New features:
      # 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]
  
  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
  
  * 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
  
  [h5 8.02.2009 - version 0.41]
  
  Maintenance release. Changes:
  
  * Bug fixes:
      # Fixed bug with node printing (occasionally some content was not written to output stream)
  
  [h5 18.01.2009 - version 0.4]
  
  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)
  
  * 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.
  
  * 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.
  
  [h5 31.10.2007 - version 0.34]
  
  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
  
  * 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
  
  [h5 21.02.2007 - version 0.3]
  
  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
  
  * Implementation:
      # 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]
  
  First public release. Changes:
  
  * Bug fixes:
      # 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
  
  [h5 15.07.2006 - version 0.1]
  
  First private release for testing purposes
  
  [[apiref]]
  == API Reference
  
negative.code: ----
  
  * 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);
  