Wt::Dbo::collection< C > Class Template Reference

An STL container for iterating query results. More...

#include <Wt/Dbo/collection>

Classes
class	const_iterator
	Const Iterator. More...
class	iterator
	Iterator. More...

Public Types
typedef C	value_type
	Value type.

Public Member Functions
	collection ()
	Default constructor. More...
	collection (const collection< C > &other)
	Copy constructor.
collection< C > &	operator= (const collection< C > &other)
	Assignment operator.
	~collection ()
	Destructor.
iterator	begin ()
	Returns an iterator to the begin of the collection. More...
iterator	end ()
	Returns an iterator to the end of the collection. More...
const_iterator	begin () const
	Returns a const iterator to the begin of the collection. More...
const_iterator	end () const
	Returns a const iterator to the end of the collection. More...
C	front () const
	Returns a reference to the first object. More...
size_type	size () const
	Returns the size. More...
bool	empty () const
	Returns whether the collection is empty. More...
void	insert (C c)
	Inserts an object. More...
void	erase (C c)
	Removes an object. More...
void	clear ()
	Clears the collection. More...
int	count (C c) const
	Returns the whether the collection contains an object. More...
Session *	session () const
	Returns the session to which this collection is bound.
Query< C, DynamicBinding >	find () const
	Returns the query that backs the collection. More...

Detailed Description

template<class C>
class Wt::Dbo::collection< C >

An STL container for iterating query results.

This is an STL-compatible container that is backed by an SQL query for fetching data.

A collection has two uses in Wt::Dbo:

• to iterate the results of a Query;
• to map the many-side of a Many-to-One or Many-to-Many relation.

Its iterators implement the InputIterator requirements, meaning you have to traverse the results from begin() to end() solely by alternating between reading an element and incrementing the iterator. When the collection represents the results of a Query, you can only iterate the results just once: i.e. you can have only one begin() call.

typedef dbo::collection< dbo::ptr<User> > Users;
Users allUsers = session.find<User> ();
for (Users::const_iterator i = allUsers.begin();
    i != allUsers.end(); ++i){
  dbo::ptr<User> user = *i;
}

The container is read only when it reflects results of a query.
Otherwise, when involved in a Many-to-One or Many-to-Many
relation, you may also insert() and erase() objects in it.

You will typically iterate the container results for local
processing, or copy the results into a standard STL container for
extended processing. Not only the weak guarantees of the
iterators make this recommended, but also in the current
implementation of the library, all sql statements are
non-reentrant prepared statements (this limitation is likely to
be removed in the future): only one %collection, which is backed
by the same SQL statement may be used at once per session. Thus,
the following will fail:

\code
void iterateChildren(Wt::Dbo::ptr<Comment> comment)
{
    typedef Wt::Dbo::collection<Wt::Dbo::ptr<Comment> > Comments;
    Comments children = comment->children;

    for (Comments::const_iterator i = children.begin(); i != children.end(); ++i) {
       std::cerr << "Comment: " << i->text << std::endl;
       iterateChildren(*i); // Illegal since will result in nested use of the same query.
    }
}

If you cannot gaurantee that during its iteration the same query will be reused, you should copy the results in a standard container. Note that this is no big overhead since dbo pointers are lightweight.

void iterateChildren(Wt::Dbo::ptr<Comment> comment)
{
    typedef std::vector<Wt::Dbo::ptr<Comment> > Comments;

    Comments children(comment->children.begin(), comment->children.end()); // copy into an STL container, freeing the underlying query for reuse 

    for (Comments::const_iterator i = children.begin(); i != children.end(); ++i) {
       std::cerr << "Comment: " << i->text << std::endl;
       iterateChildren(*i); // Okay now.
    }
}

Before iterating a collection, the session is flushed. In this way, the collection will reflect any pending dirty changes.

Constructor & Destructor Documentation

template<class C >

Wt::Dbo::collection< C >::collection

(

)

Default constructor.

Constructs an empty collection that is not bound to a database session or query.

Member Function Documentation

template<class C >

collection< C >::iterator Wt::Dbo::collection< C >::begin

(

)

Returns an iterator to the begin of the collection.

See also

end()

template<class C >

collection< C >::const_iterator Wt::Dbo::collection< C >::begin

(

)

const

Returns a const iterator to the begin of the collection.

See also

end()

template<class C >

void Wt::Dbo::collection< C >::clear

(

)

Clears the collection.

Note

This is only implemented for collections that are involved in a ManyToOne or ManyToMany relation, and not for collections that are used to iterated the result of a query.

See also

erase()

template<class C>

int Wt::Dbo::collection< C >::count

(

C

c

)

const

Returns the whether the collection contains an object.

This creates a suitable query that checks whether the collection contains ptr<X> objects (without getting the entire collection from the database). The returned value is the number of times the collection contains the object (0 or 1).

See also

find()

Note

This is (currently) only implemented for collections that are involved in a ManyToOne or ManyToMany relation, and not for collections that are used to iterate the result of a query.

template<class C >

bool Wt::Dbo::collection< C >::empty

(

)

const

Returns whether the collection is empty.

Returns whether size() == 0

template<class C >

collection< C >::iterator Wt::Dbo::collection< C >::end

(

)

Returns an iterator to the end of the collection.

See also

begin()

template<class C >

collection< C >::const_iterator Wt::Dbo::collection< C >::end

(

)

const

Returns a const iterator to the end of the collection.

See also

begin()

template<class C>

void Wt::Dbo::collection< C >::erase

(

C

c

)

Removes an object.

Note

This is only implemented for collections that are involved in a ManyToOne or ManyToMany relation, and not for collections that are used to iterated the result of a query.

See also

insert()

template<class C >

Query< C, DynamicBinding > Wt::Dbo::collection< C >::find

(

)

const

Returns the query that backs the collection.

Returns the query that backs the collection. This can be used to search for a subset or to browse the results in a particular order.

See also

count()

Note

This is (currently) only implemented for collections that are involved in a ManyToOne or ManyToMany relation, and not for collections that are used to iterate the result of a query.

template<class C >

C Wt::Dbo::collection< C >::front

(

)

const

Returns a reference to the first object.

This is equivalent to:

*(collection.begin())

template<class C>

void Wt::Dbo::collection< C >::insert

(

C

c

)

Inserts an object.

Note

This is only implemented for collections that are involved in a ManyToOne or ManyToMany relation, and not for collections that are used to iterated the result of a query.

See also

erase()

template<class C >

collection< C >::size_type Wt::Dbo::collection< C >::size

(

)

const

Returns the size.

This will execute an SQL count(*) statement to fetch the size of the collection without fetching all results.

If the collection represents the result of a Query, the underlying query is run only once, and its result is cached so that size() always returns the same value.