ZTBQuery Class Reference
[Tuplebase, Tuplesoup]

Describes the tuple selection operations to be applied to a tuplebase or tuplesoup. More...

#include <ZTBQuery.h>

List of all members.

Canonical methods
	ZTBQuery ()
	Constructs empty query.
	ZTBQuery (const ZTBQuery &iOther)
	Copy-construct from iOther.
ZTBQuery &	operator= (const ZTBQuery &iOther)
	Assign from iOther.
	~ZTBQuery ()
	Destructor.
Conversion and assignment
	ZTBQuery (const ZTuple &iTuple)
	Construct from tuple-ized representation.
	ZTBQuery (const ZStreamR &iStreamR)
	Construct from serialized representation.
ZTuple	AsTuple () const
	Return tuple-ized representation.
void	ToStream (const ZStreamW &iStreamW) const
	Write serialized representation.
Constructors, from IDs, ZTBSpec, or using results of another query.
	ZTBQuery (uint64 iID)
	All tuples whose ID is iID (ie just the one).
	ZTBQuery (const uint64 *iIDs, size_t iCount)
	All tuples whose IDs are in iIDs.
	ZTBQuery (const std::vector< uint64 > &iIDs)
	All tuples whose IDs are in iIDs.
	ZTBQuery (const std::set< uint64 > &iIDs)
	All tuples whose IDs are in iIDs.
	ZTBQuery (const ZTBSpec &iSpec)
	All tuples which match iSpec.
	ZTBQuery (const ZTBQuery &iSourceQuery, const ZTuplePropName &iSourcePropName)
	All tuples whose ID matches values from iSourceQuery's property of type ID and name iSourcePropName.
	ZTBQuery (const ZTuplePropName &iPropName, const ZTBQuery &iSourceQuery)
	All tuples whose property iPropName is of type ID and matches IDs of tuples from iSourceQuery.
Combining operators
ZTBQuery	operator & (const ZTBSpec &iSpec) const
ZTBQuery	operator & (const ZTBQuery &iQuery) const
ZTBQuery	operator| (const ZTBQuery &iQuery) const
Sorting and selection
ZTBQuery	Sorted (const ZTuplePropName &iPropName, bool iAscending, int iStrength) const
	Ascending or descending sort by iPropName, with comparator strength iStrength.
ZTBQuery	Sorted (const ZTuplePropName &iPropName, bool iAscending) const
	Ascending or descending sort by iPropName, with comparator strength 0.
ZTBQuery	Sorted (const ZTuplePropName &iPropName) const
	Ascending sort by iPropName, with comparator strength 0.
ZTBQuery	First (const ZTuplePropName &iPropName) const
	Return only the first tuple for each unique value of iPropName.
Classes
class	SortSpec
	Describes how a single property should be sorted. More...

---

Detailed Description

Describes the tuple selection operations to be applied to a tuplebase or tuplesoup.

See also:

Tuplebase

Tuplesoup

Note:

Despite its name ZTBQuery, like ZTBSpec, knows nothing about tuplebases, tuplesoups or tuplestores. It's simply a way to create and manage a tree of simple queries and indirections through intermediate query results to be applied to a set of ID/tuple pairs, as discussed in Tuplestore. As such it probably ought to be called ZTupleQuery or ZTQuery.

Whereas ZTBSpec is a predicate against which any tuple can be checked for satisfaction, a ZTBQuery represents the selection of tuples from a set of ID/tuple pairs, and potentially the use of values from the discovered tuples to execute further selection.

The simplest ZTBQuery is also the most rare; a ZTBQuery initialized with a list of IDs. Its extension is simply the appropriate ID/tuple pairs.

The next simplest ZTBQuery is the commonest; a ZTBQuery initialized with a ZTBSpec. Its extension is the ID/tuple pairs where the tuple satisfies the ZTBSpec.

There are two further ways to initialize a complex ZTBQuery. The first is the constructor ZTBQuery(const ZTBQuery& iSourceQuery, const std::string& iSourcePropName) whose extension is the values of ID fields named iSourcePropName from tuples in the extension of iSourceQuery. For each tuple returned by iSourceQuery we take its property named iSourcePropname, and if the property is an ID we add that to the result set.

The second complex constructor is ZTBQuery(const std::string& iPropName, const ZTBQuery& iSourceQuery) whose extension is those tuples with properties named iPropName whose value is an ID that occurs in the extension of iSourceQuery.

When applied to a ZTB or a ZTSoup the extension of a ZTBQuery is a list rather than a set, as such the order of the results is potentially meaningful. The order can be specified by applying the method ZTBQuery::Sorted, each invocation which returns a new ZTBQuery whose results will be primarily ordered by the given property name. It supercedes but preserves any sort that had existed previously. So to sort primarily by prop1, then by prop2 and finally by prop3 you would do this:

  theQuery = theQuery.Sorted("prop3");
  theQuery = theQuery.Sorted("prop2");
  theQuery = theQuery.Sorted("prop1");

or more succinctly:

  theQuery.Sorted("prop3").Sorted("prop2").Sorted("prop1");

There are three overloads of ZTBQuery::Sorted. The richest specifies the property name, whether the sort should be ascending or descending, and what strength of comparison should be applied to string comparisons (ZTextCollator and discussion in ZTBSpec).

The other variants of ZTBQuery::Sorted take a property name and ascending flag, and a property name only.

I will talk about ZTBQuery::First in a later revision of this documentation, when I've updated the implementation to match the intuitive interpretation of the method.

---

Constructor & Destructor Documentation

ZTBQuery::ZTBQuery	(	const uint64 *	iIDs,
		size_t	iCount
	)

All tuples whose IDs are in iIDs.

Occasionally you'll want to explicitly reference tuples by IDs, whilst still using the ZTBQuery mechanism to do so.

---

Member Function Documentation

ZTBQuery ZTBQuery::operator &

(

const ZTBSpec &

iSpec

)

const

Returns a new ZTBQuery whose extension is the current query's extension additionally filtered by iSpec. Any sort or first applied to the current query will be preserved in the new query.

ZTBQuery ZTBQuery::operator &

(

const ZTBQuery &

iQuery

)

const

Returns a new ZTBQuery whose extension is the current query's intersected with that of of iQuery. Any sort or first applied to the current query will be preserved in the new query. Any sort or first applied to iQuery will be ignored.

ZTBQuery ZTBQuery::operator|

(

const ZTBQuery &

iQuery

)

const

Returns a new ZTBQuery whose extension is the current query's unioned with that of of iQuery. Any sort or first applied to the current query or to iQuery will be discarded.

ZTBQuery ZTBQuery::Sorted	(	const ZTuplePropName &	iPropName,
		bool	iAscending,
		int	iStrength
	)			const

Ascending or descending sort by iPropName, with comparator strength iStrength.

Returns a new ZTBQuery whose extension will be primarily sorted by iPropName, in ascending order if iAscending is true, and using a universal ZTextCollator with strength iStrength for any string comparisons.

ZTBQuery ZTBQuery::Sorted	(	const ZTuplePropName &	iPropName,
		bool	iAscending
	)			const

Ascending or descending sort by iPropName, with comparator strength 0.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

ZTBQuery ZTBQuery::Sorted

(

const ZTuplePropName &

iPropName

)

const

Ascending sort by iPropName, with comparator strength 0.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

ZTBQuery ZTBQuery::First

(

const ZTuplePropName &

iPropName

)

const

Return only the first tuple for each unique value of iPropName.

Some words

---

The documentation for this class was generated from the following files:

• src_other/tuplebase/ZTBQuery.h
• src_other/tuplebase/ZTBQuery.cpp

---