NCBI C++ ToolKit
node_set.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 /* $Id: node_set.hpp 79080 2017-08-09 18:22:55Z satskyse $
2  * ===========================================================================
3  *
4  * PUBLIC DOMAIN NOTICE
5  * National Center for Biotechnology Information
6  *
7  * This software/database is a "United States Government Work" under the
8  * terms of the United States Copyright Act. It was written as part of
9  * the author's official duties as a United States Government employee and
10  * thus cannot be copyrighted. This software/database is freely available
11  * to the public for use. The National Library of Medicine and the U.S.
12  * Government have not placed any restriction on its use or reproduction.
13  *
14  * Although all reasonable efforts have been taken to ensure the accuracy
15  * and reliability of the software and data, the NLM and the U.S.
16  * Government do not and cannot warrant the performance or results that
17  * may be obtained by using this software or data. The NLM and the U.S.
18  * Government disclaim all warranties, express or implied, including
19  * warranties of performance, merchantability or fitness for any particular
20  * purpose.
21  *
22  * Please cite the author in any work or product based on this material.
23  *
24  * ===========================================================================
25  *
26  * Author: Sergey Satskiy, NCBI
27  * Credits: Denis Vakatov, NCBI (API design)
28  *
29  */
30 
31 
32 /** @file
33  * XPath execution result set for XmlWrapp.
34 **/
35 
36 #ifndef _xmlwrapp_node_set_hpp_
37 #define _xmlwrapp_node_set_hpp_
38 
39 // xmlwrapp includes
41 #include <misc/xmlwrapp/node.hpp>
42 
43 // standard includes
44 #include <cstddef>
45 
46 namespace xslt {
47  class xpath_object;
48 }
49 
50 namespace xml {
51 
52 // forward declaration
53 namespace impl
54 {
55  struct nset_impl;
56 }
57 
58 
59 /**
60  * The xml::node_set class is used to store xpath query result set.
61  * The object implements reference counting so once created while an xpath
62  * query was executed, the copies of this object refer to the same set of xml
63  * document nodes as the original one.
64  * Please note that the reference counting implementation is NOT thread safe.
65 **/
66 
67 class node_set
68 {
69 public:
70 
71  /**
72  * Create a new empty xml::node_set object.
73  **/
74  node_set ();
75 
76  /**
77  * Create a new xml::node_set object using another one as a template.
78  * The new object refers to the same set of nodes as the templete one.
79  *
80  * @param other
81  * Another xml::node_set object.
82  **/
83  node_set (const node_set& other);
84 
85  /**
86  * Destroy the object and clean up the memory.
87  **/
88  virtual ~node_set ();
89 
90  /**
91  * Creates a copy of the xml::node_set object.
92  * A copy refers to the same set of nodes as the given object.
93  *
94  * @param other
95  * Another xml::node_set object.
96  **/
97  node_set& operator= (const node_set& other);
98 
99  /**
100  * Moving constructor.
101  * @param other The other node_set.
102  **/
103  node_set(node_set &&other);
104 
105  /**
106  * Moving assignment.
107  * @param other The other node_set.
108  **/
109  node_set & operator=(node_set &&other);
110 
111 
112  // forward declaration
113  class const_iterator;
114 
115  /**
116  * The xml::node_set::iterator class is used to iterate over nodes in a
117  * node set. The iterator is one directional.
118  **/
119  class iterator
120  {
121  public:
122  typedef node value_type;
123  typedef std::ptrdiff_t difference_type;
124  typedef value_type* pointer;
126  typedef std::forward_iterator_tag iterator_category;
127 
128  /**
129  * Create a new uninitialised xml::node_set::iterator object.
130  **/
132 
133  /**
134  * Create a new xml::node_set::iterator object using another one as a
135  * template.
136  **/
137  iterator (const iterator& other);
138 
139  /**
140  * Create a copy of the xml::node_set::iterator object.
141  *
142  * @param other
143  * Another xml::node_set::iterator object
144  **/
145  iterator& operator= (const iterator& other);
146 
147  /**
148  * Destroy the object.
149  **/
150  ~iterator () {}
151 
152  /**
153  * Provide a reference to the node.
154  *
155  * @exception
156  * throws exception if the iterator is invalid
157  **/
158  reference operator* () const;
159 
160  /**
161  * Provide a pointer to the node.
162  *
163  * @exception
164  * throws exception if the iterator is invalid
165  **/
166  pointer operator-> () const;
167 
168  /**
169  * Prefix increment.
170  *
171  * @exception
172  * Throws exception if the iterator is not initialised or out of range
173  **/
175 
176  /**
177  * Postfix increment.
178  *
179  * @exception
180  * Throws exception if the iterator is not initialised or out of range
181  **/
182  iterator operator++ (int);
183 
184  /**
185  * Compare two iterators.
186  *
187  * @param other
188  * Another iterator
189  * @return
190  * True if the iterators are equal
191  **/
192  bool operator== (const iterator& other) const
193  { return ((parent_ == other.parent_) &&
194  (current_index_ == other.current_index_)); }
195 
196  /**
197  * Compare two iterators.
198  *
199  * @param other
200  * Another iterator
201  * @return
202  * True if the iterators are not equal
203  **/
204  bool operator!= (const iterator& other) const
205  { return !(*this == other); }
206 
207  private:
208  // Used by node_set to create iterators
209  iterator(node_set* parent, int index) :
210  parent_(parent), current_index_(index) {}
211 
212  void swap (iterator& other);
213 
214  node_set * parent_; // Node set to iterate over
215  int current_index_; // Index of the node in the set
216 
217  friend class node_set;
218  friend class const_iterator;
219  };
220 
221  /**
222  * The xml::node_set::const_iterator class is used to iterate over nodes in a
223  * node set. The iterator is one directional.
224  **/
226  {
227  public:
228  typedef const node value_type;
229  typedef std::ptrdiff_t difference_type;
230  typedef value_type* pointer;
232  typedef std::forward_iterator_tag iterator_category;
233 
234  /**
235  * Create a new uninitialised xml::node_set::const_iterator object.
236  **/
238 
239  /**
240  * Create a new xml::node_set::const_iterator object using another
241  * one as a template.
242  **/
243  const_iterator (const const_iterator& other);
244 
245  /**
246  * Create a new xml::node_set::const_iterator object using another
247  * one as a template.
248  **/
249  const_iterator (const iterator& other);
250 
251  /**
252  * Create a copy of the xml::node_set::const_iterator object.
253  *
254  * @param other
255  * Another xml::node_set::const_iterator object
256  **/
258 
259  /**
260  * Create a copy of the xml::node_set::const_iterator object.
261  *
262  * @param other
263  * Another const xml::node_set::iterator object
264  **/
265  const_iterator& operator= (const iterator& other);
266 
267  /**
268  * Destroy the object.
269  **/
271 
272  /**
273  * Provide a const reference to the node.
274  *
275  * @exception
276  * throws exception if the iterator is invalid
277  **/
278  reference operator* () const;
279 
280  /**
281  * Provide a const pointer to the node.
282  *
283  * @exception
284  * throws exception if the iterator is invalid
285  **/
286  pointer operator-> () const;
287 
288  /**
289  * Prefix increment.
290  *
291  * @exception
292  * Throws exception if the iterator is not initialised or out of range
293  **/
295 
296  /**
297  * Postfix increment.
298  *
299  * @exception
300  * Throws exception if the iterator is not initialised or out of range
301  **/
303 
304  /**
305  * Compare two iterators.
306  *
307  * @param other
308  * Another iterator
309  * @return
310  * True if the iterators are equal
311  **/
312  bool operator== (const const_iterator& other) const
313  { return ((parent_ == other.parent_) &&
314  (current_index_ == other.current_index_)); }
315 
316  /**
317  * Compare two iterators.
318  *
319  * @param other
320  * Another iterator
321  * @return
322  * True if the iterators are not equal
323  **/
324  bool operator!= (const const_iterator& other) const
325  { return !(*this == other); }
326 
327  private:
328  // Used by node_set to create iterators
329  const_iterator(const node_set* parent, int index) :
330  parent_(parent), current_index_(index) {}
331 
332  void swap (const_iterator& other);
333 
334  const node_set * parent_; // Node set to iterate over
335  int current_index_; // Index of the node in the set
336 
337  friend class node_set;
338  };
339 
340  /**
341  * Get an iterator that points to the beginning of the xpath query result
342  * node set.
343  *
344  * @return
345  * An iterator that points to the beginning of the xpath query result set
346  **/
347  iterator begin ();
348 
349  /**
350  * Get a const_iterator that points to the beginning of the xpath query
351  * result node set.
352  *
353  * @return
354  * A const_iterator that points to the beginning of the xpath query result set
355  **/
356  const_iterator begin () const;
357 
358  /**
359  * Get an iterator that points one past the last node in the xpath query
360  * result node set.
361  *
362  * @return
363  * An iterator that points one past the last node in the xpath query
364  * result node set.
365  **/
366  iterator end ();
367 
368  /**
369  * Get a const_iterator that points one past the last node in the xpath
370  * query result node set.
371  *
372  * @return
373  * A const_iterator that points one past the last node in the xpath query
374  * result node set.
375  **/
376  const_iterator end () const;
377 
378  /**
379  * Inform if the xpath query result node set is empty.
380  *
381  * @return
382  * true if the xpath query result node set is empty
383  **/
384  bool empty () const;
385 
386  /**
387  * Get the number of nodes in the xpath query result node set.
388  *
389  * @return
390  * The number of nodes in the xpath query result node set
391  **/
392  size_t size() const;
393 
394 private:
395  // relay to create a fake node basing on the libxml2 raw pointer
396  node_set(void* result_set);
397 
398  impl::nset_impl* pimpl_; // private implementation
399 
400  friend class node;
401  friend class iterator;
402  friend class const_iterator;
403  friend struct impl::nset_impl;
404  friend class xslt::xpath_object;
405 };
406 
407 
408 } // xml namespace
409 
410 #endif
411 
The xml::node_set::const_iterator class is used to iterate over nodes in a node set.
Definition: node_set.hpp:226
bool operator!=(const const_iterator &other) const
Compare two iterators.
Definition: node_set.hpp:324
bool operator==(const const_iterator &other) const
Compare two iterators.
Definition: node_set.hpp:312
std::ptrdiff_t difference_type
Definition: node_set.hpp:229
const_iterator(const node_set *parent, int index)
Definition: node_set.hpp:329
std::forward_iterator_tag iterator_category
Definition: node_set.hpp:232
const_iterator & operator++()
Prefix increment.
Definition: node_set.cpp:292
const_iterator()
Create a new uninitialised xml::node_set::const_iterator object.
Definition: node_set.hpp:237
reference operator*() const
Provide a const reference to the node.
Definition: node_set.cpp:278
pointer operator->() const
Provide a const pointer to the node.
Definition: node_set.cpp:285
void swap(const_iterator &other)
Definition: node_set.cpp:308
~const_iterator()
Destroy the object.
Definition: node_set.hpp:270
const node_set * parent_
Definition: node_set.hpp:334
const_iterator & operator=(const const_iterator &other)
Create a copy of the xml::node_set::const_iterator object.
Definition: node_set.cpp:264
The xml::node_set::iterator class is used to iterate over nodes in a node set.
Definition: node_set.hpp:120
bool operator!=(const iterator &other) const
Compare two iterators.
Definition: node_set.hpp:204
iterator & operator=(const iterator &other)
Create a copy of the xml::node_set::iterator object.
Definition: node_set.cpp:205
value_type * pointer
Definition: node_set.hpp:124
iterator & operator++()
Prefix increment.
Definition: node_set.cpp:226
reference operator*() const
Provide a reference to the node.
Definition: node_set.cpp:212
void swap(iterator &other)
Definition: node_set.cpp:242
iterator()
Create a new uninitialised xml::node_set::iterator object.
Definition: node_set.hpp:131
value_type & reference
Definition: node_set.hpp:125
bool operator==(const iterator &other) const
Compare two iterators.
Definition: node_set.hpp:192
pointer operator->() const
Provide a pointer to the node.
Definition: node_set.cpp:219
iterator(node_set *parent, int index)
Definition: node_set.hpp:209
std::ptrdiff_t difference_type
Definition: node_set.hpp:123
std::forward_iterator_tag iterator_category
Definition: node_set.hpp:126
~iterator()
Destroy the object.
Definition: node_set.hpp:150
The xml::node_set class is used to store xpath query result set.
Definition: node_set.hpp:68
iterator begin()
Get an iterator that points to the beginning of the xpath query result node set.
Definition: node_set.cpp:173
bool empty() const
Inform if the xpath query result node set is empty.
Definition: node_set.cpp:160
size_t size() const
Get the number of nodes in the xpath query result node set.
Definition: node_set.cpp:167
virtual ~node_set()
Destroy the object and clean up the memory.
Definition: node_set.cpp:126
impl::nset_impl * pimpl_
Definition: node_set.hpp:398
node_set & operator=(const node_set &other)
Creates a copy of the xml::node_set object.
Definition: node_set.cpp:132
iterator end()
Get an iterator that points one past the last node in the xpath query result node set.
Definition: node_set.cpp:185
node_set()
Create a new empty xml::node_set object.
Definition: node_set.cpp:106
The xml::node class is used to hold information about one XML node.
Definition: node.hpp:106
The xslt::xpath_object class is used to store extension function arguments and return values.
#define NULL
Definition: ncbistd.hpp:225
This file contains the definition of the xml::node class.
XML library namespace.
Definition: attributes.hpp:57
XML library namespace.
XPath expression storage for XmlWrapp.
Modified on Sun Jul 21 04:14:31 2024 by modify_doxy.py rev. 669887