src/xmlpatterns/api/qabstractxmlforwarditerator.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 /*!
  43   \class QAbstractXmlForwardIterator
  44   \brief The QAbstractXmlForwardIterator class is a base class for forward iterators.
  45   \reentrant
  46   \since 4.4
  47   \ingroup xml-tools
  48   \internal
  49
  50   This abstract base class is for creating iterators for
  51   traversing custom data structures modeled to look like XML.
  52   An item can be instantiated in QAbstractXmlForwardIterator if:
  53   \list
  54
  55   \o It has a default constructor, a copy constructor, and an
  56   assignment operator, and
  57
  58   \o It has an appropriate qIsForwardIteratorEnd() function.
  59   \endlist
  60
  61    @ingroup Patternist_iterators
  62    @author Frans Englich <frans.englich@nokia.com>
  63  */
  64
  65 /*!
  66  \typedef QAbstractXmlForwardIterator::Ptr
  67
  68  A smart pointer wrapping an instance of a QAbstractXmlForwardIterator subclass.
  69  */
  70
  71 /*!
  72  \typedef QAbstractXmlForwardIterator::List
  73  A QList containing QAbstractXmlForwardIterator::Ptr instances.
  74  */
  75
  76 /*!
  77  \typedef QAbstractXmlForwardIterator::Vector
  78  A QVector containing QAbstractXmlForwardIterator::Ptr instances.
  79  */
  80
  81 /*!
  82   \fn QAbstractXmlForwardIterator::QAbstractXmlForwardIterator()
  83
  84   Default constructor.
  85  */
  86
  87 /*!
  88   \fn QAbstractXmlForwardIterator::~QAbstractXmlForwardIterator()
  89
  90   Destructor.
  91  */
  92
  93 /*!
  94   \fn T QAbstractXmlForwardIterator::next() = 0;
  95
  96  Returns the next item in the sequence, or
  97  a null object if the end has been reached.
  98  */
  99
 100 /*!
 101   \fn T QAbstractXmlForwardIterator::current() const = 0;
 102
 103   Returns the current item in the sequence. If this function is called
 104   before the first call to next(), a null object is returned. If the
 105   end of the sequence has been reached, a null object is returned.
 106  */
 107
 108 /*!
 109   \fn qint64 QAbstractXmlForwardIterator::position() const = 0;
 110
 111    Returns the current position in the sequence represented
 112    by \e this.
 113
 114    The first position is 1, not 0. If next() hasn't been called, 0 is
 115    returned. If \e this has reached the end, -1 is returned.
 116  */
 117
 118 /*!
 119   \fn bool qIsForwardIteratorEnd(const T &unit)
 120   \since 4.4
 121   \relates QAbstractXmlForwardIterator
 122
 123   The Callback QAbstractXmlForwardIterator uses for determining
 124   whether \a unit is the end of a sequence.
 125
 126   If \a unit is a value that would signal the end of a sequence
 127   (typically a default constructed value), this function returns \c
 128   true, otherwise \c false.
 129
 130   This implementation works for any type that has a boolean operator.
 131   For example, this function should work satisfactory for pointers.
 132  */
 133
 134 /*!
 135   \fn qint64 QAbstractXmlForwardIterator::count()
 136   \internal
 137
 138    Determines the number of items this QAbstractXmlForwardIterator
 139    represents.
 140
 141    Note that this function is not \c const. It modifies the
 142    QAbstractXmlForwardIterator. The reason for this is efficiency. If
 143    this QAbstractXmlForwardIterator must not be changed, get a copy()
 144    before performing the count.
 145
 146    The default implementation simply calls next() until the end is
 147    reached. Hence, it may be of interest to override this function if
 148    the sub-class knows a better way of computing its count.
 149
 150    The number of items in the sequence is returned.
 151  */
 152
 153 /*!
 154   \fn QAbstractXmlForwardIterator<T>::Ptr QAbstractXmlForwardIterator::toReversed();
 155   \internal
 156
 157   Returns a reverse iterator for the sequence.
 158
 159   This function may modify the iterator, it can be considered a
 160   function that evaluates this QAbstractXmlForwardIterator. It is not
 161   a \e getter, but potentially alters the iterator in the same way the
 162   next() function does. If this QAbstractXmlForwardIterator must not
 163   be modified, such that it can be used for evaluation with next(),
 164   use a copy().
 165  */
 166
 167 /*!
 168   \fn QList<T> QAbstractXmlForwardIterator<T>::toList();
 169   \internal
 170
 171    Performs a copy of this QAbstractXmlForwardIterator(with copy()),
 172    and returns its items in a QList. Thus, this function acts as a
 173    conversion function, converting the sequence to a QList.
 174
 175    This function may modify the iterator. It is not a \e getter, but
 176    potentially alters the iterator in the same way the next() function
 177    does. If this QAbstractXmlForwardIterator must not be modified,
 178    such that it can be used for evaluation with next(), use a copy().
 179  */
 180
 181 /*!
 182   \fn T QAbstractXmlForwardIterator::last();
 183   \internal
 184
 185    Returns the item at the end of this QAbstractXmlForwardIterator.
 186    The default implementation calls next() until the end is reached.
 187  */
 188
 189 /*!
 190   \fn T QAbstractXmlForwardIterator::isEmpty();
 191   \internal
 192   Returns true if the sequence is empty.
 193  */
 194
 195 /*!
 196   \fn qint64 QAbstractXmlForwardIterator::sizeHint() const;
 197   \internal
 198
 199   Gives a hint to the size of the contained sequence. The hint is
 200   assumed to be as close as possible to the actual size.
 201
 202   If no sensible estimate can be computed, -1 should be returned.
 203  */
 204
 205 /*!
 206   \fn typename QAbstractXmlForwardIterator<T>::Ptr QAbstractXmlForwardIterator::copy() const;
 207   \internal
 208
 209    Copies this QAbstractXmlForwardIterator and returns the copy.
 210
 211    A copy and the original instance are completely independent of each
 212    other. Because evaluating an QAbstractXmlForwardIterator modifies
 213    it, one should always use a copy when an
 214    QAbstractXmlForwardIterator needs to be used several times.
 215  */
 216
 217 /*!
 218   \class QPatternist::ListIteratorPlatform
 219   \brief Helper class for ListIterator, and should only be instantiated through sub-classing.
 220   \reentrant
 221   \since 4.4
 222   \internal
 223   \ingroup xml-tools
 224
 225    ListIteratorPlatform iterates an InputList with instances
 226    of InputType. For every item in it, it returns an item from it,
 227    that is converted to OutputType by calling a function on Derived
 228    that has the following signature:
 229
 230    \snippet doc/src/snippets/code/src_xmlpatterns_api_qabstractxmlforwarditerator.cpp 0
 231
 232    TODO Document why this class doesn't duplicate ItemMappingIterator.
 233  */
 234
 235 /*!
 236   \fn QPatternist::ListIteratorPlatform::ListIteratorPlatform(const ListType &list);
 237
 238   Constructs a ListIteratorPlatform that walks the given \a list.
 239  */
 240
 241 /*!
 242   \class QPatternist::ListIterator
 243   \brief Bridges values in Qt's QList container class into an QAbstractXmlForwardIterator.
 244   \reentrant
 245   \since 4.4
 246   \internal
 247   \ingroup xml-tools
 248
 249    ListIterator takes a reference to a QList<T> instance and allows
 250    access to that list via its QAbstractXmlForwardIterator interface.
 251    ListIterator is parameterized with the type to iterate over, e.g.,
 252    Item or Expression::Ptr.
 253
 254    ListIterator is used by the ExpressionSequence to create an
 255    iterator over its operands. The iterator will be passed to a
 256    MappingIterator.
 257  */
 258
 259 /*!
 260    \fn QPatternist::makeListIterator(const QList<T> &qList)
 261    \relates QPatternist::ListIterator
 262
 263    An object generator for ListIterator.
 264
 265    makeListIterator() is a convenience function to avoid specifying
 266    the full template instantiation for ListIterator.  Conceptually, it
 267    is identical to Qt's qMakePair().
 268
 269  */