Soprano::QueryResultIterator Class Reference

An iterator for query results. More...

#include <Soprano/QueryResultIterator>

Inheritance diagram for Soprano::QueryResultIterator:
[legend]

List of all members.

Public Member Functions

 QueryResultIterator ()
 QueryResultIterator (const QueryResultIterator &)
 QueryResultIterator (QueryResultIteratorBackend *qr)
virtual ~QueryResultIterator ()
QueryResultIteratoroperator= (const QueryResultIterator &)
Statement currentStatement () const
BindingSet currentBindings () const
bool boolValue () const
Node binding (const QString &name) const
Node binding (int offset) const
int bindingCount () const
QStringList bindingNames () const
bool isGraph () const
bool isBinding () const
bool isBool () const
QList< BindingSetallBindings ()
StatementIterator iterateStatements () const
NodeIterator iterateBindings (const QString &variableName) const
NodeIterator iterateBindings (int offset) const


Detailed Description

An iterator for query results.

Query results in Soprano are wrapped in a QueryResultIterator.

Query iterators are returned by Model::executeQuery(). In contrast to NodeIterator or StatementIterator QueryResultIterator has a set of different access methods for the current dataset which can be one of three things:

Example:

 QueryResultIterator it = model->executeQuery( someGraphQuery );
 while( it.next() ) {
    doSomething( it.currentStatement() );
 }

 QueryResultIterator it2 = model->executeQuery( someTupleQuery );
 while( it.next() ) {
    doSomethingElse( it.currentBindings() );
    doSomethingCompletelyDifferent( it.binding( "x" ) );
    doSomethingEntirelyDifferent( it.binding( 0 ) );
 }

Many backends do lock the underlying Model during iteration. Thus, it is always a good idea to cache the results if they are to be used to modify the model to prevent a deadlock:

 Soprano::QueryResultIterator it = model->executeQuery( someTupleQuery );
 QList<BindingSet> allBindings = it.allBindings();
 Q_FOREACH( Soprano::BindingSet bs, allBindings ) {
    modifyTheModel( model, bs );
 }

For further details on Soprano iterators see Iterator.

Warning:
Be aware that iterators in Soprano are shared objects which means that copies of one iterator object work on the same data.
Author:
Daniele Galdi <daniele.galdi@gmail.com>
Sebastian Trueg <trueg@kde.org>

Definition at line 99 of file queryresultiterator.h.


Constructor & Destructor Documentation

Soprano::QueryResultIterator::QueryResultIterator (  ) 

Creates and empty, invalid iterator.

Soprano::QueryResultIterator::QueryResultIterator ( const QueryResultIterator  ) 

Copy constructor. Copies of iterators share their data.

Soprano::QueryResultIterator::QueryResultIterator ( QueryResultIteratorBackend qr  ) 

Create a new QueryResultIterator which uses qr as backend. QueryResultIterator will take ownership of the QueryResultIteratorBackend.

virtual Soprano::QueryResultIterator::~QueryResultIterator (  )  [virtual]

Destructor.


Member Function Documentation

QueryResultIterator& Soprano::QueryResultIterator::operator= ( const QueryResultIterator  ) 

Copies of iterators share their data.

Statement Soprano::QueryResultIterator::currentStatement (  )  const

Retrieve the current Statement after a call to next. This method does only make sense for graph queries.

BindingSet Soprano::QueryResultIterator::currentBindings (  )  const

Convenience method that puts all current bindings into one map. This method does only make sense for tuple queries.

bool Soprano::QueryResultIterator::boolValue (  )  const

This method does only make sense for boolean queries.

Returns:
The result of a boolean query (SPARQL ASK).
See also:
isBool()

Node Soprano::QueryResultIterator::binding ( const QString name  )  const

Get the current binding for a variable.

Parameters:
name The name of the requested variable.
This method does only make sense for tuple queries.

Returns:
The binding for the requested variable or and invalid node if the bindings do not contain the variable.

Node Soprano::QueryResultIterator::binding ( int  offset  )  const

Get the current binding for a variable by index.

Parameters:
offset The index of the requested variable.
This method does only make sense for tuple queries.

Returns:
The binding for the requested variable or and invalid node if offset is out of bounds, i.e. bigger or equal to bindingCount().

int Soprano::QueryResultIterator::bindingCount (  )  const

The number of bindings in this query result.

This method does only make sense for tuple queries.

Returns:
The number of bindings.

QStringList Soprano::QueryResultIterator::bindingNames (  )  const

This method does only make sense for tuple queries.

Returns:
The names of the bound variables in this query result.

bool Soprano::QueryResultIterator::isGraph (  )  const

Check if this is a graph result.

Returns:
true if this result refers to a graph query, i.e. currentStatement() and iterateStatements() return valid values.

bool Soprano::QueryResultIterator::isBinding (  )  const

Check if this is a tuple result.

Returns:
true if this result refers to a tuple query, i.e. currentBindings(), binding(), bindingCount(), bindingNames(), and allBindings() return valid values.

bool Soprano::QueryResultIterator::isBool (  )  const

Check if this is a boolean result.

There is no need to call next() for boolean results. However, for internal reasons backends need to always return true for boolean queries.

Returns:
true if this result refers to a boolean query (SPARQL ASK), i.e. boolValue() returns a valid value.

QList<BindingSet> Soprano::QueryResultIterator::allBindings (  ) 

Convenience method that collects all binding sets that are left in the iterator.

StatementIterator Soprano::QueryResultIterator::iterateStatements (  )  const

Convenience method that creates an iterator over the statements in this query result. This method does only make sense for graph queries.

Warning:
The new iterator is just a wrapper around this one. Thus, changing it will also change this one.
Returns:
A wrapper iterator over the statements in a graph query.

NodeIterator Soprano::QueryResultIterator::iterateBindings ( const QString variableName  )  const

Convenience method that creates an iterator over one column of bindings in this query result. This method does only make sense for tuple queries.

Parameters:
variableName The name of the requested variable.
Warning:
The new iterator is just a wrapper around this one. Thus, changing it will also change this one.
Returns:
A wrapper iterator over one column in a tuple query or an invalid iterator if the result does not contain bindings for variableName.

NodeIterator Soprano::QueryResultIterator::iterateBindings ( int  offset  )  const

Convenience method that creates an iterator over one column of bindings in this query result. This method does only make sense for tuple queries.

Parameters:
offset The index of the requested variable.
Warning:
The new iterator is just a wrapper around this one. Thus, changing it will also change this one.
Returns:
A wrapper iterator over one column in a tuple query or an invalid iterator if offset is out of bounds, i.e. bigger or equal to bindingCount().


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

Generated on Wed Mar 5 20:46:55 2008 for Soprano by  doxygen 1.5.5