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 /*!

    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  */