1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** No Commercial Usage
11 ** This file contains pre-release code and may not be distributed.
12 ** You may use this file in accordance with the terms and conditions
13 ** contained in the Technology Preview License Agreement accompanying
16 ** GNU Lesser General Public License Usage
17 ** Alternatively, this file may be used under the terms of the GNU Lesser
18 ** General Public License version 2.1 as published by the Free Software
19 ** Foundation and appearing in the file LICENSE.LGPL included in the
20 ** packaging of this file. Please review the following information to
21 ** ensure the GNU Lesser General Public License version 2.1 requirements
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24 ** In addition, as a special exception, Nokia gives you certain additional
25 ** rights. These rights are described in the Nokia Qt LGPL Exception
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
40 ****************************************************************************/
42 #include "qxmlresultitems.h"
43 #include "qxmlresultitems_p.h"
49 \class QXmlResultItems
50 \brief The QXmlResultItems class iterates through the results of evaluating an XQuery in QXmlQuery.
55 QXmlResultItems presents the evaluation of an associated query as a
56 sequence of \l{QXmlItem}{QXmlItems}. The sequence is traversed by
57 repeatedly calling next(), which actually produces the sequence by
58 lazy evaluation of the query.
60 \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlresultitems.cpp 0
62 An effect of letting next() produce the sequence by lazy evaluation
63 is that a query error can occur on any call to next(). If an error
64 occurs, both next() and current() will return the null QXmlItem, and
65 hasError() will return true.
67 QXmlResultItems can be thought of as an "iterator" that traverses
68 the sequence of query results once, in the forward direction. Each
69 call to next() advances the iterator to the next QXmlItem in the
70 sequence and returns it, and current() always returns the QXmlItem
71 that next() returned the last time it was called.
73 \note When using the QXmlResultItems overload of QXmlQuery::evaluateTo()
74 to execute a query, it is advisable to create a new instance of this
75 class for each new set of results rather than reusing an old instance.
77 \sa QXmlItem::isNode(), QXmlItem::isAtomicValue(), QXmlNodeModelIndex
81 Constructs an instance of QXmlResultItems.
83 QXmlResultItems::QXmlResultItems() : d_ptr(new QXmlResultItemsPrivate())
88 Destroys this instance of QXmlResultItems.
90 QXmlResultItems::~QXmlResultItems()
95 Returns the next result in the sequence produced by lazy evaluation
96 of the associated query. When the returned QXmlItem is null, either
97 the evaluation terminated normally without producing another result,
98 or an error occurred. Call hasError() to determine whether the null
99 item was caused by normal termination or by an error.
101 Returns a null QXmlItem if there is no associated QXmlQuery.
103 QXmlItem QXmlResultItems::next()
105 Q_D(QXmlResultItems);
111 d->current = QPatternist::Item::toPublic(d->iterator->next());
114 catch(const QPatternist::Exception)
116 d->current = QXmlItem();
123 Returns the current item. The current item is the last item
124 that was produced and returned by next().
126 Returns a null QXmlItem if there is no associated QXmlQuery.
128 QXmlItem QXmlResultItems::current() const
130 Q_D(const QXmlResultItems);
140 If an error occurred during evaluation of the query, true is
143 Returns false if query evaluation has been done.
145 bool QXmlResultItems::hasError() const
147 Q_D(const QXmlResultItems);