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