1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtXmlPatterns module of the Qt Toolkit.
7**
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 The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
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 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include "qxmlresultitems.h"
41#include "qxmlresultitems_p.h"
42#include "qitem_p.h"
43
44QT_BEGIN_NAMESPACE
45
46/*!
47 \class QXmlResultItems
48 \brief The QXmlResultItems class iterates through the results of evaluating an XQuery in QXmlQuery.
49 \reentrant
50 \since 4.4
51 \ingroup xml-tools
52 \inmodule QtXmlPatterns
53
54 QXmlResultItems presents the evaluation of an associated query as a
55 sequence of \l{QXmlItem}{QXmlItems}. The sequence is traversed by
56 repeatedly calling next(), which actually produces the sequence by
57 lazy evaluation of the query.
58
59 \snippet code/src_xmlpatterns_api_qxmlresultitems.cpp 0
60
61 An effect of letting next() produce the sequence by lazy evaluation
62 is that a query error can occur on any call to next(). If an error
63 occurs, both next() and current() will return the null QXmlItem, and
64 hasError() will return true.
65
66 QXmlResultItems can be thought of as an "iterator" that traverses
67 the sequence of query results once, in the forward direction. Each
68 call to next() advances the iterator to the next QXmlItem in the
69 sequence and returns it, and current() always returns the QXmlItem
70 that next() returned the last time it was called.
71
72 \note When using the QXmlResultItems overload of QXmlQuery::evaluateTo()
73 to execute a query, it is advisable to create a new instance of this
74 class for each new set of results rather than reusing an old instance.
75
76 \sa QXmlItem::isNode(), QXmlItem::isAtomicValue(), QXmlNodeModelIndex
77 */
78
79/*!
80 Constructs an instance of QXmlResultItems.
81 */
82QXmlResultItems::QXmlResultItems() : d_ptr(new QXmlResultItemsPrivate())
83{
84}
85
86/*!
87 Destroys this instance of QXmlResultItems.
88 */
89QXmlResultItems::~QXmlResultItems()
90{
91}
92
93/*!
94 Returns the next result in the sequence produced by lazy evaluation
95 of the associated query. When the returned QXmlItem is null, either
96 the evaluation terminated normally without producing another result,
97 or an error occurred. Call hasError() to determine whether the null
98 item was caused by normal termination or by an error.
99
100 Returns a null QXmlItem if there is no associated QXmlQuery.
101 */
102QXmlItem QXmlResultItems::next()
103{
104 Q_D(QXmlResultItems);
105 if(d->hasError)
106 return QXmlItem();
107
108 try
109 {
110 d->current = QPatternist::Item::toPublic(i: d->iterator->next());
111 return d->current;
112 }
113 catch(const QPatternist::Exception)
114 {
115 d->current = QXmlItem();
116 d->hasError = true;
117 return QXmlItem();
118 }
119}
120
121/*!
122 Returns the current item. The current item is the last item
123 that was produced and returned by next().
124
125 Returns a null QXmlItem if there is no associated QXmlQuery.
126 */
127QXmlItem QXmlResultItems::current() const
128{
129 Q_D(const QXmlResultItems);
130
131 if(d->hasError)
132 return QXmlItem();
133 else
134 return d->current;
135}
136
137/*!
138
139 If an error occurred during evaluation of the query, true is
140 returned.
141
142 Returns false if query evaluation has been done.
143 */
144bool QXmlResultItems::hasError() const
145{
146 Q_D(const QXmlResultItems);
147 return d->hasError;
148}
149
150QT_END_NAMESPACE
151
152

source code of qtxmlpatterns/src/xmlpatterns/api/qxmlresultitems.cpp