src/xmlpatterns/api/qxmlresultitems.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   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 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.
  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 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.
  24 **
  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.
  28 **
  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.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qxmlresultitems.h"
  43 #include "qxmlresultitems_p.h"
  44 #include "qitem_p.h"
  45
  46 QT_BEGIN_NAMESPACE
  47
  48 /*!
  49   \class QXmlResultItems
  50   \brief The QXmlResultItems class iterates through the results of evaluating an XQuery in QXmlQuery.
  51   \reentrant
  52   \since 4.4
  53   \ingroup xml-tools
  54   \inmodule QtXmlPatterns
  55
  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.
  60
  61   \snippet code/src_xmlpatterns_api_qxmlresultitems.cpp 0
  62
  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.
  67
  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.
  73
  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.
  77
  78   \sa QXmlItem::isNode(), QXmlItem::isAtomicValue(), QXmlNodeModelIndex
  79  */
  80
  81 /*!
  82   Constructs an instance of QXmlResultItems.
  83  */
  84 QXmlResultItems::QXmlResultItems() : d_ptr(new QXmlResultItemsPrivate())
  85 {
  86 }
  87
  88 /*!
  89   Destroys this instance of QXmlResultItems.
  90  */
  91 QXmlResultItems::~QXmlResultItems()
  92 {
  93 }
  94
  95 /*!
  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.
 101
 102   Returns a null QXmlItem if there is no associated QXmlQuery.
 103  */
 104 QXmlItem QXmlResultItems::next()
 105 {
 106     Q_D(QXmlResultItems);
 107     if(d->hasError)
 108         return QXmlItem();
 109
 110     try
 111     {
 112         d->current = QPatternist::Item::toPublic(d->iterator->next());
 113         return d->current;
 114     }
 115     catch(const QPatternist::Exception)
 116     {
 117         d->current = QXmlItem();
 118         d->hasError = true;
 119         return QXmlItem();
 120     }
 121 }
 122
 123 /*!
 124   Returns the current item. The current item is the last item
 125   that was produced and returned by next().
 126
 127   Returns a null QXmlItem if there is no associated QXmlQuery.
 128  */
 129 QXmlItem QXmlResultItems::current() const
 130 {
 131     Q_D(const QXmlResultItems);
 132
 133     if(d->hasError)
 134         return QXmlItem();
 135     else
 136         return d->current;
 137 }
 138
 139 /*!
 140
 141   If an error occurred during evaluation of the query, true is
 142   returned.
 143
 144   Returns false if query evaluation has been done.
 145  */
 146 bool QXmlResultItems::hasError() const
 147 {
 148     Q_D(const QXmlResultItems);
 149     return d->hasError;
 150 }
 151
 152 QT_END_NAMESPACE
 153