manual.qbk

[section:attrdata Setting attribute data]

[#xml_attribute::set_name][#xml_attribute::set_value]
All attributes have name and value, both of which are strings (value may be empty). You can set them with the following functions:

    bool xml_attribute::set_name(const char_t* rhs);
    bool xml_attribute::set_value(const char_t* rhs);

Both functions try to set the name\/value to the specified string, and return the operation result. The operation fails if the attribute handle is null, or if there is insufficient memory to handle the request. The provided string is copied into document managed memory and can be destroyed after the function returns (for example, you can safely pass stack-allocated buffers to these functions). The name/value content is not verified, so take care to use only valid XML names, or the document may become malformed.

In addition to string functions, several functions are provided for handling attributes with numbers and booleans as values:

    bool xml_attribute::set_value(int rhs);
    bool xml_attribute::set_value(unsigned int rhs);
    bool xml_attribute::set_value(double rhs);
    bool xml_attribute::set_value(bool 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"`.]

[note There are no portable 64-bit types in C++, so there is no corresponding `set_value` function. If your platform has a 64-bit integer, you can easily write such a function yourself.]

[#xml_attribute::assign]

For convenience, all `set_value` functions have the corresponding assignment operators:

    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=(double rhs);
    xml_attribute& xml_attribute::operator=(bool rhs);

These operators simply call the right `set_value` function and return the attribute they're called on; the return value of `set_value` is ignored, so errors are not detected.

This is an example of setting attribute name and value ([@samples/modify_base.cpp]):

[code_modify_base_attr]

[endsect] [/attrdata]

[section:add Adding nodes/attributes]

[#xml_node::append_attribute][#xml_node::insert_attribute_after][#xml_node::insert_attribute_before][#xml_node::append_child][#xml_node::insert_child_after][#xml_node::insert_child_before]
Nodes and attributes do not exist outside of document tree, so you can't create them without adding them to some document. A node or attribute can be created at the end of node/attribute list or before\/after some other node:

    xml_attribute xml_node::append_attribute(const char_t* name);
    xml_attribute xml_node::insert_attribute_after(const char_t* name, const xml_attribute& attr);
    xml_attribute xml_node::insert_attribute_before(const char_t* name, const xml_attribute& attr);

    xml_node xml_node::append_child(xml_node_type type = node_element);
    xml_node xml_node::insert_child_after(xml_node_type type, const xml_node& node);
    xml_node xml_node::insert_child_before(xml_node_type type, const xml_node& node);

`append_attribute` and `append_child` create a new node/attribute at the end of the corresponding list of the node the method is called on; `insert_attribute_after`, `insert_attribute_before`, `insert_child_after` and `insert_attribute_before` add the node\/attribute before or after specified node\/attribute.

Attribute functions create an attribute with the specified name; you can specify the empty name and change the name later if you want to. Node functions create the node with the specified type; since node type can't be changed, you have to know the desired type beforehand. Also note that not all types can be added as children; see below for clarification.

All functions return the handle to newly created object on success, and null handle on failure. There are several reasons for failure:

* Adding fails if the target node is null;
* Only `node_element` nodes can contain attributes, so attribute adding fails if node is not an element;
* Only `node_document` and `node_element` nodes can contain children, so child node adding fails if target node is not an element or a document;
* `node_document` and `node_null` nodes can not be inserted as children, so passing `node_document` or `node_null` value as type results in operation failure;
* `node_declaration` nodes can only be added as children of the document node; attempt to insert declaration node as a child of an element node fails;
* Adding node/attribute results in memory allocation, which may fail;
* Insertion functions fail if the specified node or attribute is not in the target node's children/attribute list.

Even if the operation fails, the document remains in consistent state, but the requested node/attribute is not added.

[caution attribute() and child() functions do not add attributes or nodes to the tree, so code like `node.attribute("id") = 123;` will not do anything if `node` does not have an attribute with name `"id"`. Make sure you're operating with existing attributes/nodes by adding them if necessary.]

This is an example of adding new attributes\/nodes to the document ([@samples/modify_add.cpp]):

[import samples/modify_add.cpp]
[code_modify_add]

[endsect] [/add]

[section:remove Removing nodes/attributes]

[#xml_node::remove_attribute][#xml_node::remove_child]
If you do not want your document to contain some node or attribute, you can remove it with one of the following functions:

    bool xml_node::remove_attribute(const xml_attribute& a);
    bool xml_node::remove_child(const xml_node& n);

`remove_attribute` removes the attribute from the attribute list of the node, and returns the operation result. `remove_child` removes the child node with the entire subtree (including all descendant nodes and attributes) from the document, and returns the operation result. Removing fails if one of the following is true:

* The node the function is called on is null;
* The attribute\/node to be removed is null;
* The attribute\/node to be removed is not in the node's attribute\/child list.

Removing the attribute or node invalidates all handles to the same underlying object, and also invalidates all iterators pointing to the same object. Removing node also invalidates all past-the-end iterators to its attribute or child node list. Be careful to ensure that all such handles and iterators either do not exist or are not used after the attribute\/node is removed.

If you want to remove the attribute or child node by its name, two additional helper functions are available:

    bool xml_node::remove_attribute(const char_t* name);
    bool xml_node::remove_child(const char_t* name);

These functions look for the first attribute or child with the specified name, and then remove it, returning the result. If there is no attribute or child with such name, the function returns `false`; if there are two nodes with the given name, only the first node is deleted. If you want to delete all nodes with the specified name, you can use code like this: `while (node.remove_child("tool")) ;`.

This is an example of removing attributes\/nodes from the document ([@samples/modify_remove.cpp]):

[import samples/modify_remove.cpp]
[code_modify_remove]

[endsect] [/remove]

[section:clone Cloning nodes/attributes]

[#xml_node::append_copy][#xml_node::insert_copy_after][#xml_node::insert_copy_before]
With the help of previously described functions, it is possible to create trees with any contents and structure, including cloning the existing data. However since this is an often needed operation, pugixml provides built-in node/attribute cloning facilities. Since nodes and attributes do not exist outside of document tree, you can't create a standalone copy - you have to immediately insert it somewhere in the tree. For this, you can use one of the following functions:

    xml_attribute xml_node::append_copy(const xml_attribute& proto);
    xml_attribute xml_node::insert_copy_after(const xml_attribute& proto, const xml_attribute& attr);
    xml_attribute xml_node::insert_copy_before(const xml_attribute& proto, const xml_attribute& attr);
    xml_node xml_node::append_copy(const xml_node& proto);
    xml_node xml_node::insert_copy_after(const xml_node& proto, const xml_node& node);
    xml_node xml_node::insert_copy_before(const xml_node& proto, const xml_node& node);

These functions mirror the structure of `append_child`, `insert_child_before` and related functions - they take the handle to the prototype object, which is to be cloned, insert a new attribute\/node at the appropriate place, and then copy the attribute data or the whole node subtree to the new object. The functions return the handle to the resulting duplicate object, or null handle on failure.

The attribute is copied along with the name and value; the node is copied along with its type, name and value; additionally attribute list and all children are recursively cloned, resulting in the deep subtree clone. The prototype object can be a part of the same document, or a part of any other document.

The failure conditions resemble those of `append_child`, `insert_child_before` and related functions, [link xml_node::append_child consult their documentation for more information]. There are additional caveats specific to cloning functions:

* Cloning null handles results in operation failure;
* Node cloning starts with insertion of the node of the same type as that of the prototype; for this reason, cloning functions can not be directly used to clone entire documents, since `node_document` is not a valid insertion type. The example below provides a workaround.
* It is possible to copy a subtree as a child of some node inside this subtree, i.e. `node.append_copy(node.parent().parent());`. This is a valid operation, and it results in a clone of the subtree in the state before cloning started, i.e. no infinite recursion takes place.

This is an example with one possible implementation of include tags in XML ([@samples/include.cpp]). It illustrates node cloning and usage of other document modification functions:

[import samples/include.cpp]
[code_include]

[endsect] [/clone]

[endsect] [/modify]

[section:saving Saving document]

Often after creating a new document or loading the existing one and processing it, it is necessary to save the result back to file. Also it is occasionally useful to output the whole document or a subtree to some stream; use cases include debug printing, serialization via network or other text-oriented medium, etc. pugixml provides several functions to output any subtree of the document to a file, stream or another generic transport interface; these functions allow to customize the output format (see [sref manual.saving.options]), and also perform necessary encoding conversions (see [sref manual.saving.encoding]). This section documents the relevant functionality.

The node/attribute data is written to the destination properly formatted according to the node type; all special XML symbols, such as < and &, are properly escaped. In order to guard against forgotten node/attribute names, empty node/attribute names are printed as `":anonymous"`. For proper output, make sure all node and attribute names are set to meaningful values.

[caution Currently the content of CDATA sections is not escaped, so CDATA sections with values that contain `"]]>"` will result in malformed document. This will be fixed in version 1.0.]

[section:file Saving document to a file]

[#xml_document::save_file]
If you want to save the whole document to a file, you can use the following function:

    bool xml_document::save_file(const char* path, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;

This function accepts file path as its first argument, and also three optional arguments, which specify indentation and other output options (see [sref manual.saving.options]) and output data encoding (see [sref manual.saving.encoding]). The path has the target operating system format, so it can be a relative or absolute one, it should have the delimiters of target system, it should have the exact case if target file system is case-sensitive, etc. File path is passed to system file opening function as is.

[#xml_writer_file]
`save_file` opens the target file for writing, outputs the requested header (by default a document declaration is output, unless the document already has one), and then saves the document contents. If the file could not be opened, the function returns `false`. Calling `save_file` is equivalent to creating an `xml_writer_file` object with `FILE*` handle as the only constructor argument and then calling `save`; see [sref manual.saving.writer] for writer interface details.

[note As of version 0.9, there is no function for saving XML document to wide character paths. Unfortunately, there is no portable way to do this; the version 1.0 will provide such function only for platforms with the corresponding functionality. You can use stream-saving functions as a workaround if your STL implementation can open file streams via wchar_t paths.]

This is a simple example of saving XML document to file ([@samples/save_file.cpp]):

[import samples/save_file.cpp]
[code_save_file]

[endsect] [/file]

[section:stream Saving document to C++ IOstreams]

[#xml_document::save_stream]
For additional interoperability pugixml provides functions for saving document to any object which implements C++ std::ostream interface. This allows you to save documents to any standard C++ stream (i.e. file stream) or any third-party compliant implementation (i.e. Boost Iostreams). Most notably, this allows for easy debug output, since you can use `std::cout` stream as saving target. There are two functions, one works with narrow character streams, another handles wide character ones:

    void xml_document::save(std::ostream& stream, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;
    void xml_document::save(std::wostream& stream, const char_t* indent = "\t", unsigned int flags = format_default) const;

`save` with `std::ostream` argument saves the document to the stream in the same way as `save_file` (i.e. with requested header and with encoding conversions). On the other hand, `save` with `std::wstream` argument saves the document to the wide stream with `encoding_wchar` encoding.  Because of this, using `save` with wide character streams requires careful (usually platform-specific) stream setup (i.e. using the `imbue` function). Generally use of wide streams is discouraged, however it provides you with the ability to save documents to non-Unicode encodings, i.e. you can save Shift-JIS encoded data if you set the correct locale.

[#xml_writer_stream]
Calling `save` with stream target is equivalent to creating an `xml_writer_stream` object with stream as the only constructor argument and then calling `save`; see [sref manual.saving.writer] for writer interface details.

This is a simple example of saving XML document to standard output ([@samples/save_stream.cpp]):

[import samples/save_stream.cpp]
[code_save_stream]

[endsect] [/stream]

[section:writer Saving document via writer interface]

[#xml_document::save][#xml_writer][#xml_writer::write]
All of the above saving functions are implemented in terms of writer interface. This is a simple interface with a single function, which is called several times during output process with chunks of document data as input:

    class xml_writer
    {
    public:
        virtual void write(const void* data, size_t size) = 0;
    };

    void xml_document::save(xml_writer& writer, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;

In order to output the document via some custom transport, for example sockets, you should create an object which implements `xml_writer_file` interface and pass it to `save` function. `xml_writer_file::write` function is called with a buffer as an input, where `data` points to buffer start, and `size` is equal to the buffer size in bytes. `write` implementation must write the buffer to the transport; it can not save the passed buffer pointer, as the buffer contents will change after `write` returns. The buffer contains the chunk of document data in the desired encoding.

`write` function is called with relatively large blocks (size is usually several kilobytes, except for the first block with BOM, which is output only if `format_write_bom` is set, and last block, which may be small), so there is often no need for additional buffering in the implementation.

This is a simple example of custom writer for saving document data to STL string ([@samples/save_custom_writer.cpp]); read the sample code for more complex examples:

[import samples/save_custom_writer.cpp]
[code_save_custom_writer]

[endsect] [/writer]

[section:subtree Saving a single subtree]

[#xml_node::print][#xml_node::print_stream]
While the previously described functions saved the whole document to the destination, it is easy to save a single subtree. The following functions are provided:

    void xml_node::print(std::ostream& os, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto, unsigned int depth = 0) const;
    void xml_node::print(std::wostream& os, const char_t* indent = "\t", unsigned int flags = format_default, unsigned int depth = 0) const;
    void xml_node::print(xml_writer& writer, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto, unsigned int depth = 0) const;

These functions have the same arguments with the same meaning as the corresponding `xml_document::save` functions, and allow you to save the subtree to either a C++ IOstream or to any object that implements `xml_writer` interface.

Saving a subtree differs from saving the whole document: the process behaves as if `format_write_bom` is off, and `format_no_declaration` is on, even if actual values of the flags are different. This means that BOM is not written to the destination, and document declaration is only written if it is the node itself or is one of node's children. Note that this also holds if you're saving a document; this example ([@samples/save_subtree.cpp]) illustrates the difference:

[import samples/save_subtree.cpp]
[code_save_subtree]

[endsect] [/subtree]

[section:options Output options]

All saving functions accept the optional parameter `flags`. This is a bitmask that customizes the output format; you can select the way the document nodes are printed and select the needed additional information that is output before the document contents.

[note You should use the usual bitwise arithmetics to manipulate the bitmask: to enable a flag, use `mask | flag`; to disable a flag, use `mask & ~flag`.]

These flags control the resulting tree contents:

* [anchor format_indent] determines if all nodes should be indented with the indentation string (this is an additional parameter for all saving functions, and is `"\t"` by default). If this flag is on, before every node the indentation string is output several times, where the amount of indentation depends on the node's depth relative to the output subtree. This flag has no effect if `format_raw` is enabled. This flag is *on* by default.
[lbr]

* [anchor format_raw] switches between formatted and raw output. If this flag is on, the nodes are not indented in any way, and also no newlines that are not part of document text are printed. Raw mode can be used for serialization where the result is not intended to be read by humans; also it can be useful if the document was parsed with `parse_ws_pcdata` flag, to preserve the original document formatting as much as possible. This flag is *off* by default.

These flags control the additional output information:

* [anchor format_no_declaration] allows to disable 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.
[lbr]

* [anchor format_write_bom] allows to enable Byte Order Mark (BOM) output. By default, no BOM is output, so in case of non UTF-8 encodings the resulting document's encoding may not be recognized by some parsers and text editors, if they do not implement sophisticated encoding detection. Enabling this flag adds an encoding-specific BOM to the output. This flag has no effect in `xml_node::print` functions: they never output the BOM. This flag is *off* by default.

Additionally, there is one predefined option mask:

* [anchor format_default] is the default set of flags, i.e. it has all options set to their default values. It sets formatted output with indentation, without BOM and with default node declaration, if necessary.

This is an example that shows the outputs of different output options ([@samples/save_options.cpp]):

[import samples/save_options.cpp]
[code_save_options]

[endsect] [/options]

[section:encoding Encodings]

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 during output. The output encoding is set via the `encoding` parameter of saving functions, which is of type `xml_encoding`. The possible values for the encoding are documented in [sref manual.loading.encoding]; the only flag that has a different meaning is `encoding_auto`.

While all other flags set the exact encoding, `encoding_auto` is meant for automatic encoding detection. The automatic detection does not make sense for output encoding, since there is usually nothing to infer the actual encoding from, so here `encoding_auto` means UTF-8 encoding, which is the most popular encoding for XML data storage. This is also the default value of output encoding; specify another value if you do not want UTF-8 encoded output.

Also note that wide stream saving functions do not have `encoding` argument and always assume `encoding_wchar` encoding.

[note The current behavior for Unicode conversion is to skip all invalid UTF sequences during conversion. This behavior should not be relied upon; if your node/attribute names do not contain any valid UTF sequences, they may be output as if they are empty, which will result in malformed XML document.]

[endsect] [/encoding]

[endsect] [/saving]

[section:xpath XPath]

If the task at hand is to select a subset of document nodes that match some criteria, it is possible to code a function using the existing traversal functionality for any practical criteria. However, often either a data-driven approach is desirable, in case the criteria are not predefined and come from a file, or it is inconvenient to use traversal interfaces and a higher-level DSL is required. There is a standard language for XML processing, XPath, that can be useful for these cases. pugixml implements an almost complete subset of XPath 1.0. Because of differences in document object model and some performance implications, there are minor violations of the official specifications, which can be found in [sref manual.xpath.w3c]. The rest of this section describes the interface for XPath functionality. Please note that if you wish to learn to use XPath language, you have to look for other tutorials or manuals; for example, you can read [@http://www.w3schools.com/xpath/ W3Schools XPath tutorial], [@http://www.tizag.com/xmlTutorial/xpathtutorial.php XPath tutorial at tizag.com], and [@http://www.w3.org/TR/xpath/ the XPath 1.0 specification].

[note As of version 0.9, you need both STL and exception support to use XPath; XPath is disabled if either `PUGIXML_NO_STL` or `PUGIXML_NO_EXCEPTIONS` is defined.]

[section:types XPath types]

[#xpath_value_type][#xpath_type_number][#xpath_type_string][#xpath_type_boolean][#xpath_type_node_set][#xpath_type_none]
Each XPath expression can have one of the following types: boolean, number, string or node set. Boolean type corresponds to `bool` type, number type corresponds to `double` type, string type corresponds to either `std::string` or `std::wstring`, depending on whether [link manual.dom.unicode wide character interface is enabled], and node set corresponds to `xpath_node_set` type. There is an enumeration, `xpath_value_type`, which can take the values `xpath_type_boolean`, `xpath_type_number`, `xpath_type_string` or `xpath_type_node_set`, accordingly.

[#xpath_node][#xpath_node::node][#xpath_node::attribute][#xpath_node::parent]
Because an XPath node can be either a node or an attribute, there is a special type, `xpath_node`, which is a discriminated union of these types. A value of this type contains two node handles, one of `xml_node` type, and another one of `xml_attribute` type; at most one of them can be non-null. The accessors to get these handles are available:

    xml_node xpath_node::node() const;
    xml_attribute xpath_node::attribute() const;

XPath nodes can be null, in which case both accessors return null handles.

Note that as per XPath specification, each XPath node has a parent, which can be retrieved via this function:

    xml_node xpath_node::parent() const;

`parent` function returns the node's parent if the XPath node corresponds to `xml_node` handle (equivalent to `node().parent()`), or the node to which the attribute belongs to, if the XPath node corresponds to `xml_attribute` handle. For null nodes, `parent` returns null handle.

[#xpath_node::unspecified_bool_type][#xpath_node::comparison]
Like node and attribute handles, XPath node handles can be implicitly cast to boolean-like object to check if it is a null node, and also can be compared for equality with each other.

[#xpath_node::ctor]
You can also create XPath nodes with one of tree constructors: the default constructor, the constructor that takes node argument, and the constructor that takes attribute and node arguments (in which case the attribute must belong to the attribute list of the node). However, usually you don't need to create your own XPath node objects, since they are returned to you via selection functions.

[#xpath_node_set]
XPath expressions operate not on single nodes, but instead on node sets. A node set is a collection of nodes, which can be optionally ordered in either a forward document order or a reverse one. Document order is defined in XPath specification; an XPath node is before another node in document order if it appears before it in XML representation of the corresponding document.

[#xpath_node_set::const_iterator][#xpath_node_set::begin][#xpath_node_set::end]
Node sets are represented by `xpath_node_set` object, which has an interface that resembles one of sequential random-access containers. It has an iterator type along with usual begin/past-the-end iterator accessors:

    typedef const xpath_node* xpath_node_set::const_iterator;
    const_iterator xpath_node_set::begin() const;
    const_iterator xpath_node_set::end() const;

[#xpath_node_set::index][#xpath_node_set::size][#xpath_node_set::empty]
And it also can be iterated via indices, just like `std::vector`:

    const xpath_node& xpath_node_set::operator[](size_t index) const;
    size_t xpath_node_set::size() const;
    bool xpath_node_set::empty() const;

All of the above operations have the same semantics as that of `std::vector`: the iterators are random-access, all of the above operations are constant time, and accessing the element at index that is greater or equal than the set size results in undefined behavior. You can use both iterator-based and index-based access for iteration, however the iterator-based can be faster.

[#xpath_node_set::type][#xpath_node_set::type_unsorted][#xpath_node_set::type_sorted][#xpath_node_set::type_sorted_reverse][#xpath_node_set::sort]
The order of iteration depends on the order of nodes inside the set; the order can be queried via the following function:

    enum xpath_node_set::type_t {type_unsorted, type_sorted, type_sorted_reverse};
    type_t xpath_node_set::type() const;

`type` function returns the current order of nodes; `type_sorted` means that the nodes are in forward document order, `type_sorted_reverse` means that the nodes are in reverse document order, and `type_unsorted` means that neither order is guaranteed (nodes can accidentally be in a sorted order even if `type()` returns `type_unsorted`). If you require a specific order of iteration, you can change it via `sort` function:

    void xpath_node_set::sort(bool reverse = false);

Calling `sort` sorts the nodes in either forward or reverse document order, depending on the argument; after this call `type()` will return `type_sorted` or `type_sorted_reverse`.

[#xpath_node_set::first]
Often the actual iteration is not needed; instead, only the first element in document order is required. For this, a special accessor is provided:

    xpath_node xpath_node_set::first() const;

This function returns the first node in forward document order from the set, or null node if the set is empty. Note that while the result of the node does not depend on the order of nodes in the set (i.e. on the result of `type()`), the complexity does - if the set is sorted, the complexity is constant, otherwise it is linear in the number of elements or worse.

[endsect] [/types]

[section:select Selecting nodes via XPath expression]

[#xml_node::select_single_node][#xml_node::select_nodes]
If you want to select nodes that match some XPath expression, you can do it with the following functions:

    xpath_node xml_node::select_single_node(const char_t* query) const;
    xpath_node_set xml_node::select_nodes(const char_t* query) const;

`select_nodes` function compiles the expression and then executes it with the node as a context node, and returns the resulting node set. `select_single_node` returns only the first node in document order from the result, and is equivalent to calling `select_nodes(query).first()`. If the XPath expression does not match anything, or the node handle is null, `select_nodes` returns an empty set, and `select_single_node` returns null XPath node.

Both functions throw `xpath_exception` if the query can not be compiled or if it returns a value with type other than node set; see [sref manual.xpath.errors] for details.

[#xml_node::select_single_node_precomp][#xml_node::select_nodes_precomp]
While compiling expressions is fast, the compilation time can introduce a significant overhead if the same expression is used many times on small subtrees. If you're doing many similar queries, consider compiling them into query objects (see [sref manual.xpath.query] for further reference). Once you get a compiled query object, you can pass it to select functions instead of an expression string:

    xpath_node xml_node::select_single_node(const xpath_query& query) const;
    xpath_node_set xml_node::select_nodes(const xpath_query& query) const;

Both functions throw `xpath_exception` if the query returns a value with type other than node set.

This is an example of selecting nodes using XPath expressions ([@samples/xpath_select.cpp]):

[import samples/xpath_select.cpp]
[code_xpath_select]

[endsect] [/select]

[section:query Using query objects]

[#xpath_query]
When you call `select_nodes` with an expression string as an argument, a query object is created behind the scene. A query object represents a compiled XPath expression. Query objects can be needed in the following circumstances:

* You can precompile expressions to query objects to save compilation time if it becomes an issue;
* You can use query objects to evaluate XPath expressions which result in booleans, numbers or strings;
* You can get the type of expression value via query object.

Query objects correspond to `xpath_query` type. They are immutable and non-copyable: they are bound to the expression at creation time and can not be cloned. If you want to put query objects in a container, allocate them on heap via `new` operator and store pointers to `xpath_query` in the container.

[#xpath_query::ctor]
You can create a query object with the constructor that takes XPath expression as an argument:

    explicit xpath_query::xpath_query(const char_t* query);

[#xpath_query::return_type]
The expression is compiled and the compiled representation is stored in the new query object. If compilation fails, `xpath_exception` is thrown (see [sref manual.xpath.errors] for details). After the query is created, you can query the type of the evaluation result using the following function:

    xpath_value_type xpath_query::return_type() const;

[#xpath_query::evaluate_boolean][#xpath_query::evaluate_number][#xpath_query::evaluate_string][#xpath_query::evaluate_node_set]
You can evaluate the query using one of the following functions:

    bool xpath_query::evaluate_boolean(const xml_node& n) const;
    double xpath_query::evaluate_number(const xml_node& n) const;
    string_t xpath_query::evaluate_string(const xml_node& n) const;
    xpath_node_set xpath_query::evaluate_node_set(const xml_node& n) const;

All functions take the context node as an argument, compute the expression and return the result, converted to the requested type. By XPath specification, value of any type can be converted to boolean, number or string value, but no type other than node set can be converted to node set. Because of this, `evaluate_boolean`, `evaluate_number` and `evaluate_string` always return a result, but `evaluate_node_set` throws an `xpath_exception` if the return type is not node set.

[note Calling `node.select_nodes("query")` is equivalent to calling `xpath_query("query").evaluate_node_set(node)`.]

This is an example of using query objects ([@samples/xpath_query.cpp]):

[import samples/xpath_query.cpp]
[code_xpath_query]

[endsect] [/query]

[section:errors Error handling]

[#xpath_exception][#xpath_exception::what]
As of version 0.9, all XPath errors result in thrown exceptions. The errors can arise during expression compilation or node set evaluation. In both cases, an `xpath_exception` object is thrown. This is an exception object that implements `std::exception` interface, and thus has a single function `what()`:

    virtual const char* xpath_exception::what() const throw();

This function returns the error message. Currently it is impossible to get the exact place where query compilation failed. This functionality, along with optional error handling without exceptions, will be available in version 1.0.

This is an example of XPath error handling ([@samples/xpath_error.cpp]):

[import samples/xpath_error.cpp]
[code_xpath_error]

[endsect] [/errors]

[section:w3c Conformance to W3C specification]

Because of the differences in document object models, performance considerations and implementation complexity, pugixml does not provide a fully conformant XPath 1.0 implementation. This is the current list of incompatibilities:

* Consecutive text nodes sharing the same parent are not merged, i.e. in `<node>text1 <![CDATA[data]]> text2</node>` node should have one text node children, but instead has three.
* Since document can't have a document type declaration, `id()` function always returns an empty node set.
* Namespace nodes are not supported (affects namespace:: axis).
* Name tests are performed on QNames in XML document instead of expanded names; for `<foo xmlns:ns1='uri' xmlns:ns2='uri'><ns1:child/><ns2:child/></foo>`, query `foo/ns1:*` will return only the first child, not both of them. Compliant XPath implementations can return both nodes if the user provides appropriate namespace declarations.
* String functions consider a character to be either a single `char` value or a single `wchar_t` value, depending on the library configuration; this means that some string functions are not fully Unicode-aware. This affects `substring()`, `string-length()` and `translate()` functions.
* Variable references are not supported.

Some of these incompatibilities will be fixed in version 1.0.

[endsect] [/w3c]

[endsect] [/xpath]

[section:changes Changelog]

[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++, MSVC 6, CodeWarrior 8, PGI C++, 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

[endsect] [/changes]

[section:apiref API Reference]

This is the reference for all macros, types, enumerations, classes and functions in pugixml. Each symbol is a link that leads to the relevant section of the manual.

Macros:

* `#define `[link PUGIXML_WCHAR_MODE]
* `#define `[link PUGIXML_NO_XPATH]
* `#define `[link PUGIXML_NO_STL]
* `#define `[link PUGIXML_NO_EXCEPTIONS]
* `#define `[link PUGIXML_API]
* `#define `[link PUGIXML_CLASS]
* `#define `[link PUGIXML_FUNCTION]

Types:

* `typedef `/configuration-defined type/` `[link char_t]`;`
* `typedef `/configuration-defined type/` `[link string_t]`;`
* `typedef void* (*`[link allocation_function]`)(size_t size);`
* `typedef void (*`[link deallocation_function]`)(void* ptr);`

Enumerations:

* `enum `[link xml_node_type]
    * [link node_null]
    * [link node_document]
    * [link node_element]
    * [link node_pcdata]
    * [link node_cdata]
    * [link node_comment]
    * [link node_pi]
    * [link node_declaration]
    [lbr]

* `enum `[link xml_parse_status]
    * [link status_ok]
    * [link status_file_not_found]
    * [link status_io_error]
    * [link status_out_of_memory]
    * [link status_internal_error]
    * [link status_unrecognized_tag]
    * [link status_bad_pi]
    * [link status_bad_comment]
    * [link status_bad_cdata]
    * [link status_bad_doctype]
    * [link status_bad_pcdata]
    * [link status_bad_start_element]
    * [link status_bad_attribute]
    * [link status_bad_end_element]
    * [link status_end_element_mismatch]
    [lbr]

* `enum `[link xml_encoding]
    * [link encoding_auto]
    * [link encoding_utf8]
    * [link encoding_utf16_le]
    * [link encoding_utf16_be]
    * [link encoding_utf16]
    * [link encoding_utf32_le]
    * [link encoding_utf32_be]
    * [link encoding_utf32]
    * [link encoding_wchar]
    [lbr]

* `enum `[link xpath_value_type]
    * [link xpath_type_none]
    * [link xpath_type_node_set]
    * [link xpath_type_number]
    * [link xpath_type_string]
    * [link xpath_type_boolean]

Constants:

* Formatting options bit flags:
    * [link format_default]
    * [link format_indent]
    * [link format_no_declaration]
    * [link format_raw]
    * [link format_write_bom]
    [lbr]

* Parsing options bit flags:
    * [link parse_cdata]
    * [link parse_comments]
    * [link parse_declaration]
    * [link parse_default]
    * [link parse_eol]
    * [link parse_escapes]
    * [link parse_minimal]
    * [link parse_pi]
    * [link parse_ws_pcdata]
    * [link parse_wconv_attribute]
    * [link parse_wnorm_attribute]
        
Classes:

* `class `[link xml_attribute]
    * [link xml_attribute::ctor xml_attribute]`();`
    [lbr]

    * `bool `[link xml_attribute::empty empty]`() const;`
    * `operator `[link xml_attribute::unspecified_bool_type unspecified_bool_type]`() const;`
    [lbr]

    * `bool `[link xml_attribute::comparison operator==]`(const xml_attribute& r) const;`
    * `bool `[link xml_attribute::comparison operator!=]`(const xml_attribute& r) const;`
    * `bool `[link xml_attribute::comparison operator<]`(const xml_attribute& r) const;`
    * `bool `[link xml_attribute::comparison operator>]`(const xml_attribute& r) const;`
    * `bool `[link xml_attribute::comparison operator<=]`(const xml_attribute& r) const;`
    * `bool `[link xml_attribute::comparison operator>=]`(const xml_attribute& r) const;`
    [lbr]

    * `xml_attribute `[link xml_attribute::next_attribute next_attribute]`() const;`
    * `xml_attribute `[link xml_attribute::previous_attribute previous_attribute]`() const;`
    [lbr]

    * `const char_t* `[link xml_attribute::name name]`() const;`
    * `const char_t* `[link xml_attribute::value value]`() const;`
    [lbr]

    * `int `[link xml_attribute::as_int as_int]`() const;`
    * `unsigned int `[link xml_attribute::as_uint as_uint]`() const;`
    * `double `[link xml_attribute::as_double as_double]`() const;`
    * `float `[link xml_attribute::as_float as_float]`() const;`
    * `bool `[link xml_attribute::as_bool as_bool]`() const;`
    [lbr]

    * `bool `[link xml_attribute::set_name set_name]`(const char_t* rhs);`
    * `bool `[link xml_attribute::set_value set_value]`(const char_t* rhs);`
    * `bool `[link xml_attribute::set_value set_value]`(int rhs);`
    * `bool `[link xml_attribute::set_value set_value]`(unsigned int rhs);`
    * `bool `[link xml_attribute::set_value set_value]`(double rhs);`
    * `bool `[link xml_attribute::set_value set_value]`(bool rhs);`
    [lbr]

    * `xml_attribute& `[link xml_attribute::assign operator=]`(const char_t* rhs);`
    * `xml_attribute& `[link xml_attribute::assign operator=]`(int rhs);`
    * `xml_attribute& `[link xml_attribute::assign operator=]`(unsigned int rhs);`
    * `xml_attribute& `[link xml_attribute::assign operator=]`(double rhs);`
    * `xml_attribute& `[link xml_attribute::assign operator=]`(bool rhs);`
    [lbr]

* `class `[link xml_node]
    * [link xml_node::ctor xml_node]`();`
    [lbr]

    * `bool `[link xml_node::empty empty]`() const;`
    * `operator `[link xml_node::unspecified_bool_type unspecified_bool_type]`() const;`
    [lbr]

    * `bool `[link xml_node::comparison operator==]`(const xml_node& r) const;`
    * `bool `[link xml_node::comparison operator!=]`(const xml_node& r) const;`
    * `bool `[link xml_node::comparison operator<]`(const xml_node& r) const;`
    * `bool `[link xml_node::comparison operator>]`(const xml_node& r) const;`
    * `bool `[link xml_node::comparison operator<=]`(const xml_node& r) const;`
    * `bool `[link xml_node::comparison operator>=]`(const xml_node& r) const;`
    [lbr]

    * `xml_node_type `[link xml_node::type type]`() const;`
    [lbr]

    * `const char_t* `[link xml_node::name name]`() const;`
    * `const char_t* `[link xml_node::value value]`() const;`
    [lbr]

    * `xml_node `[link xml_node::parent parent]`() const;`
    * `xml_node `[link xml_node::first_child first_child]`() const;`
    * `xml_node `[link xml_node::last_child last_child]`() const;`
    * `xml_node `[link xml_node::next_sibling next_sibling]`() const;`
    * `xml_node `[link xml_node::previous_sibling previous_sibling]`() const;`
    [lbr]

    * `xml_attribute `[link xml_node::first_attribute first_attribute]`() const;`
    * `xml_attribute `[link xml_node::last_attribute last_attribute]`() const;`
    [lbr]

    * `xml_node `[link xml_node::child child]`(const char_t* name) const;`
    * `xml_attribute `[link xml_node::attribute attribute]`(const char_t* name) const;`
    * `xml_node `[link xml_node::next_sibling_name next_sibling]`(const char_t* name) const;`
    * `xml_node `[link xml_node::previous_sibling_name previous_sibling]`(const char_t* name) const;`
    * `xml_node `[link xml_node::find_child_by_attribute find_child_by_attribute]`(const char_t* name, const char_t* attr_name, const char_t* attr_value) const;`
    * `xml_node `[link xml_node::find_child_by_attribute find_child_by_attribute]`(const char_t* attr_name, const char_t* attr_value) const;`
    [lbr]

    * `const char_t* `[link xml_node::child_value child_value]`() const;`
    * `const char_t* `[link xml_node::child_value child_value]`(const char_t* name) const;`
    [lbr]

    * `typedef xml_node_iterator `[link xml_node_iterator iterator]`;`
    * `iterator `[link xml_node::begin begin]`() const;`
    * `iterator `[link xml_node::end end]`() const;`
    [lbr]

    * `typedef xml_attribute_iterator `[link xml_attribute_iterator attribute_iterator]`;`
    * `attribute_iterator `[link xml_node::attributes_begin attributes_begin]`() const;`
    * `attribute_iterator `[link xml_node::attributes_end attributes_end]`() const;`
    [lbr]

    * `bool `[link xml_node::traverse traverse]`(xml_tree_walker& walker);`
    [lbr]

    * `template <typename Predicate> xml_attribute `[link xml_node::find_attribute find_attribute]`(Predicate pred) const;`
    * `template <typename Predicate> xml_node `[link xml_node::find_child find_child]`(Predicate pred) const;`
    * `template <typename Predicate> xml_node `[link xml_node::find_node find_node]`(Predicate pred) const;`
    [lbr]

    * `string_t `[link xml_node::path path]`(char_t delimiter = '/') const;`
    * `xml_node `[link xml_node::first_element_by_path]`(const char_t* path, char_t delimiter = '/') const;`
    * `xml_node `[link xml_node::root root]`() const;`
    * `ptrdiff_t `[link xml_node::offset_debug offset_debug]`() const;`
    [lbr]

    * `bool `[link xml_node::set_name set_name]`(const char_t* rhs);`
    * `bool `[link xml_node::set_value set_value]`(const char_t* rhs);`
    [lbr]

    * `xml_attribute `[link xml_node::append_attribute append_attribute]`(const char_t* name);`
    * `xml_attribute `[link xml_node::insert_attribute_after insert_attribute_after]`(const char_t* name, const xml_attribute& attr);`
    * `xml_attribute `[link xml_node::insert_attribute_before insert_attribute_before]`(const char_t* name, const xml_attribute& attr);`
    [lbr]

    * `xml_node `[link xml_node::append_child append_child]`(xml_node_type type = node_element);`
    * `xml_node `[link xml_node::insert_child_after insert_child_after]`(xml_node_type type, const xml_node& node);`
    * `xml_node `[link xml_node::insert_child_before insert_child_before]`(xml_node_type type, const xml_node& node);`
    [lbr]

    * `xml_attribute `[link xml_node::append_copy append_copy]`(const xml_attribute& proto);`
    * `xml_attribute `[link xml_node::insert_copy_after insert_copy_after]`(const xml_attribute& proto, const xml_attribute& attr);`
    * `xml_attribute `[link xml_node::insert_copy_before insert_copy_before]`(const xml_attribute& proto, const xml_attribute& attr);`
    [lbr]

    * `xml_node `[link xml_node::append_copy append_copy]`(const xml_node& proto);`
    * `xml_node `[link xml_node::insert_copy_after insert_copy_after]`(const xml_node& proto, const xml_node& node);`
    * `xml_node `[link xml_node::insert_copy_before insert_copy_before]`(const xml_node& proto, const xml_node& node);`
    [lbr]

    * `bool `[link xml_node::remove_attribute remove_attribute]`(const xml_attribute& a);`
    * `bool `[link xml_node::remove_attribute remove_attribute]`(const char_t* name);`
    * `bool `[link xml_node::remove_child remove_child]`(const xml_node& n);`
    * `bool `[link xml_node::remove_child remove_child]`(const char_t* name);`
    [lbr]

    * `void `[link xml_node::print print]`(xml_writer& writer, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto, unsigned int depth = 0) const;`
    * `void `[link xml_node::print_stream print]`(std::ostream& os, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto, unsigned int depth = 0) const;`
    * `void `[link xml_node::print_stream print]`(std::wostream& os, const char_t* indent = "\t", unsigned int flags = format_default, unsigned int depth = 0) const;`
    [lbr]

    * `xpath_node `[link xml_node::select_single_node select_single_node]`(const char_t* query) const;`
    * `xpath_node `[link xml_node::select_single_node_precomp select_single_node]`(const xpath_query& query) const;`
    * `xpath_node_set `[link xml_node::select_nodes select_nodes]`(const char_t* query) const;`
    * `xpath_node_set `[link xml_node::select_nodes_precomp select_nodes]`(const xpath_query& query) const;`
    [lbr]

* `class `[link xml_document]
    * [link xml_document::ctor xml_document]`();`
    * `~`[link xml_document::dtor xml_document]`();`
    [lbr]

    * `xml_parse_result `[link xml_document::load_stream load]`(std::istream& stream, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);`
    * `xml_parse_result `[link xml_document::load_stream load]`(std::wistream& stream, unsigned int options = parse_default);`
    [lbr]

    * `xml_parse_result `[link xml_document::load_string load]`(const char_t* contents, unsigned int options = parse_default);`
    [lbr]

    * `xml_parse_result `[link xml_document::load_file load_file]`(const char* path, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);`
    [lbr]

    * `xml_parse_result `[link xml_document::load_buffer load_buffer]`(const void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);`
    * `xml_parse_result `[link xml_document::load_buffer_inplace load_buffer_inplace]`(void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);`
    * `xml_parse_result `[link xml_document::load_buffer_inplace_own load_buffer_inplace_own]`(void* contents, size_t size, unsigned int options = parse_default, xml_encoding encoding = encoding_auto);`
    [lbr]

    * `bool `[link xml_document::save_file save_file]`(const char* path, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;`
    [lbr]

    * `void `[link xml_document::save_stream save]`(std::ostream& stream, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;`
    * `void `[link xml_document::save_stream save]`(std::wostream& stream, const char_t* indent = "\t", unsigned int flags = format_default) const;`
    [lbr]

    * `void `[link xml_document::save save]`(xml_writer& writer, const char_t* indent = "\t", unsigned int flags = format_default, xml_encoding encoding = encoding_auto) const;`
    [lbr]

* `struct `[link xml_parse_result]
    * `xml_parse_status `[link xml_parse_result::status status]`;`
    * `ptrdiff_t `[link xml_parse_result::offset offset]`;`
    * `xml_encoding `[link xml_parse_result::encoding encoding]`;`
    [lbr]

    * `operator `[link xml_parse_result::bool bool]`() const;`
    * `const char* `[link xml_parse_result::description description]`() const;`
    [lbr]

* `class `[link xml_node_iterator]
* `class `[link xml_attribute_iterator]
[lbr]

* `class `[link xml_tree_walker]
    * `virtual bool `[link xml_tree_walker::begin begin]`(xml_node& node);`
    * `virtual bool `[link xml_tree_walker::for_each for_each]`(xml_node& node) = 0;`
    * `virtual bool `[link xml_tree_walker::end end]`(xml_node& node);`
    [lbr]

    * `int `[link xml_tree_walker::depth depth]`() const;`
    [lbr]

* `class `[link xml_writer]
    * `virtual void `[link xml_writer::write write]`(const void* data, size_t size) = 0;`
    [lbr]

* `class `[link xml_writer_file]`: public xml_writer`
    * [link xml_writer_file]`(void* file);`
    [lbr]

* `class `[link xml_writer_stream]`: public xml_writer`
    * [link xml_writer_stream]`(std::ostream& stream);`
    * [link xml_writer_stream]`(std::wostream& stream);`
    [lbr]

* `class `[link xpath_query]
    * `explicit `[link xpath_query::ctor xpath_query]`(const char_t* query);`
    [lbr]

    * `bool `[link xpath_query::evaluate_boolean evaluate_boolean]`(const xml_node& n) const;`
    * `double `[link xpath_query::evaluate_number evaluate_number]`(const xml_node& n) const;`
    * `string_t `[link xpath_query::evaluate_string evaluate_string]`(const xml_node& n) const;`
    * `xpath_node_set `[link xpath_query::evaluate_node_set evaluate_node_set]`(const xml_node& n) const;`
    [lbr]

    * `xpath_value_type `[link xpath_query::return_type return_type]`() const;`
    [lbr]

* `class `[link xpath_exception]`: public std::exception`
    * `virtual const char* `[link xpath_exception::what what]`() const throw();`
    [lbr]

* `class `[link xpath_node]
    * [link xpath_node::ctor xpath_node]`();`
    * [link xpath_node::ctor xpath_node]`(const xml_node& node);`
    * [link xpath_node::ctor xpath_node]`(const xml_attribute& attribute, const xml_node& parent);`
    [lbr]

    * `xml_node `[link xpath_node::node node]`() const;`
    * `xml_attribute `[link xpath_node::attribute attribute]`() const;`
    * `xml_node `[link xpath_node::parent parent]`() const;`
    [lbr]

    * `operator `[link xpath_node::unspecified_bool_type unspecified_bool_type]`() const;`
    * `bool `[link xpath_node::comparison operator==]`(const xpath_node& n) const;`
    * `bool `[link xpath_node::comparison operator!=]`(const xpath_node& n) const;`
    [lbr]

* `class `[link xpath_node_set]
    * `typedef const xpath_node* `[link xpath_node_set::const_iterator const_iterator]`;`
    * `const_iterator `[link xpath_node_set::begin begin]`() const;`
    * `const_iterator `[link xpath_node_set::end end]`() const;`
    [lbr]

    * `const xpath_node& `[link xpath_node_set::index operator\[\]]`(size_t index) const;`
    * `size_t `[link xpath_node_set::size size]`() const;`
    * `bool `[link xpath_node_set::empty empty]`() const;`
    [lbr]

    * `xpath_node `[link xpath_node_set::first first]`() const;`
    [lbr]

    * `enum type_t {`[link xpath_node_set::type_unsorted type_unsorted], [link xpath_node_set::type_sorted type_sorted], [link xpath_node_set::type_sorted_reverse type_sorted_reverse]`};`
    * `type_t `[link xpath_node_set::type type]`() const;`
    * `void `[link xpath_node_set::sort sort]`(bool reverse = false);`

Functions:

* [link as_utf8]
* [link as_wide]
* [link get_memory_allocation_function]
* [link get_memory_deallocation_function]
* [link set_memory_management_functions]

[endsect] [/apiref]