src/xmlpatterns/api/qxmlresultitems.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  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
  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.
  59
  60   \snippet doc/src/snippets/code/src_xmlpatterns_api_qxmlresultitems.cpp 0
  61
  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.
  66
  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.
  72
  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.
  76
  77   \sa QXmlItem::isNode(), QXmlItem::isAtomicValue(), QXmlNodeModelIndex
  78  */
  79
  80 /*!
  81   Constructs an instance of QXmlResultItems.
  82  */
  83 QXmlResultItems::QXmlResultItems() : d_ptr(new QXmlResultItemsPrivate())
  84 {
  85 }
  86
  87 /*!
  88   Destroys this instance of QXmlResultItems.
  89  */
  90 QXmlResultItems::~QXmlResultItems()
  91 {
  92 }
  93
  94 /*!
  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.
 100
 101   Returns a null QXmlItem if there is no associated QXmlQuery.
 102  */
 103 QXmlItem QXmlResultItems::next()
 104 {
 105     Q_D(QXmlResultItems);
 106     if(d->hasError)
 107         return QXmlItem();
 108
 109     try
 110     {
 111         d->current = QPatternist::Item::toPublic(d->iterator->next());
 112         return d->current;
 113     }
 114     catch(const QPatternist::Exception)
 115     {
 116         d->current = QXmlItem();
 117         d->hasError = true;
 118         return QXmlItem();
 119     }
 120 }
 121
 122 /*!
 123   Returns the current item. The current item is the last item
 124   that was produced and returned by next().
 125
 126   Returns a null QXmlItem if there is no associated QXmlQuery.
 127  */
 128 QXmlItem QXmlResultItems::current() const
 129 {
 130     Q_D(const QXmlResultItems);
 131
 132     if(d->hasError)
 133         return QXmlItem();
 134     else
 135         return d->current;
 136 }
 137
 138 /*!
 139
 140   If an error occurred during evaluation of the query, true is
 141   returned.
 142
 143   Returns false if query evaluation has been done.
 144  */
 145 bool QXmlResultItems::hasError() const
 146 {
 147     Q_D(const QXmlResultItems);
 148     return d->hasError;
 149 }
 150
 151 QT_END_NAMESPACE
 152