manual.qbk

[import samples/modify_base.cpp]

[section:nodedata Setting node data]

[#xml_node::set_name][#xml_node::set_value]
As discussed before, nodes can have name and value, both of which are strings. Depending on node type, name or value may be absent. `node_document` nodes do not have name or value, `node_element` and `node_declaration` nodes always have a name but never have a value, `node_pcdata`, `node_cdata` and `node_comment` nodes never have a name but always have a value (it may be empty though), `node_pi` nodes always have a name and a value (again, value may be empty). In order to set node's name or value, you can use the following functions:

    bool xml_node::set_name(const char_t* rhs);
    bool xml_node::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 node can not have name or value (for instance, when trying to call `set_name` on a `node_pcdata` node), if the node 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.

There is no equivalent of `child_value` function for modifying text children of the node.

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

[code_modify_base_node]

[endsect] [/nodedata]

[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.

CDATA sections with values that contain `"]]>"` are split into several sections as follows: section with value `"pre]]>post"` is written as `<![CDATA[pre]]]]><![CDATA[>post]]>`. While this alters the structure of the document (if you load the document after saving it, there will be two CDATA sections instead of one), this is the only way to escape CDATA contents.

[section:file Saving document to a file]

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

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

These functions accept 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 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.

[#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.

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].

[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 the three 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). The constructor from `xml_node` is implicit, so you can usually pass `xml_node` to functions that expect `xpath_node`. Apart from that you usually don't need to create your own XPath node objects, since they are returned to you via selection functions.

[#xpath_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.

[#xpath_node_set::ctor]
While in the majority of cases the node set is returned by XPath functions, sometimes there is a need to manually construct a node set. For such cases, a constructor is provided which takes an iterator range (`const_iterator` is a typedef for `const xpath_node*`), and an optional type:

	xpath_node_set::xpath_node_set(const_iterator begin, const_iterator end, type_t type = type_unsorted);

The constructor copies the specified range and sets the specified type. The objects in the range are not checked in any way; you'll have to ensure that the range contains no duplicates, and that the objects are sorted according to the `type` parameter. Otherwise XPath operations with this set may produce unexpected results.

[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, xpath_variable_set* variables = 0) const;
    xpath_node_set xml_node::select_nodes(const char_t* query, xpath_variable_set* variables = 0) 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_variable_set* variables = 0);

[#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 xpath_node& n) const;
    double xpath_query::evaluate_number(const xpath_node& n) const;
    string_t xpath_query::evaluate_string(const xpath_node& n) const;
    xpath_node_set xpath_query::evaluate_node_set(const xpath_node& n) const;

All functions take the context node as an argument, compute the expression and return the result, converted to the requested type. By XPath specification, value of any type can be converted to boolean, number or string value, but no type other than node set can be converted to node set. Because of this, `evaluate_boolean`, `evaluate_number` and `evaluate_string` always return a result, but `evaluate_node_set` results in an error if the return type is not node set (see [sref manual.xpath.errors]).

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

[#xpath_query::evaluate_string_buffer]
Note that `evaluate_string` function returns the STL string; as such, it's not available in `PUGIXML_NO_STL` mode and also usually allocates memory. There is another string evaluation function:

	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: 

* 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.

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]

There are two different mechanisms for error handling in XPath implementation; the mechanism used depends on whether exception support is disabled (this is controlled with `PUGIXML_NO_EXCEPTIONS` define).

[#xpath_exception]
[#xpath_exception::result]
[#xpath_exception::what]
By default, XPath functions throw `xpath_exception` object in case of errors; additionally, in the event any memory allocation fails, an `std::bad_alloc` exception is thrown. Also `xpath_exception` is thrown if the query is evaluated to a node set, but the return type is not node set. If the query constructor succeeds (i.e. no exception is thrown), the query object is valid. Otherwise you can get the error details via one of the following functions:

    virtual const char* xpath_exception::what() const throw();
    const xpath_parse_result& xpath_exception::result() const;

[#xpath_query::unspecified_bool_type]
[#xpath_query::result]
If exceptions are disabled, then in the event of parsing failure the query is initialized to invalid state; you can test if the query object is valid by using it in a boolean expression: `if (query) { ... }`. Additionally, you can get parsing result via the result() accessor:

    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]
The information about parsing result is returned via `xpath_parse_result` object. It contains parsing status and the offset of last successfully parsed character from the beginning of the source stream:

    struct xpath_parse_result
    {
		const char* error;
		ptrdiff_t offset;

		operator bool() const;
		const char* description() const;
    };

[#xpath_parse_result::error]
Parsing result is represented as the error message; it is either a null pointer, in case there is no error, or the error message in the form of ASCII zero-terminated string.

[#xpath_parse_result::description]
`description()` member function can be used to get the error message; it never returns the null pointer, so you can safely use description() even if query parsing succeeded.

[#xpath_parse_result::offset]
In addition to the error message, parsing result has an `offset` member, which contains the offset of last successfully parsed character. This offset is in units of `pugi::char_t` (bytes for character mode, wide characters for wide character mode).

[#xpath_parse_result::bool]
Parsing result object can be implicitly converted to `bool` like this: `if (result) { ... } else { ... }`.

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.

[endsect] [/w3c]

[endsect] [/xpath]

[section:changes Changelog]

[h5 1.11.2010 - version 1.0]

Major release, featuring many XPath enhancements, wide character filename support, miscellaneous performance improvements, bug fixes and more.

* XPath:
    # XPath implementation is moved to pugixml.cpp (which is the only source file now); use PUGIXML_NO_XPATH if you want to disable XPath to reduce code size
    # XPath is now supported without exceptions (PUGIXML_NO_EXCEPTIONS); the error handling mechanism depends on the presence of exception support
    # XPath is now supported without STL (PUGIXML_NO_STL)
    # Introduced variable support
    # Introduced new xpath_query::evaluate_string, which works without STL
    # Introduced new xpath_node_set constructor (from an iterator range)
    # Evaluation function now accept attribute context nodes
    # All internal allocations use custom allocation functions
    # Improved error reporting; now a last parsed offset is returned together with the parsing error

* Bug fixes:
    # Fixed memory leak for loading from streams with stream exceptions turned on
    # Fixed custom deallocation function calling with null pointer in one case
    # Fixed missing attributes for iterator category functions; all functions/classes can now be DLL-exported
    # Worked around Digital Mars compiler bug, which lead to minor read overfetches in several functions
    # load_file now works with 2+ Gb files in MSVC/MinGW
    # XPath: fixed memory leaks for incorrect queries
    # XPath: fixed xpath_node() attribute constructor with empty attribute argument
    # XPath: fixed lang() function for non-ASCII arguments

* Specification changes:
    # CDATA nodes containing ]]> are printed as several nodes; while this changes the internal structure, this is the only way to escape CDATA contents
    # Memory allocation errors during parsing now preserve last parsed offset (to give an idea about parsing progress)
    # Added xml_parse_result default constructor
    # Added xml_document::load_file and xml_document::save_file with wide character paths
    # Added as_utf8 and as_wide overloads for std::wstring/std::string arguments
    # Added DOCTYPE node type (node_doctype) and a special parse flag, parse_doctype, to add such nodes to the document during parsing
    # Added parse_full parse flag mask, which extends parse_default with all node type parsing flags except parse_ws_pcdata

* Performance improvements:
    # xml_node::root() and xml_node::offset_debug() are now O(1) instead of O(logN)
    # Minor parsing optimizations
    # Minor memory optimization for strings in DOM tree (set_name/set_value)
    # Memory optimization for string memory reclaiming in DOM tree (set_name/set_value now reallocate the buffer if memory waste is too big)
    # XPath: optimized document order sorting
    # XPath: optimized child/attribute axis step
    # XPath: optimized number-to-string conversions in MSVC
    # XPath: optimized concat for many arguments
    # XPath: optimized evaluation allocation mechanism: constant and document strings are not heap-allocated
    # XPath: optimized evaluation allocation mechanism: all temporaries' allocations use fast stack-like allocator

* Compatibility:
    # Removed wildcard functions (xml_node::child_w, xml_node::attribute_w, etc.)
    # Removed xml_node::all_elements_by_name
    # Removed xpath_type_t enumeration; use xpath_value_type instead
    # Removed format_write_bom_utf8 enumeration; use format_write_bom instead
    # Removed xml_document::precompute_document_order, xml_attribute::document_order and xml_node::document_order functions; document order sort optimization is now automatic
    # Removed xml_document::parse functions and transfer_ownership struct; use xml_document::load_buffer_inplace and xml_document::load_buffer_inplace_own instead
    # Removed as_utf16 function; use as_wide instead

[h5 1.07.2010 - version 0.9]

Major release, featuring extended and improved Unicode support, miscellaneous performance improvements, bug fixes and more.

* Major Unicode improvements:
    # Introduced encoding support (automatic/manual encoding detection on load, manual encoding selection on save, conversion from/to UTF8, UTF16 LE/BE, UTF32 LE/BE)
    # Introduced wchar_t mode (you can set PUGIXML_WCHAR_MODE define to switch pugixml internal encoding from UTF8 to wchar_t; all functions are switched to their Unicode variants)
    # Load/save functions now support wide streams

* Bug fixes:
    # Fixed document corruption on failed parsing bug
    # XPath string <-> number conversion improvements (increased precision, fixed crash for huge numbers)
    # Improved DOCTYPE parsing: now parser recognizes all well-formed DOCTYPE declarations
    # Fixed xml_attribute::as_uint() for large numbers (i.e. 2^32-1)
    # Fixed xml_node::first_element_by_path for path components that are prefixes of node names, but are not exactly equal to them.

* Specification changes:
    # parse() API changed to load_buffer/load_buffer_inplace/load_buffer_inplace_own; load_buffer APIs do not require zero-terminated strings.
    # Renamed as_utf16 to as_wide
    # Changed xml_node::offset_debug return type and xml_parse_result::offset type to ptrdiff_t
    # Nodes/attributes with empty names are now printed as :anonymous

* Performance improvements:
    # Optimized document parsing and saving
    # Changed internal memory management: internal allocator is used for both metadata and name/value data; allocated pages are deleted if all allocations from them are deleted
    # Optimized memory consumption: sizeof(xml_node_struct) reduced from 40 bytes to 32 bytes on x86
    # Optimized debug mode parsing/saving by order of magnitude

* Miscellaneous:
    # All STL includes except <exception> in pugixml.hpp are replaced with forward declarations
    # xml_node::remove_child and xml_node::remove_attribute now return the operation result

* Compatibility:
    # parse() and as_utf16 are left for compatibility (these functions are deprecated and will be removed in version 1.0)
    # Wildcard functions, document_order/precompute_document_order functions, all_elements_by_name function and format_write_bom_utf8 flag are deprecated and will be removed in version 1.0
    # xpath_type_t enumeration was renamed to xpath_value_type; xpath_type_t is deprecated and will be removed in version 1.0

[h5 8.11.2009 - version 0.5]

Major bugfix release. Changes:

* XPath bugfixes:
    # Fixed translate(), lang() and concat() functions (infinite loops/crashes)
    # Fixed compilation of queries with empty literal strings ("")
    # Fixed axis tests: they never add empty nodes/attributes to the resulting node set now
    # Fixed string-value evaluation for node-set (the result excluded some text descendants)
    # Fixed self:: axis (it behaved like ancestor-or-self::)
    # Fixed following:: and preceding:: axes (they included descendent and ancestor nodes, respectively)
    # Minor fix for namespace-uri() function (namespace declaration scope includes the parent element of namespace declaration attribute)
    # Some incorrect queries are no longer parsed now (i.e. foo: *)
    # Fixed text()/etc. node test parsing bug (i.e. foo[text()] failed to compile)
    # Fixed root step (/) - it now selects empty node set if query is evaluated on empty node
    # Fixed string to number conversion ("123 " converted to NaN, "123 .456" converted to 123.456 - now the results are 123 and NaN, respectively)
    # Node set copying now preserves sorted type; leads to better performance on some queries

* Miscellaneous bugfixes:
    # Fixed xml_node::offset_debug for PI nodes
    # Added empty attribute checks to xml_node::remove_attribute
    # Fixed node_pi and node_declaration copying
    # Const-correctness fixes

* Specification changes:
    # xpath_node::select_nodes() and related functions now throw exception if expression return type is not node set (instead of assertion)
    # xml_node::traverse() now sets depth to -1 for both begin() and end() callbacks (was 0 at begin() and -1 at end())
    # In case of non-raw node printing a newline is output after PCDATA inside nodes if the PCDATA has siblings
    # UTF8 -> wchar_t conversion now considers 5-byte UTF8-like sequences as invalid

* New features:
    # Added xpath_node_set::operator[] for index-based iteration
    # Added xpath_query::return_type()
    # Added getter accessors for memory-management functions

[h5 17.09.2009 - version 0.42]

Maintenance release. Changes:

* Bug fixes:
    # Fixed deallocation in case of custom allocation functions or if delete[] / free are incompatible
    # XPath parser fixed for incorrect queries (i.e. incorrect XPath queries should now always fail to compile)
    # Const-correctness fixes for find_child_by_attribute
    # Improved compatibility (miscellaneous warning fixes, fixed cstring include dependency for GCC)
    # Fixed iterator begin/end and print function to work correctly for empty nodes

* New features:
    # Added PUGIXML_API/PUGIXML_CLASS/PUGIXML_FUNCTION configuration macros to control class/function attributes
    # Added xml_attribute::set_value overloads for different types

[h5 8.02.2009 - version 0.41]

Maintenance release. Changes:

* Bug fixes:
    # Fixed bug with node printing (occasionally some content was not written to output stream)

[h5 18.01.2009 - version 0.4]

Changes:

* Bug fixes:
    # Documentation fix in samples for parse() with manual lifetime control
    # Fixed document order sorting in XPath (it caused wrong order of nodes after xpath_node_set::sort and wrong results of some XPath queries)

* Node printing changes:
    # Single quotes are no longer escaped when printing nodes
    # Symbols in second half of ASCII table are no longer escaped when printing nodes; because of this, format_utf8 flag is deleted as it's no longer needed and format_write_bom is renamed to format_write_bom_utf8.
    # Reworked node printing - now it works via xml_writer interface; implementations for FILE* and std::ostream are available. As a side-effect, xml_document::save_file now works without STL.

* New features:
    # Added unsigned integer support for attributes (xml_attribute::as_uint, xml_attribute::operator=)
    # Now document declaration (<?xml ...?>) is parsed as node with type node_declaration when parse_declaration flag is specified (access to encoding/version is performed as if they were attributes, i.e. doc.child("xml").attribute("version").as_float()); corresponding flags for node printing were also added
    # Added support for custom memory management (see set_memory_management_functions for details)
    # Implemented node/attribute copying (see xml_node::insert\_copy_* and xml_node::append_copy for details)
    # Added find_child_by_attribute and find_child_by_attribute_w to simplify parsing code in some cases (i.e. COLLADA files)
    # Added file offset information querying for debugging purposes (now you're able to determine exact location of any xml_node in parsed file, see xml_node::offset_debug for details)
    # Improved error handling for parsing - now load(), load_file() and parse() return xml_parse_result, which contains error code and last parsed offset; this does not break old interface as xml_parse_result can be implicitly casted to bool.

[h5 31.10.2007 - version 0.34]

Maintenance release. Changes:

* Bug fixes:
    # Fixed bug with loading from text-mode iostreams
    # Fixed leak when transfer_ownership is true and parsing is failing
    # Fixed bug in saving (\\r and \\n are now escaped in attribute values)
    # Renamed free() to destroy() - some macro conflicts were reported

* New features:
    # Improved compatibility (supported Digital Mars C++, 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]
    * [link node_doctype]
    [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_doctype]
    * [link parse_eol]
    * [link parse_escapes]
    * [link parse_full]
    * [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, xpath_variable_set* variables = 0) 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, xpath_variable_set* variables = 0) const;`
    * `xpath_node_set `[link xml_node::select_nodes_precomp select_nodes]`(const xpath_query& query) const;`
    [lbr]