Wt  3.3.9
Classes | Public Types | Public Member Functions | List of all members
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...
 
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...
 
Sessionsession () const
 Returns the session to which this collection is bound.
 
Query< C, DynamicBindingfind () 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:

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)
{
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) 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)

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)

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.


Generated on Tue Nov 21 2017 for the C++ Web Toolkit (Wt) by doxygen 1.8.11