#include <DbXml.hpp>

class DbXml::XmlResults {
public:
	XmlResults();
	XmlResults(const XmlResults &);
	~XmlResults();
	XmlResults &operator = (const XmlResults &)
	...
};

The XmlResults class encapsulates the results of a query or other lookup operation. XmlResults is a collection of XmlValue objects, which may represent any one of the supported types.

An XmlResults object is created by executing a query, calling XmlIndexLookup::execute or calling XmlManager::createResults. There are several ways that a query is performed. One is to call XmlManager::query directly. This mechanism is appropriate for one-off queries that will not be repeated.

A second approach is to create an XmlQueryExpression using XmlManager::prepare. You then execute the query expression using XmlQueryExpression::execute. This approach is appropriate for queries that will be performed more than once as it means that the expense of compiling the query can be amortized across multiple queries.

Note that when you perform a query, you must provide an XmlQueryContext object. Using this object, you can indicate whether you want the query to be performed eagerly or lazily. If eager evaluation is specified (the default), then the resultant values are stored within the XmlResults object. If lazy evaluation is selected, then the resultant values will be computed as needed. In this case the XmlResults object will maintain a reference to the affected containers ( XmlContainer ), query context ( XmlQueryContext ), and expression ( XmlQueryExpression ).

The XmlResults class provides an iteration interface through the XmlResults::next method. XmlResults::next method returns false and the null value when no more results are available ( XmlValue ::isNull returns true). XmlResults::reset method can be called to reset the iterator, and the subsequent call to the XmlResults::next method will return the first value of the result set.

The copy constructor and assignment operator are provided for this class. The class is implemented using a handle-body idiom. When a handle is copied both handles maintain a reference to the same body.

An object returned from a query or other container-based operation may contains XmlValue objects that refer to persistent data that cannot be safely addressed once a transaction commits. It is possible to construct an entirely transient copy of a result set using XmlResults::copyResults. Such a copy can be used as long as the object remains in scope but its values will no longer refer to data in any container. This object is not thread-safe, and can only be safely used by one thread at a time in an application.