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

Wt 4.10.4

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | List of all members
Wt::Dbo::collection< C > Class Template Reference
Database Objects (Wt::Dbo)

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

`#include <Wt/Dbo/collection.h>`

## 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.
| collection (const collection< C > &other)
| Copy constructor.
| collection (collection< C > &&other) noexcept
| Move constructor.
collection< C > & | operator= (const collection< C > &other)
| Copy assignment operator.
collection< C > & | operator= (collection< C > &&other) noexcept
| Move assignment operator.
| ~collection ()
| Destructor.
iterator | begin ()
| Returns an iterator to the begin of the collection.
iterator | end ()
| Returns an iterator to the end of the collection.
const_iterator | begin () const
| Returns a const iterator to the begin of the collection.
const_iterator | end () const
| Returns a const iterator to the end of the collection.
C | front () const
| Returns a reference to the first object.
size_type | size () const
| Returns the size.
bool | empty () const
| Returns whether the collection is empty.
void | insert (C c)
| Inserts an object.
void | erase (C c)
| Removes an object.
void | clear ()
| Clears the collection.
int | count (C c) const
| Returns the whether the collection contains an object.
Session * | session () const
| Returns the session to which this collection is bound.
Query< C, DynamicBinding > | find () const
| Returns the query that backs the collection.

## 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;
}
Wt::Dbo::Session::find
Query< ptr< C >, BindStrategy > find(const std::string &condition=std::string())
Finds database objects.
Definition Session_impl.h:265
Wt::Dbo::collection::session
Session * session() const
Returns the session to which this collection is bound.
Definition collection.h:391
Wt::EventType::User
@ User
A user-initiated event.

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:

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.
}
}
Wt::Dbo::collection
An STL container for iterating query results.
Definition WGlobal.h:280
Wt::Dbo::ptr
A smart pointer for a database object.
Definition WGlobal.h:283

If you cannot guarantee 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

## ◆ collection()

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

## ◆ begin() [1/2]

template<class C >

collection< C >::iterator Wt::Dbo::collection< C >::begin | ( |  | ) |

Returns an iterator to the begin of the collection.

See also
  end()

## ◆ begin() [2/2]

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

## ◆ clear()

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

## ◆ count()

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.

## ◆ empty()

template<class C >

bool Wt::Dbo::collection< C >::empty | ( |  | ) | const

Returns whether the collection is empty.

Returns whether size() == 0

## ◆ end() [1/2]

template<class C >

collection< C >::iterator Wt::Dbo::collection< C >::end | ( |  | ) |

Returns an iterator to the end of the collection.

See also
  begin()

## ◆ end() [2/2]

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

## ◆ erase()

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

## ◆ find()

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.

## ◆ front()

template<class C >

C Wt::Dbo::collection< C >::front | ( |  | ) | const

Returns a reference to the first object.

This is equivalent to:

*(collection.begin())
Wt::Dbo::collection::begin
iterator begin()
Returns an iterator to the begin of the collection.
Definition collection_impl.h:453

## ◆ insert()

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

## ◆ size()

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.