1//
2// NodeIterator.h
3//
4// Library: XML
5// Package: DOM
6// Module: NodeIterator
7//
8// Definition of the DOM NodeIterator class.
9//
10// Copyright (c) 2004-2006, Applied Informatics Software Engineering GmbH.
11// and Contributors.
12//
13// SPDX-License-Identifier: BSL-1.0
14//
15
16
17#ifndef DOM_NodeIterator_INCLUDED
18#define DOM_NodeIterator_INCLUDED
19
20
21#include "Poco/XML/XML.h"
22
23
24namespace Poco {
25namespace XML {
26
27
28class Node;
29class NodeFilter;
30
31
32class XML_API NodeIterator
33 /// Iterators are used to step through a set of nodes, e.g. the set of nodes
34 /// in a NodeList, the document subtree governed by a particular Node, the results
35 /// of a query, or any other set of nodes. The set of nodes to be iterated is
36 /// determined by the implementation of the NodeIterator. DOM Level 2 specifies
37 /// a single NodeIterator implementation for document-order traversal of a document
38 /// subtree.
39 ///
40 /// A NodeIterator can be directly instantiated using one of its constructors -
41 /// the DocumentTraversal interface is not needed and therefore not implemented.
42 /// Unlike most other DOM classes, NodeIterator supports value semantics.
43 ///
44 /// If the NodeIterator's current node is removed from the document, the
45 /// result of calling any of the movement methods is undefined. This behavior does
46 /// not conform to the DOM Level 2 Traversal specification.
47{
48public:
49 NodeIterator(Node* root, unsigned long whatToShow, NodeFilter* pFilter = 0);
50 /// Creates a NodeIterator over the subtree rooted at the specified node.
51
52 NodeIterator(const NodeIterator& iterator);
53 /// Creates a NodeIterator by copying another NodeIterator.
54
55 NodeIterator& operator = (const NodeIterator& iterator);
56 /// Assignment operator.
57
58 ~NodeIterator();
59 /// Destroys the NodeIterator.
60
61 Node* root() const;
62 /// The root node of the NodeIterator, as specified when it was created.
63
64 unsigned long whatToShow() const;
65 /// This attribute determines which node types are presented via the iterator.
66 /// The available set of constants is defined in the NodeFilter interface.
67 /// Nodes not accepted by whatToShow will be skipped, but their children may
68 /// still be considered. Note that this skip takes precedence over the filter,
69 /// if any.
70
71 NodeFilter* filter() const;
72 /// The NodeFilter used to screen nodes.
73
74 bool expandEntityReferences() const;
75 /// The value of this flag determines whether the children of entity reference
76 /// nodes are visible to the iterator. If false, they and their descendants
77 /// will be rejected. Note that this rejection takes precedence over whatToShow
78 /// and the filter. Also note that this is currently the only situation where
79 /// NodeIterators may reject a complete subtree rather than skipping individual
80 /// nodes.
81 ///
82 /// To produce a view of the document that has entity references expanded and
83 /// does not expose the entity reference node itself, use the whatToShow flags
84 /// to hide the entity reference node and set expandEntityReferences to true
85 /// when creating the iterator. To produce a view of the document that has entity
86 /// reference nodes but no entity expansion, use the whatToShow flags to show
87 /// the entity reference node and set expandEntityReferences to false.
88 ///
89 /// This implementation does not support entity reference expansion and
90 /// thus always returns false.
91
92 Node* nextNode();
93 /// Returns the next node in the set and advances the position of the iterator
94 /// in the set. After a NodeIterator is created, the first call to nextNode()
95 /// returns the first node in the set.
96
97 Node* previousNode();
98 /// Returns the previous node in the set and moves the position of the NodeIterator
99 /// backwards in the set.
100
101 Node* currentNodeNP() const;
102 /// Returns the current node in the set.
103 ///
104 /// Leaves the NodeIterator unchanged.
105 ///
106 /// Warning: This is a proprietary extension to the DOM Level 2 NodeIterator
107 /// interface.
108
109 void detach();
110 /// Detaches the NodeIterator from the set which it iterated over, releasing
111 /// any computational resources and placing the iterator in the INVALID state.
112 /// After detach has been invoked, calls to nextNode or previousNode will raise
113 /// the exception INVALID_STATE_ERR.
114
115protected:
116 bool accept(Node* pNode) const;
117 Node* next() const;
118 Node* previous() const;
119 Node* last();
120
121private:
122 NodeIterator();
123
124 Node* _pRoot;
125 unsigned long _whatToShow;
126 NodeFilter* _pFilter;
127 Node* _pCurrent;
128};
129
130
131//
132// inlines
133//
134inline Node* NodeIterator::root() const
135{
136 return _pRoot;
137}
138
139
140inline Node* NodeIterator::currentNodeNP() const
141{
142 return _pCurrent;
143}
144
145
146inline unsigned long NodeIterator::whatToShow() const
147{
148 return _whatToShow;
149}
150
151
152inline NodeFilter* NodeIterator::filter() const
153{
154 return _pFilter;
155}
156
157
158inline bool NodeIterator::expandEntityReferences() const
159{
160 return false;
161}
162
163
164} } // namespace Poco::XML
165
166
167#endif // DOM_NodeIterator_INCLUDED
168