1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
17 ** GNU Lesser General Public License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Lesser
19 ** General Public License version 2.1 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL included in the
21 ** packaging of this file. Please review the following information to
22 ** ensure the GNU Lesser General Public License version 2.1 requirements
23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 ** In addition, as a special exception, Digia gives you certain additional
26 ** rights. These rights are described in the Digia Qt LGPL Exception
27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 ** GNU General Public License Usage
30 ** Alternatively, this file may be used under the terms of the GNU
31 ** General Public License version 3.0 as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL included in the
33 ** packaging of this file. Please review the following information to
34 ** ensure the GNU General Public License version 3.0 requirements will be
35 ** met: http://www.gnu.org/copyleft/gpl.html.
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.
54 \inmodule QtXmlPatterns
56 QXmlResultItems presents the evaluation of an associated query as a
57 sequence of \l{QXmlItem}{QXmlItems}. The sequence is traversed by
58 repeatedly calling next(), which actually produces the sequence by
59 lazy evaluation of the query.
61 \snippet code/src_xmlpatterns_api_qxmlresultitems.cpp 0
63 An effect of letting next() produce the sequence by lazy evaluation
64 is that a query error can occur on any call to next(). If an error
65 occurs, both next() and current() will return the null QXmlItem, and
66 hasError() will return true.
68 QXmlResultItems can be thought of as an "iterator" that traverses
69 the sequence of query results once, in the forward direction. Each
70 call to next() advances the iterator to the next QXmlItem in the
71 sequence and returns it, and current() always returns the QXmlItem
72 that next() returned the last time it was called.
74 \note When using the QXmlResultItems overload of QXmlQuery::evaluateTo()
75 to execute a query, it is advisable to create a new instance of this
76 class for each new set of results rather than reusing an old instance.
78 \sa QXmlItem::isNode(), QXmlItem::isAtomicValue(), QXmlNodeModelIndex
82 Constructs an instance of QXmlResultItems.
84 QXmlResultItems::QXmlResultItems() : d_ptr(new QXmlResultItemsPrivate())
89 Destroys this instance of QXmlResultItems.
91 QXmlResultItems::~QXmlResultItems()
96 Returns the next result in the sequence produced by lazy evaluation
97 of the associated query. When the returned QXmlItem is null, either
98 the evaluation terminated normally without producing another result,
99 or an error occurred. Call hasError() to determine whether the null
100 item was caused by normal termination or by an error.
102 Returns a null QXmlItem if there is no associated QXmlQuery.
104 QXmlItem QXmlResultItems::next()
106 Q_D(QXmlResultItems);
112 d->current = QPatternist::Item::toPublic(d->iterator->next());
115 catch(const QPatternist::Exception)
117 d->current = QXmlItem();
124 Returns the current item. The current item is the last item
125 that was produced and returned by next().
127 Returns a null QXmlItem if there is no associated QXmlQuery.
129 QXmlItem QXmlResultItems::current() const
131 Q_D(const QXmlResultItems);
141 If an error occurred during evaluation of the query, true is
144 Returns false if query evaluation has been done.
146 bool QXmlResultItems::hasError() const
148 Q_D(const QXmlResultItems);