diff options
Diffstat (limited to 'docs/manual.adoc')
| -rw-r--r-- | docs/manual.adoc | 201 |
1 files changed, 123 insertions, 78 deletions
diff --git a/docs/manual.adoc b/docs/manual.adoc index 82c6b6a..61dcfcb 100644 --- a/docs/manual.adoc +++ b/docs/manual.adoc @@ -46,7 +46,7 @@ Thanks to *Vyacheslav Egorov* for documentation proofreading and fuzz testing. The pugixml library is distributed under the MIT license: .... -Copyright (c) 2006-2015 Arseny Kapoulkine +Copyright (c) 2006-2016 Arseny Kapoulkine Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation @@ -71,10 +71,10 @@ OTHER DEALINGS IN THE SOFTWARE. .... This means that you can freely use pugixml in your applications, both open-source and proprietary. If you use pugixml in a product, it is sufficient to add an acknowledgment like this to the product distribution: - + .... This software is based on pugixml library (http://pugixml.org). -pugixml is Copyright (C) 2006-2015 Arseny Kapoulkine. +pugixml is Copyright (C) 2006-2016 Arseny Kapoulkine. .... [[install]] @@ -142,9 +142,9 @@ Here's an incomplete list of pugixml packages in various systems: === Building pugixml pugixml is distributed in source form without any pre-built binaries; you have to build them yourself. - + The complete pugixml source consists of three files - one source file, `pugixml.cpp`, and two header files, `pugixml.hpp` and `pugiconfig.hpp`. `pugixml.hpp` is the primary header which you need to include in order to use pugixml classes/functions; `pugiconfig.hpp` is a supplementary configuration file (see <<install.building.config>>). The rest of this guide assumes that `pugixml.hpp` is either in the current directory or in one of include directories of your projects, so that `#include "pugixml.hpp"` can find the header; however you can also use relative path (i.e. `#include "../libs/pugixml/src/pugixml.hpp"`) or include directory-relative path (i.e. `#include <xml/thirdparty/pugixml/src/pugixml.hpp>`). - + [[install.building.embed]] ==== Building pugixml as a part of another static library/executable @@ -165,11 +165,11 @@ The correct way to resolve this is to disable precompiled headers for `pugixml.c | image::vs2005_pch3.png[link="images/vs2005_pch3.png"] | image::vs2005_pch4.png[link="images/vs2005_pch4.png"] |=== - + [[install.building.static]] ==== Building pugixml as a standalone static library - -It's possible to compile pugixml as a standalone static library. This process depends on the method of building your application; pugixml distribution comes with project files for several popular IDEs/build systems. There are project files for Apple XCode, Code::Blocks, Codelite, Microsoft Visual Studio 2005, 2008, 2010+, and configuration scripts for CMake and premake4. You're welcome to submit project files/build scripts for other software; see <<overview.feedback>>. + +It's possible to compile pugixml as a standalone static library. This process depends on the method of building your application; pugixml distribution comes with project files for several popular IDEs/build systems. There are project files for Apple XCode, Code::Blocks, Codelite, Microsoft Visual Studio 2005, 2008, 2010+, and configuration scripts for CMake and premake4. You're welcome to submit project files/build scripts for other software; see <<overview.feedback>>. There are two projects for each version of Microsoft Visual Studio: one for dynamically linked CRT, which has a name like `pugixml_vs2008.vcproj`, and another one for statically linked CRT, which has a name like `pugixml_vs2008_static.vcproj`. You should select the version that matches the CRT used in your application; the default option for new projects created by Microsoft Visual Studio is dynamically linked CRT, so unless you changed the defaults, you should use the version with dynamic CRT (i.e. `pugixml_vs2008.vcproj` for Microsoft Visual Studio 2008). @@ -187,7 +187,7 @@ In addition to adding pugixml project to your workspace, you'll have to make sur [[install.building.shared]] ==== Building pugixml as a standalone shared library - + It's possible to compile pugixml as a standalone shared library. The process is usually similar to the static library approach; however, no preconfigured projects/scripts are included into pugixml distribution, so you'll have to do it yourself. Generally, if you're using GCC-based toolchain, the process does not differ from building any other library as DLL (adding -shared to compilation flags should suffice); if you're using MSVC-based toolchain, you'll have to explicitly mark exported symbols with a declspec attribute. You can do it by defining <<PUGIXML_API,PUGIXML_API>> macro, i.e. via `pugiconfig.hpp`: [source] @@ -243,13 +243,13 @@ NOTE: In that example `PUGIXML_API` is inconsistent between several source files [[PUGIXML_MEMORY_PAGE_SIZE]]`PUGIXML_MEMORY_PAGE_SIZE`, [[PUGIXML_MEMORY_OUTPUT_STACK]]`PUGIXML_MEMORY_OUTPUT_STACK` and [[PUGIXML_MEMORY_XPATH_PAGE_SIZE]]`PUGIXML_MEMORY_XPATH_PAGE_SIZE` can be used to customize certain important sizes to optimize memory usage for the application-specific patterns. For details see <<dom.memory.tuning>>. [[PUGIXML_HAS_LONG_LONG]]`PUGIXML_HAS_LONG_LONG` define enables support for `long long` type in pugixml. This define is automatically enabled if your platform is known to have `long long` support (i.e. has C{plus}{plus}11 support or uses a reasonably modern version of a known compiler); if pugixml does not recognize that your platform supports `long long` but in fact it does, you can enable the define manually. - + [[install.portability]] === Portability 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 exceeding 99%. -pugixml runs on a variety of desktop platforms (including Microsoft Windows, Linux, FreeBSD, Apple MacOSX and Sun Solaris), game consoles (inclusing Microsoft Xbox 360, Microsoft Xbox One, Nintendo Wii, Sony Playstation Portable and Sony Playstation 3) and mobile platforms (including Android, BlackBerry, Samsung bada and Microsoft Windows CE). +pugixml runs on a variety of desktop platforms (including Microsoft Windows, Linux, FreeBSD, Apple MacOSX and Sun Solaris), game consoles (inclusing Microsoft Xbox 360, Microsoft Xbox One, Nintendo Wii, Sony Playstation Portable and Sony Playstation 3) and mobile platforms (including Android, iOS, BlackBerry, Samsung bada and Microsoft Windows CE). pugixml supports various architectures, such as x86/x86-64, PowerPC, ARM, MIPS and SPARC. In general it should run on any architecture since it does not use architecture-specific code and does not rely on features such as unaligned memory access. @@ -291,7 +291,7 @@ Here `"node"` element has three children, two of which are PCDATA nodes with val * Character data nodes ([[node_cdata]]`node_cdata`) represent text in XML that is quoted in a special way. CDATA nodes do not differ from PCDATA nodes except in XML representation - the above text example looks like this with CDATA: + ---- -<node> <![CDATA[[text1]]> <child/> <![CDATA[[text2]]> </node> +<node> <![CDATA[text1]]> <child/> <![CDATA[text2]]> </node> ---- + CDATA nodes make it easy to include non-escaped `<`, `&` and `>` characters in plain text. CDATA value can not contain the character sequence `]]>`, since it is used to determine the end of node contents. @@ -451,7 +451,7 @@ you'll have to use `xml_node node = doc.child(L"bookstore").find_child_by_attribute(L"book", L"id", L"12345");` ==== - + [[dom.thread]] === Thread-safety guarantees @@ -509,11 +509,11 @@ This is a simple example of custom memory management (link:samples/custom_memory [source,indent=0] ---- -include::samples/custom_memory_management.cpp[tags=decl] +include::samples/custom_memory_management.cpp[tags=decl] ---- [source,indent=0] ---- -include::samples/custom_memory_management.cpp[tags=call] +include::samples/custom_memory_management.cpp[tags=call] ---- When setting new memory management functions, care must be taken to make sure that there are no live pugixml objects. Otherwise when the objects are destroyed, the new deallocation function will be called with the memory obtained by the old allocation function, resulting in undefined behavior. @@ -569,7 +569,7 @@ The most common source of XML data is files; pugixml provides dedicated function 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); ---- - + These functions accept the file path as its first argument, and also two optional arguments, which specify parsing options (see <<loading.options>>) and input data encoding (see <<loading.encoding>>). The path has the target operating system format, so it can be a relative or absolute one, it should have the delimiters of the target system, it should have the exact case if the target file system is case-sensitive, etc. File path is passed to the 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. @@ -580,7 +580,7 @@ This is an example of loading XML document from file (link:samples/load_file.cpp [source,indent=0] ---- -include::samples/load_file.cpp[tags=code] +include::samples/load_file.cpp[tags=code] ---- [[loading.memory]] @@ -616,25 +616,25 @@ This is an example of loading XML document from memory using different functions [source,indent=0] ---- -include::samples/load_memory.cpp[tags=decl] +include::samples/load_memory.cpp[tags=decl] ---- [source,indent=0] ---- -include::samples/load_memory.cpp[tags=load_buffer] +include::samples/load_memory.cpp[tags=load_buffer] ---- [source,indent=0] ---- -include::samples/load_memory.cpp[tags=load_buffer_inplace_begin] +include::samples/load_memory.cpp[tags=load_buffer_inplace_begin] -include::samples/load_memory.cpp[tags=load_buffer_inplace_end] +include::samples/load_memory.cpp[tags=load_buffer_inplace_end] ---- [source,indent=0] ---- -include::samples/load_memory.cpp[tags=load_buffer_inplace_own] +include::samples/load_memory.cpp[tags=load_buffer_inplace_own] ---- [source,indent=0] ---- -include::samples/load_memory.cpp[tags=load_string] +include::samples/load_memory.cpp[tags=load_string] ---- [[loading.stream]] @@ -657,7 +657,7 @@ This is a simple example of loading XML document from file using streams (link:s [source,indent=0] ---- -include::samples/load_stream.cpp[tags=code] +include::samples/load_stream.cpp[tags=code] ---- [[loading.errors]] @@ -718,7 +718,7 @@ This is an example of handling loading errors (link:samples/load_error_handling. [source,indent=0] ---- -include::samples/load_error_handling.cpp[tags=code] +include::samples/load_error_handling.cpp[tags=code] ---- [[loading.options]] @@ -746,6 +746,9 @@ These flags control the resulting tree contents: * [[parse_ws_pcdata_single]]`parse_ws_pcdata_single` determines if whitespace-only PCDATA nodes that have no sibling nodes are to be put in DOM tree. In some cases application needs to parse the whitespace-only contents of nodes, i.e. `<node> </node>`, but is not interested in whitespace markup elsewhere. It is possible to use <<parse_ws_pcdata,parse_ws_pcdata>> flag in this case, but it results in excessive allocations and complicates document processing; this flag can be used to avoid that. As an example, after parsing XML string `<node> <a> </a> </node>` with `parse_ws_pcdata_single` flag set, `<node>` element will have one child `<a>`, and `<a>` element will have one child with type <<node_pcdata,node_pcdata>> and value `" "`. This flag has no effect if <<parse_ws_pcdata,parse_ws_pcdata>> is enabled. This flag is *off* by default. +* [[parse_embed_pcdata]]`parse_embed_pcdata` determines if PCDATA contents is to be saved as element values. Normally element nodes have names but not values; this flag forces the parser to store the contents as a value if PCDATA is the first child of the element node (otherwise PCDATA node is created as usual). This can significantly reduce the memory required for documents with many PCDATA nodes. To retrieve the data you can use `xml_node::value()` on the element nodes or any of the higher-level functions like `child_value` or `text`. This flag is *off* by default. +Since this flag significantly changes the DOM structure it is only recommended for parsing documents with many PCDATA nodes in memory-constrained environments. This flag is *off* by default. + * [[parse_fragment]]`parse_fragment` determines if document should be treated as a fragment of a valid XML. Parsing document as a fragment leads to top-level PCDATA content (i.e. text that is not located inside a node) to be added to a tree, and additionally treats documents without element nodes as valid. This flag is *off* by default. CAUTION: Using in-place parsing (<<xml_document::load_buffer_inplace,load_buffer_inplace>>) with `parse_fragment` flag may result in the loss of the last character of the buffer if it is a part of PCDATA. Since PCDATA values are null-terminated strings, the only way to resolve this is to provide a null-terminated buffer as an input to `load_buffer_inplace` - i.e. `doc.load_buffer_inplace("test\0", 5, pugi::parse_default | pugi::parse_fragment)`. @@ -774,7 +777,7 @@ This is an example of using different parsing options (link:samples/load_options [source,indent=0] ---- -include::samples/load_options.cpp[tags=code] +include::samples/load_options.cpp[tags=code] ---- [[loading.encoding]] @@ -835,7 +838,7 @@ pugixml features an extensive interface for getting various types of data from t [[xml_node::parent]][[xml_node::first_child]][[xml_node::last_child]][[xml_node::next_sibling]][[xml_node::previous_sibling]][[xml_node::first_attribute]][[xml_node::last_attribute]][[xml_attribute::next_attribute]][[xml_attribute::previous_attribute]] The internal representation of the document is a tree, where each node has a list of child nodes (the order of children corresponds to their order in the XML representation), and additionally element nodes have a list of attributes, which is also ordered. Several functions are provided in order to let you get from one node in the tree to the other. These functions roughly correspond to the internal representation, and thus are usually building blocks for other methods of traversing (i.e. XPath traversals are based on these functions). - + [source] ---- xml_node xml_node::parent() const; @@ -860,7 +863,7 @@ With these functions, you can iterate through all child nodes and display all at [source,indent=0] ---- -include::samples/traverse_base.cpp[tags=basic] +include::samples/traverse_base.cpp[tags=basic] ---- [[access.nodedata]] @@ -919,7 +922,7 @@ It returns `def` argument if the attribute handle is null. If you do not specify [[xml_attribute::as_int]][[xml_attribute::as_uint]][[xml_attribute::as_double]][[xml_attribute::as_float]][[xml_attribute::as_bool]][[xml_attribute::as_llong]][[xml_attribute::as_ullong]] In many cases attribute values have types that are not strings - i.e. an attribute may always contain values that should be treated as integers, despite the fact that they are represented as strings in XML. pugixml provides several accessors that convert attribute value to some other type: - + [source] ---- int xml_attribute::as_int(int def = 0) const; @@ -931,9 +934,9 @@ long long xml_attribute::as_llong(long long def = 0) const; unsigned long long xml_attribute::as_ullong(unsigned long long def = 0) const; ---- -`as_int`, `as_uint`, `as_llong`, `as_ullong`, `as_double` and `as_float` convert attribute values to numbers. If attribute handle is null or attribute value is empty, `def` argument is returned (which is 0 by default). Otherwise, all leading whitespace characters are truncated, and the remaining string is parsed as an integer number in either decimal or hexadecimal form (applicable to `as_int`, `as_uint`, `as_llong` and `as_ullong`; hexadecimal format is used if the number has `0x` or `0X` prefix) or as a floating point number in either decimal or scientific form (`as_double` or `as_float`). Any extra characters are silently discarded, i.e. `as_int` will return `1` for string `"1abc"`. +`as_int`, `as_uint`, `as_llong`, `as_ullong`, `as_double` and `as_float` convert attribute values to numbers. If attribute handle is null `def` argument is returned (which is 0 by default). Otherwise, all leading whitespace characters are truncated, and the remaining string is parsed as an integer number in either decimal or hexadecimal form (applicable to `as_int`, `as_uint`, `as_llong` and `as_ullong`; hexadecimal format is used if the number has `0x` or `0X` prefix) or as a floating point number in either decimal or scientific form (`as_double` or `as_float`). -In case the input string contains a number that is out of the target numeric range, the result is undefined. +In case the input string contains a non-numeric character sequence or a number that is out of the target numeric range, the result is undefined. CAUTION: Number conversion functions depend on current C locale as set with `setlocale`, so may return unexpected results if the locale is different from `"C"`. @@ -946,7 +949,7 @@ This is an example of using these functions, along with node data retrieval ones [source,indent=0] ---- -include::samples/traverse_base.cpp[tags=data] +include::samples/traverse_base.cpp[tags=data] ---- [[access.contents]] @@ -989,7 +992,7 @@ This is an example of using these functions (link:samples/traverse_base.cpp[]): [source,indent=0] ---- -include::samples/traverse_base.cpp[tags=contents] +include::samples/traverse_base.cpp[tags=contents] ---- [[access.rangefor]] @@ -1011,7 +1014,7 @@ This is an example of using these functions (link:samples/traverse_rangefor.cpp[ [source,indent=0] ---- -include::samples/traverse_rangefor.cpp[tags=code] +include::samples/traverse_rangefor.cpp[tags=code] ---- [[access.iterators]] @@ -1044,7 +1047,7 @@ Here is an example of using iterators for document traversal (link:samples/trave [source,indent=0] ---- -include::samples/traverse_iter.cpp[tags=code] +include::samples/traverse_iter.cpp[tags=code] ---- CAUTION: Node and attribute iterators are somewhere in the middle between const and non-const iterators. While dereference operation yields a non-constant reference to the object, so that you can use it for tree modification operations, modifying this reference using assignment - i.e. passing iterators to a function like `std::sort` - will not give expected results, as assignment modifies local handle that's stored in the iterator. @@ -1086,11 +1089,11 @@ This is an example of traversing tree hierarchy with xml_tree_walker (link:sampl [source,indent=0] ---- -include::samples/traverse_walker.cpp[tags=impl] +include::samples/traverse_walker.cpp[tags=impl] ---- [source,indent=0] ---- -include::samples/traverse_walker.cpp[tags=traverse] +include::samples/traverse_walker.cpp[tags=traverse] ---- [[access.predicate]] @@ -1118,11 +1121,11 @@ This is an example of using predicate-based functions (link:samples/traverse_pre [source,indent=0] ---- -include::samples/traverse_predicate.cpp[tags=decl] +include::samples/traverse_predicate.cpp[tags=decl] ---- [source,indent=0] ---- -include::samples/traverse_predicate.cpp[tags=find] +include::samples/traverse_predicate.cpp[tags=find] ---- [[access.text]] @@ -1133,7 +1136,7 @@ It is common to store data as text contents of some node - i.e. `<node><descript [[xml_node::text]] You can get the text object from a node by using `text()` method: - + [source] ---- xml_text xml_node::text() const; @@ -1190,7 +1193,7 @@ This is an example of using `xml_text` object (link:samples/text.cpp[]): [source,indent=0] ---- -include::samples/text.cpp[tags=access] +include::samples/text.cpp[tags=access] ---- [[access.misc]] @@ -1217,7 +1220,7 @@ xml_node xml_node::first_element_by_path(const char_t* path, char_t delimiter = Node paths consist of node names, separated with a delimiter (which is `/` by default); also paths can contain self (`.`) and parent (`..`) pseudo-names, so that this is a valid path: `"../../foo/./bar"`. `path` returns the path to the node from the document root, `first_element_by_path` looks for a node represented by a given path; a path can be an absolute one (absolute paths start with the delimiter), in which case the rest of the path is treated as document root relative, and relative to the given node. For example, in the following document: `<a><b><c/></b></a>`, node `<c/>` has path `"a/b/c"`; calling `first_element_by_path` for document with path `"a/b"` results in node `<b/>`; calling `first_element_by_path` for node `<a/>` with path `"../a/./b/../."` results in node `<a/>`; calling `first_element_by_path` with path `"/a"` results in node `<a/>` for any node. -In case path component is ambiguous (if there are two nodes with given name), the first one is selected; paths are not guaranteed to uniquely identify nodes in a document. If any component of a path is not found, the result of `first_element_by_path` is null node; also `first_element_by_path` returns null node for null nodes, in which case the path does not matter. `path` returns an empty string for null nodes. +In case path component is ambiguous (if there are two nodes with given name), the first one is selected; paths are not guaranteed to uniquely identify nodes in a document. If any component of a path is not found, the result of `first_element_by_path` is null node; also `first_element_by_path` returns null node for null nodes, in which case the path does not matter. `path` returns an empty string for null nodes. NOTE: `path` function returns the result as STL string, and thus is not available if <<PUGIXML_NO_STL,PUGIXML_NO_STL>> is defined. @@ -1258,7 +1261,7 @@ This is an example of setting node name and value (link:samples/modify_base.cpp[ [source,indent=0] ---- -include::samples/modify_base.cpp[tags=node] +include::samples/modify_base.cpp[tags=node] ---- [[modify.attrdata]] @@ -1281,13 +1284,15 @@ In addition to string functions, several functions are provided for handling att ---- bool xml_attribute::set_value(int rhs); bool xml_attribute::set_value(unsigned int rhs); +bool xml_attribute::set_value(long rhs); +bool xml_attribute::set_value(unsigned long rhs); bool xml_attribute::set_value(double rhs); bool xml_attribute::set_value(float rhs); bool xml_attribute::set_value(bool rhs); bool xml_attribute::set_value(long long rhs); bool xml_attribute::set_value(unsigned long long rhs); ---- - + The above functions convert the argument to string and then call the base `set_value` function. Integers are converted to a decimal form, floating-point numbers are converted to either decimal or scientific form, depending on the number magnitude, boolean values are converted to either `"true"` or `"false"`. CAUTION: Number conversion functions depend on current C locale as set with `setlocale`, so may generate unexpected results if the locale is different from `"C"`. @@ -1303,6 +1308,8 @@ For convenience, all `set_value` functions have the corresponding assignment ope xml_attribute& xml_attribute::operator=(const char_t* rhs); xml_attribute& xml_attribute::operator=(int rhs); xml_attribute& xml_attribute::operator=(unsigned int rhs); +xml_attribute& xml_attribute::operator=(long rhs); +xml_attribute& xml_attribute::operator=(unsigned long rhs); xml_attribute& xml_attribute::operator=(double rhs); xml_attribute& xml_attribute::operator=(float rhs); xml_attribute& xml_attribute::operator=(bool rhs); @@ -1316,7 +1323,7 @@ This is an example of setting attribute name and value (link:samples/modify_base [source,indent=0] ---- -include::samples/modify_base.cpp[tags=attr] +include::samples/modify_base.cpp[tags=attr] ---- [[modify.add]] @@ -1365,7 +1372,7 @@ This is an example of adding new attributes/nodes to the document (link:samples/ [source,indent=0] ---- -include::samples/modify_add.cpp[tags=code] +include::samples/modify_add.cpp[tags=code] ---- [[modify.remove]] @@ -1402,7 +1409,7 @@ This is an example of removing attributes/nodes from the document (link:samples/ [source,indent=0] ---- -include::samples/modify_remove.cpp[tags=code] +include::samples/modify_remove.cpp[tags=code] ---- [[modify.text]] @@ -1427,13 +1434,15 @@ In addition to a string function, several functions are provided for handling te ---- bool xml_text::set(int rhs); bool xml_text::set(unsigned int rhs); +bool xml_text::set(long rhs); +bool xml_text::set(unsigned long rhs); bool xml_text::set(double rhs); bool xml_text::set(float rhs); bool xml_text::set(bool rhs); bool xml_text::set(long long rhs); bool xml_text::set(unsigned long long rhs); ---- - + The above functions convert the argument to string and then call the base `set` function. These functions have the same semantics as similar `xml_attribute` functions. You can <<xml_attribute::set_value,refer to documentation for the attribute functions>> for details. [[xml_text::assign]] @@ -1445,6 +1454,8 @@ For convenience, all `set` functions have the corresponding assignment operators xml_text& xml_text::operator=(const char_t* rhs); xml_text& xml_text::operator=(int rhs); xml_text& xml_text::operator=(unsigned int rhs); +xml_text& xml_text::operator=(long rhs); +xml_text& xml_text::operator=(unsigned long rhs); xml_text& xml_text::operator=(double rhs); xml_text& xml_text::operator=(float rhs); xml_text& xml_text::operator=(bool rhs); @@ -1458,7 +1469,7 @@ This is an example of using `xml_text` object to modify text contents (link:samp [source,indent=0] ---- -include::samples/text.cpp[tags=modify] +include::samples/text.cpp[tags=modify] ---- [[modify.clone]] @@ -1494,7 +1505,7 @@ This is an example with one possible implementation of include tags in XML (link [source,indent=0] ---- -include::samples/include.cpp[tags=code] +include::samples/include.cpp[tags=code] ---- [[modify.move]] @@ -1597,7 +1608,7 @@ This is a simple example of saving XML document to file (link:samples/save_file. [source,indent=0] ---- -include::samples/save_file.cpp[tags=code] +include::samples/save_file.cpp[tags=code] ---- [[saving.stream]] @@ -1621,7 +1632,7 @@ This is a simple example of saving XML document to standard output (link:samples [source,indent=0] ---- -include::samples/save_stream.cpp[tags=code] +include::samples/save_stream.cpp[tags=code] ---- [[saving.writer]] @@ -1649,7 +1660,7 @@ This is a simple example of custom writer for saving document data to STL string [source,indent=0] ---- -include::samples/save_custom_writer.cpp[tags=code] +include::samples/save_custom_writer.cpp[tags=code] ---- [[saving.subtree]] @@ -1671,7 +1682,7 @@ Saving a subtree differs from saving the whole document: the process behaves as [source,indent=0] ---- -include::samples/save_subtree.cpp[tags=code] +include::samples/save_subtree.cpp[tags=code] ---- [[saving.options]] @@ -1691,6 +1702,8 @@ These flags control the resulting tree contents: * [[format_no_escapes]]`format_no_escapes` disables output escaping for attribute values and PCDATA contents. If this flag is off, special symbols (`"`, `&`, `<`, `>`) and all non-printable characters (those with codepoint values less than 32) are converted to XML escape sequences (i.e. `&amp;`) during output. If this flag is on, no text processing is performed; therefore, output XML can be malformed if output contents contains invalid symbols (i.e. having a stray `<` in the PCDATA will make the output malformed). This flag is *off* by default. +* [[format_no_empty_element_tags]]`format_no_empty_element_tags` determines if start/end tags should be output instead of empty element tags for empty elements (that is, elements with no children). This flag is *off* by default. + These flags control the additional output information: * [[format_no_declaration]]`format_no_declaration` disables default node declaration output. By default, if the document is saved via `save` or `save_file` function, and it does not have any document declaration, a default declaration is output before the document contents. Enabling this flag disables this declaration. This flag has no effect in `xml_node::print` functions: they never output the default declaration. This flag is *off* by default. @@ -1708,7 +1721,7 @@ This is an example that shows the outputs of different output options (link:samp [source,indent=0] ---- -include::samples/save_options.cpp[tags=code] +include::samples/save_options.cpp[tags=code] ---- [[saving.encoding]] @@ -1735,7 +1748,7 @@ This is an example that shows how to create a custom declaration node (link:samp [source,indent=0] ---- -include::samples/save_declaration.cpp[tags=code] +include::samples/save_declaration.cpp[tags=code] ---- [[xpath]] @@ -1869,7 +1882,7 @@ This is an example of selecting nodes using XPath expressions (link:samples/xpat [source,indent=0] ---- -include::samples/xpath_select.cpp[tags=code] +include::samples/xpath_select.cpp[tags=code] ---- [[xpath.query]] @@ -1924,7 +1937,7 @@ Note that `evaluate_string` function returns the STL string; as such, it's not a size_t xpath_query::evaluate_string(char_t* buffer, size_t capacity, const xpath_node& n) const; ---- -This function evaluates the string, and then writes the result to `buffer` (but at most `capacity` characters); then it returns the full size of the result in characters, including the terminating zero. If `capacity` is not 0, the resulting buffer is always zero-terminated. You can use this function as follows: +This function evaluates the string, and then writes the result to `buffer` (but at most `capacity` characters); then it returns the full size of the result in characters, including the terminating zero. If `capacity` is not 0, the resulting buffer is always zero-terminated. You can use this function as follows: * First call the function with `buffer = 0` and `capacity = 0`; then allocate the returned amount of characters, and call the function again, passing the allocated storage and the amount of characters; * First call the function with small buffer and buffer capacity; then, if the result is larger than the capacity, the output has been trimmed, so allocate a larger buffer and call the function again. @@ -1933,7 +1946,7 @@ This is an example of using query objects (link:samples/xpath_query.cpp[]): [source,indent=0] ---- -include::samples/xpath_query.cpp[tags=code] +include::samples/xpath_query.cpp[tags=code] ---- [[xpath.variables]] @@ -2037,7 +2050,7 @@ This is an example of using variables in XPath queries (link:samples/xpath_varia [source,indent=0] ---- -include::samples/xpath_variables.cpp[tags=code] +include::samples/xpath_variables.cpp[tags=code] ---- [[xpath.errors]] @@ -2061,7 +2074,7 @@ If exceptions are disabled, then in the event of parsing failure the query is in ---- const xpath_parse_result& xpath_query::result() const; ---- - + Without exceptions, evaluating invalid query results in `false`, empty string, `NaN` or an empty node set, depending on the type; evaluating a query as a node set results in an empty node set if the return type is not node set. [[xpath_parse_result]] @@ -2095,7 +2108,7 @@ This is an example of XPath error handling (link:samples/xpath_error.cpp[]): [source,indent=0] ---- -include::samples/xpath_error.cpp[tags=code] +include::samples/xpath_error.cpp[tags=code] ---- [[xpath.w3c]] @@ -2114,8 +2127,30 @@ Because of the differences in document object models, performance considerations :!numbered: +[[v1.8]] +=== v1.8 ^2016-11-24^ + +Maintenance release. Changes: + +* Specification changes: + . When printing empty elements, a space is no longer added before / in format_raw mode + +* New features: + . Added parse_embed_pcdata parsing mode in which PCDATA value is stored in the element node if possible (significantly reducing memory consumption for some documents) + . Added auto-detection support for Latin-1 (ISO-8859-1) encoding during parsing + . Added format_no_empty_element_tags formatting flag that outputs start/end tags instead of empty element tags for empty elements + +* Performance improvements: + . Minor memory allocation improvements (yielding up to 1% memory savings in some cases) + +* Compatibility improvements: + . Fixed compilation issues for Borland C++ 5.4 + . Fixed compilation issues for some distributions of MinGW 3.8 + . Fixed various Clang/GCC warnings + . Enabled move semantics support for XPath objects for MSVC 2010 and above + [[v1.7]] -=== v1.7 ^19.10.2015^ +=== v1.7 ^2015-10-19^ Major release, featuring performance and memory improvements along with some new features. Changes: @@ -2140,7 +2175,7 @@ Major release, featuring performance and memory improvements along with some new . Fix saving for custom xml_writer implementations that can throw from write() [[v1.6]] -=== v1.6 ^10.04.2015^ +=== v1.6 ^2015-04-10^ Maintenance release. Changes: @@ -2155,7 +2190,7 @@ Maintenance release. Changes: . Adjusted processing instruction output to avoid malformed documents if the PI value contains `?>` [[v1.5]] -=== v1.5 ^27.11.2014^ +=== v1.5 ^2014-11-27^ Major release, featuring a lot of performance improvements and some new features. @@ -2188,7 +2223,7 @@ Major release, featuring a lot of performance improvements and some new features . Fix `load_file` for wide-character paths with non-ASCII characters in MinGW with C{plus}{plus}11 mode enabled [[v1.4]] -=== v1.4 ^27.02.2014^ +=== v1.4 ^2014-02-27^ Major release, featuring various new features, bug fixes and compatibility improvements. @@ -2217,7 +2252,7 @@ Major release, featuring various new features, bug fixes and compatibility impro . Fixed `find_child_by_attribute` assertion for attributes with null name/value [[v1.2]] -=== v1.2 ^1.05.2012^ +=== v1.2 ^2012-05-01^ 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. @@ -2246,7 +2281,7 @@ Major release, featuring header-only mode, various interface enhancements (i.e. . `xml_document::save_file` now checks for file I/O errors during saving [[v1.0]] -=== v1.0 ^1.11.2010^ +=== v1.0 ^2010-11-01^ Major release, featuring many XPath enhancements, wide character filename support, miscellaneous performance improvements, bug fixes and more. @@ -2311,7 +2346,7 @@ Major release, featuring many XPath enhancements, wide character filename suppor . Removed `as_utf16` function; use `as_wide` instead [[v0.9]] -=== v0.9 ^1.07.2010^ +=== v0.9 ^2010-07-01^ Major release, featuring extended and improved Unicode support, miscellaneous performance improvements, bug fixes and more. @@ -2349,7 +2384,7 @@ Major release, featuring extended and improved Unicode support, miscellaneous pe . `xpath_type_t` enumeration was renamed to `xpath_value_type`; `xpath_type_t` is deprecated and will be removed in version 1.0 [[v0.5]] -=== v0.5 ^8.11.2009^ +=== v0.5 ^2009-11-08^ Major bugfix release. Changes: @@ -2385,7 +2420,7 @@ Major bugfix release. Changes: . Added getter accessors for memory-management functions [[v0.42]] -=== v0.42 ^17.09.2009^ +=== v0.42 ^2009-09-17^ Maintenance release. Changes: @@ -2401,7 +2436,7 @@ Maintenance release. Changes: . Added `xml_attribute::set_value` overloads for different types [[v0.41]] -=== v0.41 ^8.02.2009^ +=== v0.41 ^2009-02-08^ Maintenance release. Changes: @@ -2409,7 +2444,7 @@ Maintenance release. Changes: . Fixed bug with node printing (occasionally some content was not written to output stream) [[v0.4]] -=== v0.4 ^18.01.2009^ +=== v0.4 ^2009-01-18^ Changes: @@ -2432,7 +2467,7 @@ Changes: . 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`. [[v0.34]] -=== v0.34 ^31.10.2007^ +=== v0.34 ^2007-10-31^ Maintenance release. Changes: @@ -2447,7 +2482,7 @@ Maintenance release. Changes: . `PUGIXML_NO_EXCEPTION` flag for platforms without exception handling [[v0.3]] -=== v0.3 ^21.02.2007^ +=== v0.3 ^2007-02-21^ Refactored, reworked and improved version. Changes: @@ -2470,7 +2505,7 @@ Refactored, reworked and improved version. Changes: . Fixed several bugs [[v0.2]] -=== v0.2 ^6.11.2006^ +=== v0.2 ^2006-11-06^ First public release. Changes: @@ -2484,7 +2519,7 @@ First public release. Changes: . Optimizations of `strconv_t` [[v0.1]] -=== v0.1 ^15.07.2006^ +=== v0.1 ^2006-07-15^ First private release for testing purposes @@ -2591,6 +2626,7 @@ const unsigned int +++<a href="#format_default">format_default</a>+++ const unsigned int +++<a href="#format_indent">format_indent</a>+++ const unsigned int +++<a href="#format_indent_attributes">format_indent_attributes</a>+++ const unsigned int +++<a href="#format_no_declaration">format_no_declaration</a>+++ +const unsigned int +++<a href="#format_no_empty_element_tags">format_no_empty_element_tags</a>+++ const unsigned int +++<a href="#format_no_escapes">format_no_escapes</a>+++ const unsigned int +++<a href="#format_raw">format_raw</a>+++ const unsigned int +++<a href="#format_save_file_text">format_save_file_text</a>+++ @@ -2611,10 +2647,11 @@ const unsigned int +++<a href="#parse_pi">parse_pi</a>+++ const unsigned int +++<a href="#parse_trim_pcdata">parse_trim_pcdata</a>+++ const unsigned int +++<a href="#parse_ws_pcdata">parse_ws_pcdata</a>+++ const unsigned int +++<a href="#parse_ws_pcdata_single">parse_ws_pcdata_single</a>+++ +const unsigned int +++<a href="#parse_embed_pcdata">parse_embed_pcdata</a>+++ const unsigned int +++<a href="#parse_wconv_attribute">parse_wconv_attribute</a>+++ const unsigned int +++<a href="#parse_wnorm_attribute">parse_wnorm_attribute</a>+++ ---- - + [[apiref.classes]] === Classes @@ -2654,6 +2691,8 @@ const unsigned int +++<a href="#parse_wnorm_attribute">parse_wnorm_attribute</a> bool +++<a href="#xml_attribute::set_value">set_value</a>+++(const char_t* rhs); bool +++<a href="#xml_attribute::set_value">set_value</a>+++(int rhs); bool +++<a href="#xml_attribute::set_value">set_value</a>+++(unsigned int rhs); + bool +++<a href="#xml_attribute::set_value">set_value</a>+++(long rhs); + bool +++<a href="#xml_attribute::set_value">set_value</a>+++(unsigned long rhs); bool +++<a href="#xml_attribute::set_value">set_value</a>+++(double rhs); bool +++<a href="#xml_attribute::set_value">set_value</a>+++(float rhs); bool +++<a href="#xml_attribute::set_value">set_value</a>+++(bool rhs); @@ -2663,6 +2702,8 @@ const unsigned int +++<a href="#parse_wnorm_attribute">parse_wnorm_attribute</a> xml_attribute& +++<a href="#xml_attribute::assign">operator=</a>+++(const char_t* rhs); xml_attribute& +++<a href="#xml_attribute::assign">operator=</a>+++(int rhs); xml_attribute& +++<a href="#xml_attribute::assign">operator=</a>+++(unsigned int rhs); + xml_attribute& +++<a href="#xml_attribute::assign">operator=</a>+++(long rhs); + xml_attribute& +++<a href="#xml_attribute::assign">operator=</a>+++(unsigned long rhs); xml_attribute& +++<a href="#xml_attribute::assign">operator=</a>+++(double rhs); xml_attribute& +++<a href="#xml_attribute::assign">operator=</a>+++(float rhs); xml_attribute& +++<a href="#xml_attribute::assign">operator=</a>+++(bool rhs); @@ -2847,6 +2888,8 @@ const unsigned int +++<a href="#parse_wnorm_attribute">parse_wnorm_attribute</a> bool +++<a href="#xml_text::set">set</a>+++(int rhs); bool +++<a href="#xml_text::set">set</a>+++(unsigned int rhs); + bool +++<a href="#xml_text::set">set</a>+++(long rhs); + bool +++<a href="#xml_text::set">set</a>+++(unsigned long rhs); bool +++<a href="#xml_text::set">set</a>+++(double rhs); bool +++<a href="#xml_text::set">set</a>+++(float rhs); bool +++<a href="#xml_text::set">set</a>+++(bool rhs); @@ -2856,6 +2899,8 @@ const unsigned int +++<a href="#parse_wnorm_attribute">parse_wnorm_attribute</a> xml_text& +++<a href="#xml_text::assign">operator=</a>+++(const char_t* rhs); xml_text& +++<a href="#xml_text::assign">operator=</a>+++(int rhs); xml_text& +++<a href="#xml_text::assign">operator=</a>+++(unsigned int rhs); + xml_text& +++<a href="#xml_text::assign">operator=</a>+++(long rhs); + xml_text& +++<a href="#xml_text::assign">operator=</a>+++(unsigned long rhs); xml_text& +++<a href="#xml_text::assign">operator=</a>+++(double rhs); xml_text& +++<a href="#xml_text::assign">operator=</a>+++(float rhs); xml_text& +++<a href="#xml_text::assign">operator=</a>+++(bool rhs); |