1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
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 The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/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 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40//
41// W A R N I N G
42// -------------
43//
44// This file is not part of the Qt API. It exists purely as an
45// implementation detail. This header file may change from version to
46// version without notice, or even be removed.
47//
48// We mean it.
49
50#ifndef Patternist_ItemMappingIterator_H
51#define Patternist_ItemMappingIterator_H
52
53#include <private/qabstractxmlforwarditerator_p.h>
54#include <private/qdynamiccontext_p.h>
55
56QT_BEGIN_NAMESPACE
57
58namespace QPatternist
59{
60 /**
61 * @short Proxies another QAbstractXmlForwardIterator, and for each item, returns the
62 * Item returned from a mapping function.
63 *
64 * ItemMappingIterator is practical when the items in an QAbstractXmlForwardIterator needs to
65 * be translated to another sequence, while still doing it in a pipe-lined
66 * fashion.
67 *
68 * This is achieved by that ItemMappingIterator's constructor takes
69 * an instance of a class, that must have the following member:
70 *
71 * @code
72 * TResult::Ptr mapToItem(const TSource &item,
73 * const Context &context) const
74 * @endcode
75 *
76 * For each item in the QAbstractXmlForwardIterator ItemMappingIterator proxies, this function is
77 * called and its return value becomes the return value of the ItemMappingIterator. If the
78 * mapping function returns null, ItemMappingIterator maps the next item in the source sequence
79 * such that a contiguous sequence of items is returned.
80 *
81 * Declaring the mapToItem() function as inline, can be a good way to improve performance.
82 *
83 * @see SequenceMappingIterator
84 * @author Frans Englich <frans.englich@nokia.com>
85 * @ingroup Patternist_iterators
86 */
87 template<typename TResult, typename TSource, typename TMapper, typename Context = DynamicContext::Ptr>
88 class ItemMappingIterator : public QAbstractXmlForwardIterator<TResult>
89 {
90 public:
91 /**
92 * Constructs an ItemMappingIterator.
93 *
94 * @param mapper the object that has the mapToItem() sequence.
95 * @param iterator the QAbstractXmlForwardIterator whose items should be mapped.
96 * @param context the context that will be passed to the map function.
97 * May be null.
98 */
99 ItemMappingIterator(const TMapper &mapper,
100 const typename QAbstractXmlForwardIterator<TSource>::Ptr &iterator,
101 const Context &context) : m_mapper(mapper)
102 , m_it(iterator)
103 , m_context(context)
104 , m_position(0)
105 {
106 Q_ASSERT(mapper);
107 Q_ASSERT(iterator);
108 }
109
110 /**
111 * @returns the next item in the sequence, or
112 * @c null if the end have been reached.
113 */
114 virtual TResult next()
115 {
116 while (true)
117 {
118 const TSource &sourceItem = m_it->next();
119 if (qIsForwardIteratorEnd(sourceItem))
120 {
121 m_current = TResult();
122 m_position = -1;
123 return m_current;
124 }
125 else
126 {
127 m_current = m_mapper->mapToItem(sourceItem, m_context);
128 if (qIsForwardIteratorEnd(m_current))
129 {
130 continue; /* The mapper returned null, so continue with the next in the source. */
131 }
132 else
133 {
134 ++m_position;
135 return m_current;
136 }
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
186QT_END_NAMESPACE
187
188#endif
189

source code of qtxmlpatterns/src/xmlpatterns/iterators/qitemmappingiterator_p.h