1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 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 ** 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

    14 ** this package.

    15 **

    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.

    23 **

    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.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    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   \sa QXmlItem::isNode(), QXmlItem::isAtomicValue(), QXmlNodeModelIndex

    74  */

    75 

    76 /*!

    77   Constructs an instance of QXmlResultItems.

    78  */

    79 QXmlResultItems::QXmlResultItems() : d_ptr(new QXmlResultItemsPrivate())

    80 {

    81 }

    82 

    83 /*!

    84   Destroys this instance of QXmlResultItems.

    85  */

    86 QXmlResultItems::~QXmlResultItems()

    87 {

    88 }

    89 

    90 /*!

    91   Returns the next result in the sequence produced by lazy evaluation

    92   of the associated query. When the returned QXmlItem is null, either

    93   the evaluation terminated normally without producing another result,

    94   or an error occurred. Call hasError() to determine whether the null

    95   item was caused by normal termination or by an error.

    96 

    97   Returns a null QXmlItem if there is no associated QXmlQuery.

    98  */

    99 QXmlItem QXmlResultItems::next()

   100 {

   101     Q_D(QXmlResultItems);

   102     if(d->hasError)

   103         return QXmlItem();

   104 

   105     try

   106     {

   107         d->current = QPatternist::Item::toPublic(d->iterator->next());

   108         return d->current;

   109     }

   110     catch(const QPatternist::Exception)

   111     {

   112         d->current = QXmlItem();

   113         d->hasError = true;

   114         return QXmlItem();

   115     }

   116 }

   117 

   118 /*!

   119   Returns the current item. The current item is the last item

   120   that was produced and returned by next().

   121 

   122   Returns a null QXmlItem if there is no associated QXmlQuery.

   123  */

   124 QXmlItem QXmlResultItems::current() const

   125 {

   126     Q_D(const QXmlResultItems);

   127 

   128     if(d->hasError)

   129         return QXmlItem();

   130     else

   131         return d->current;

   132 }

   133 

   134 /*!

   135 

   136   If an error occurred during evaluation of the query, true is

   137   returned.

   138 

   139   Returns false if query evaluation has been done.

   140  */

   141 bool QXmlResultItems::hasError() const

   142 {

   143     Q_D(const QXmlResultItems);

   144     return d->hasError;

   145 }

   146 

   147 QT_END_NAMESPACE

   148