src/xmlpatterns/iterators/qitemmappingiterator_p.h

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtXmlPatterns module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 //
  43 //  W A R N I N G
  44 //  -------------
  45 //
  46 // This file is not part of the Qt API.  It exists purely as an
  47 // implementation detail.  This header file may change from version to
  48 // version without notice, or even be removed.
  49 //
  50 // We mean it.
  51
  52 #ifndef Patternist_ItemMappingIterator_H
  53 #define Patternist_ItemMappingIterator_H
  54
  55 #include <private/qabstractxmlforwarditerator_p.h>
  56 #include <private/qdynamiccontext_p.h>
  57
  58 QT_BEGIN_HEADER
  59
  60 QT_BEGIN_NAMESPACE
  61
  62 namespace QPatternist
  63 {
  64     /**
  65      * @short Proxies another QAbstractXmlForwardIterator, and for each item, returns the
  66      * Item returned from a mapping function.
  67      *
  68      * ItemMappingIterator is practical when the items in an QAbstractXmlForwardIterator needs to
  69      * be translated to another sequence, while still doing it in a pipe-lined
  70      * fashion.
  71      *
  72      * This is achieved by that ItemMappingIterator's constructor takes
  73      * an instance of a class, that must have the following member:
  74      *
  75      * @code
  76      * TResult::Ptr mapToItem(const TSource &item,
  77      *                        const Context &context) const
  78      * @endcode
  79      *
  80      * For each item in the QAbstractXmlForwardIterator ItemMappingIterator proxies, this function is
  81      * called and its return value becomes the return value of the ItemMappingIterator. If the
  82      * mapping function returns null, ItemMappingIterator maps the next item in the source sequence
  83      * such that a contiguous sequence of items is returned.
  84      *
  85      * Declaring the mapToItem() function as inline, can be a good way to improve performance.
  86      *
  87      * @see SequenceMappingIterator
  88      * @author Frans Englich <frans.englich@nokia.com>
  89      * @ingroup Patternist_iterators
  90      */
  91     template<typename TResult, typename TSource, typename TMapper, typename Context = DynamicContext::Ptr>
  92     class ItemMappingIterator : public QAbstractXmlForwardIterator<TResult>
  93     {
  94     public:
  95         /**
  96          * Constructs an ItemMappingIterator.
  97          *
  98          * @param mapper the object that has the mapToItem() sequence.
  99          * @param iterator the QAbstractXmlForwardIterator whose items should be mapped.
 100          * @param context the context that will be passed to the map function.
 101          * May be null.
 102          */
 103         ItemMappingIterator(const TMapper &mapper,
 104                             const typename QAbstractXmlForwardIterator<TSource>::Ptr &iterator,
 105                             const Context &context) : m_mapper(mapper)
 106                                                     , m_it(iterator)
 107                                                     , m_context(context)
 108                                                     , m_position(0)
 109         {
 110             Q_ASSERT(mapper);
 111             Q_ASSERT(iterator);
 112         }
 113
 114         /**
 115          * @returns the next item in the sequence, or
 116          * @c null if the end have been reached.
 117          */
 118         virtual TResult next()
 119         {
 120             const TSource sourceItem(m_it->next());
 121
 122             if(qIsForwardIteratorEnd(sourceItem))
 123             {
 124                 m_current = TResult();
 125                 m_position = -1;
 126                 return TResult();
 127             }
 128             else
 129             {
 130                 m_current = m_mapper->mapToItem(sourceItem, m_context);
 131                 if(qIsForwardIteratorEnd(m_current))
 132                     return next(); /* The mapper returned null, so continue with the next in the source. */
 133                 else
 134                 {
 135                     ++m_position;
 136                     return m_current;
 137                 }
 138             }
 139         }
 140
 141         virtual TResult current() const
 142         {
 143             return m_current;
 144         }
 145
 146         virtual xsInteger position() const
 147         {
 148             return m_position;
 149         }
 150
 151         virtual typename QAbstractXmlForwardIterator<TResult>::Ptr copy() const
 152         {
 153             return typename QAbstractXmlForwardIterator<TResult>::Ptr
 154                 (new ItemMappingIterator<TResult, TSource, TMapper, Context>(m_mapper, m_it->copy(), m_context));
 155         }
 156
 157     private:
 158         const TMapper                                               m_mapper;
 159         const typename QAbstractXmlForwardIterator<TSource>::Ptr    m_it;
 160         const Context                                               m_context;
 161         TResult                                                     m_current;
 162         xsInteger                                                   m_position;
 163     };
 164
 165     /**
 166      * @short An object generator for ItemMappingIterator.
 167      *
 168      * makeItemMappingIterator() is a convenience function for avoiding specifying
 169      * the full template instantiation for ItemMappingIterator. Conceptually, it
 170      * is identical to Qt's qMakePair().
 171      *
 172      * @relates ItemMappingIterator
 173      */
 174     template<typename TResult, typename TSource, typename TMapper, typename Context>
 175     static inline
 176     typename QAbstractXmlForwardIterator<TResult>::Ptr
 177     makeItemMappingIterator(const TMapper &mapper,
 178                             const QExplicitlySharedDataPointer<QAbstractXmlForwardIterator<TSource> > &source,
 179                             const Context &context)
 180     {
 181         return typename QAbstractXmlForwardIterator<TResult>::Ptr
 182             (new ItemMappingIterator<TResult, TSource, TMapper, Context>(mapper, source, context));
 183     }
 184 }
 185
 186 QT_END_NAMESPACE
 187
 188 QT_END_HEADER
 189
 190 #endif