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

Go to the SVN repository for this file.

1 /*
2  * Copyright (C) 2001-2003 Peter J Jones (pjones@pmade.org)
3  * All Rights Reserved
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * 1. Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * 2. Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in
13  * the documentation and/or other materials provided with the
14  * distribution.
15  * 3. Neither the name of the Author nor the names of its contributors
16  * may be used to endorse or promote products derived from this software
17  * without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
20  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
22  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
23  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
26  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30  * SUCH DAMAGE.
31  */
32 
33 /*
34  * $Id: attributes.hpp 79080 2017-08-09 18:22:55Z satskyse $
35  * NOTE: This file was modified from its original version 0.6.0
36  * to fit the NCBI C++ Toolkit build framework and
37  * API and functionality requirements.
38  * Most importantly, it adds support for XML namespaces (see "namespace.hpp").
39  */
40 
41 /** @file
42  * This file contains the definition of the xml::attributes class.
43 **/
44 
45 #ifndef _xmlwrapp_attributes_h_
46 #define _xmlwrapp_attributes_h_
47 
48 // xmlwrapp includes
51 
52 // standard includes
53 #include <cstddef>
54 #include <iosfwd>
55 #include <string>
56 
57 namespace xml {
58 
59 // forward declarations
60 class node;
61 
62 namespace impl {
63 class ait_impl;
64 struct node_impl;
65 struct attr_instance;
66 bool operator== (const ait_impl &lhs, const ait_impl &rhs);
67 void * get_ptr_to_attr_instance(void *);
68 }
69 
70 /**
71  * The xml::attributes class is used to access all the attributes of one
72  * xml::node. You can add, find and erase attributes by name, and for some
73  * member functions, use the provided iterator classes.
74  *
75  * The iterator classes allow you to access one XML attribute. This is done
76  * using the xml::attributes::attr class interface.
77 **/
78 class attributes {
79 public:
80  typedef std::size_t size_type; ///< size type
81 
82  //####################################################################
83  /**
84  * Create a new xml::attributes object with no attributes.
85  *
86  * @author Peter Jones
87  **/
88  //####################################################################
89  attributes (void);
90 
91  //####################################################################
92  /**
93  * Copy construct a xml::attributes object.
94  *
95  * @param other The xml::attributes object to copy from.
96  * @author Peter Jones
97  **/
98  //####################################################################
99  attributes (const attributes &other);
100 
101  //####################################################################
102  /**
103  * Copy the given xml::attributes object into this one.
104  *
105  * @param other The xml::attributes object to copy from.
106  * @return *this.
107  * @author Peter Jones
108  **/
109  //####################################################################
110  attributes& operator= (const attributes &other);
111 
112  /**
113  * Moving constructor.
114  * @param other The other attributes.
115  **/
116  attributes (attributes &&other);
117 
118  /**
119  * Moving assignment.
120  * @param other The other attributes.
121  **/
122  attributes& operator= (attributes &&other);
123 
124  //####################################################################
125  /**
126  * Swap this xml::attributes object with another one.
127  *
128  * @param other The other xml::attributes object to swap with.
129  * @author Peter Jones
130  **/
131  //####################################################################
132  void swap (attributes &other);
133 
134  //####################################################################
135  /**
136  * Clean up after a xml::attributes object.
137  *
138  * @author Peter Jones
139  **/
140  //####################################################################
141  virtual ~attributes (void);
142 
143  // forward declarations
144  class const_iterator;
145  class iterator;
146 
147  /**
148  * The xml::attributes::attr class is used to hold information about one
149  * attribute.
150  */
151  class attr {
152  public:
153  //####################################################################
154  /**
155  * Test if the attribute is default.
156  *
157  * @return true if the attribute is default
158  * @author Sergey Satskiy, NCBI
159  **/
160  //####################################################################
161  bool is_default (void) const;
162 
163  //####################################################################
164  /**
165  * Get the name of this attribute.
166  *
167  * @return The name for this attribute.
168  * @author Peter Jones
169  **/
170  //####################################################################
171  const char* get_name (void) const;
172 
173  //####################################################################
174  /**
175  * Get the value of this attribute.
176  *
177  * @return The value for this attribute.
178  * @author Peter Jones
179  **/
180  //####################################################################
181  const char* get_value (void) const;
182 
183  //####################################################################
184  /**
185  * Set the value of this attribute.
186  *
187  * @param value The value for this attribute.
188  * @note If the value is set for the default attribute then it
189  * will be implicilty converted to a regular one and then the
190  * value will be changed.
191  * @author Sergey Satskiy, NCBI
192  **/
193  //####################################################################
194  void set_value (const char* value);
195 
196  //####################################################################
197  /**
198  * Get the attribute's namespace.
199  *
200  * @param type The required type of namespace object (safe/unsafe).
201  * @return
202  * The attribute's namespace ("void" namespace if the attribute has
203  * no namespace set).
204  * @author Sergey Satskiy, NCBI
205  **/
206  //####################################################################
208 
209  //####################################################################
210  /**
211  * Unset the attribute's namespace.
212  *
213  * @author Sergey Satskiy, NCBI
214  **/
215  //####################################################################
216  void erase_namespace (void);
217 
218  //####################################################################
219  /**
220  * Set the attribute's namespace.
221  *
222  * The namespace definition is searched up in the hierarchy of nodes.
223  * If a namespace with the given prefix is not found then throw an
224  * exception.
225  *
226  * @param prefix
227  * Namespace prefix.
228  * You can use empty string or NULL to remove the namespace -- it
229  * works exactly the same as erase_namespace() call.
230  * @return Unsafe namespace
231  * @author Sergey Satskiy, NCBI
232  **/
233  //####################################################################
234  ns set_namespace (const char* prefix);
235 
236  //####################################################################
237  /**
238  * Set the attribute's namespace.
239  *
240  * The namespace definition is searched up in the hierarchy of nodes.
241  * If a namespace with the given prefix and URI is not found
242  * then throw an exception.
243  *
244  * @param name_space
245  * Namespace object.
246  * You can use "void" or default namespace to remove the namespace --
247  * it works exactly the same as erase_namespace() call.
248  * @note There are no checks at all if an unsafe ns object is provided.
249  * @return unsafe namespace
250  * @author Sergey Satskiy, NCBI
251  **/
252  //####################################################################
253  ns set_namespace (const ns& name_space);
254 
255  private:
256  void *xmlnode_;
257  void *prop_;
260 
261  attr (void);
262  attr (const attr &other);
263  attr& operator= (const attr &other);
264  void swap (attr &other);
265 
266  void set_data (void *node, void *prop, bool def_prop);
267  void *normalize (void) const;
268  void *get_node (void) const;
269  bool operator==(const attr &other) const;
270  void convert (void);
271  void *resolve_default_attr_ns (void) const;
272 
273  friend bool impl::operator== (const impl::ait_impl &lhs, const impl::ait_impl &rhs);
274  friend class impl::ait_impl;
275  friend class iterator;
276  friend class const_iterator;
277  friend class attributes;
279  friend void * xml::impl::get_ptr_to_attr_instance(void *);
280  }; // end xml::attributes::attr class
281 
282  /**
283  * Iterator class for accessing attribute pairs.
284  */
285  class iterator {
286  public:
287  typedef attr value_type;
288  typedef std::ptrdiff_t difference_type;
289  typedef value_type* pointer;
291  typedef std::forward_iterator_tag iterator_category;
292 
293  iterator (void);
294  iterator (const iterator &other);
295  iterator& operator= (const iterator& other);
296  ~iterator (void);
297 
298  reference operator* (void) const;
299  pointer operator-> (void) const;
300 
301  /// prefix increment
302  iterator& operator++ (void);
303 
304  /// postfix increment (avoid if possible for better performance)
305  iterator operator++ (int);
306 
307  friend bool operator== (const iterator &lhs, const iterator &rhs);
308  friend bool operator!= (const iterator &lhs, const iterator &rhs);
309  private:
311  iterator (void *node, void *prop, bool def_prop, bool from_find);
312  void swap (iterator &other);
313  friend class attributes;
314  friend class const_iterator;
315  }; // end xml::attributes::iterator class
316 
317  /**
318  * Const Iterator class for accessing attribute pairs.
319  */
321  public:
322  typedef const attr value_type;
323  typedef std::ptrdiff_t difference_type;
324  typedef value_type* pointer;
326  typedef std::forward_iterator_tag iterator_category;
327 
328  const_iterator (void);
329  const_iterator (const const_iterator &other);
330  const_iterator (const iterator &other);
332  ~const_iterator (void);
333 
334  reference operator* (void) const;
335  pointer operator-> (void) const;
336 
337  /// prefix increment
339 
340  /// postfix increment (avoid if possible better for performance)
342 
343  friend bool operator== (const const_iterator &lhs, const const_iterator &rhs);
344  friend bool operator!= (const const_iterator &lhs, const const_iterator &rhs);
345  private:
347  const_iterator (void *node, void *prop, bool def_prop, bool from_find);
348  void swap (const_iterator &other);
349  friend class attributes;
350  }; // end xml::attributes::const_iterator class
351 
352  //####################################################################
353  /**
354  * Get an iterator that points to the first attribute.
355  *
356  * @return An iterator that points to the first attribute.
357  * @return An iterator equal to end() if there are no attributes.
358  * @see xml::attributes::iterator
359  * @see xml::attributes::attr
360  * @author Peter Jones
361  **/
362  //####################################################################
363  iterator begin (void);
364 
365  //####################################################################
366  /**
367  * Get a const_iterator that points to the first attribute.
368  *
369  * @return A const_iterator that points to the first attribute.
370  * @return A const_iterator equal to end() if there are no attributes.
371  * @see xml::attributes::const_iterator
372  * @see xml::attributes::attr
373  * @author Peter Jones
374  **/
375  //####################################################################
376  const_iterator begin (void) const;
377 
378  //####################################################################
379  /**
380  * Get an iterator that points one past the the last attribute.
381  *
382  * @return An "end" iterator.
383  * @author Peter Jones
384  **/
385  //####################################################################
386  iterator end (void);
387 
388  //####################################################################
389  /**
390  * Get a const_iterator that points one past the last attribute.
391  *
392  * @return An "end" const_iterator.
393  * @author Peter Jones
394  **/
395  //####################################################################
396  const_iterator end (void) const;
397 
398  //####################################################################
399  /**
400  * Add an attribute to the attributes list. If there is another
401  * attribute with the same name, it will be replaced with this one.
402  *
403  * @param name The name of the attribute to add. The name could be
404  * qualified. If it is qualified then the namespace parameter must be
405  * NULL.
406  * @param value The value of the attribute to add.
407  * @param nspace
408  * The namespace of the atrribute to insert:
409  * - NULL or void namespace insert an attribute without a namespace.
410  * - default namespace causes an exception because attributes may not
411  * have default namespace.
412  * - Unsafe namespace is used as it is.
413  * - A safe namespace is resolved basing on the uri only
414  * @exception Throws exceptions in case of problems.
415  * @author Peter Jones, Sergey Satskiy
416  **/
417  //####################################################################
418  void insert (const char *name, const char *value, const ns *nspace=NULL);
419 
420  //####################################################################
421  /**
422  * Find the attribute with the given name and namespace. If the
423  * attribute is not found on the current node, the DTD will be searched
424  * for a default value. This is, of course, if there was a DTD parsed
425  * with the XML document. If the search comes to DTD and the namespace is
426  * provided then the only namespace prefix is taken into account.
427  *
428  * @param name
429  * The name of the attribute to find. The name could be given as a
430  * qualified name, e.g. 'prefix:attr_name'. If the name is qualified then
431  * the nspace argument must be NULL (otherwise an exception is
432  * generated) and the attribute search is namespace aware with an
433  * effective namespace identified by the given prefix.
434  * @param nspace
435  * The namespace of the atrribute to find:
436  * - NULL matches any namespace
437  * - Void namespace matches attributes without a namespace set
438  * - Unsafe namespace is used as it is
439  * - A safe namespace is resolved basing on the uri only
440  * @return An iterator that points to the attribute with the given name.
441  * @return If the attribute was not found, find will return end().
442  * @see xml::attributes::iterator
443  * @see xml::attributes::attr
444  * @author Peter Jones; Sergey Satskiy, NCBI
445  **/
446  //####################################################################
447  iterator find (const char *name, const ns *nspace=NULL);
448 
449  //####################################################################
450  /**
451  * Find the attribute with the given name and namespace. If the
452  * attribute is not found on the current node, the DTD will be searched
453  * for a default value. This is, of course, if there was a DTD parsed
454  * with the XML document. If the search comes to DTD and the namespace is
455  * provided then the only namespace prefix is taken into account.
456  *
457  * @param name
458  * The name of the attribute to find. The name could be given as a
459  * qualified name, e.g. 'prefix:attr_name'. If the name is qualified then
460  * the nspace argument must be NULL (otherwise an exception is
461  * generated) and the attribute search is namespace aware with an
462  * effective namespace identified by the given prefix.
463  * @param nspace
464  * The namespace of the atrribute to find:
465  * - NULL matches any namespace
466  * - Void namespace matches attributes without a namespace set
467  * - Unsafe namespace is used as it is
468  * - A safe namespace is resolved basing on the uri only
469  * @return A const_iterator that points to the attribute with the given name.
470  * @return If the attribute was not found, find will return end().
471  * @see xml::attributes::const_iterator
472  * @see xml::attributes::attr
473  * @author Peter Jones; Sergey Satskiy, NCBI
474  **/
475  //####################################################################
476  const_iterator find (const char *name, const ns *nspace=NULL) const;
477 
478  //####################################################################
479  /**
480  * Erase the attribute that is pointed to by the given iterator. This
481  * will invalidate any iterators for this attribute, as well as any
482  * pointers or references to it.
483  *
484  * @param to_erase An iterator that points to the attribute to erased.
485  * @return An iterator that points to the attribute after the one to be erased.
486  * @see xml::attributes::iterator
487  * @see xml::attributes::attr
488  * @author Peter Jones
489  **/
490  //####################################################################
491  iterator erase (iterator to_erase);
492 
493  //####################################################################
494  /**
495  * Erase the attribute with the given name. This will invalidate any
496  * iterators that are pointing to that attribute, as well as any
497  * pointers or references to that attribute.
498  *
499  * This function does not throw any exceptions.
500  *
501  * @param name The name of the attribute to erase. The name may be
502  * qualified. If it is qualified then the namespace parameter must be
503  * NULL.
504  * @param nspace
505  * The namespace of the atrribute to erase:
506  * - NULL matches any namespace
507  * - Void namespace matches attributes without a namespace set
508  * - Unsafe namespace is used as it is
509  * - A safe namespace is resolved basing on the uri only
510  * @return The number of erased attributes.
511  * @author Peter Jones, Sergey Satskiy
512  **/
513  //####################################################################
514  size_type erase (const char *name, const ns *nspace=NULL);
515 
516  //####################################################################
517  /**
518  * Find out if there are any attributes in this xml::attributes object.
519  *
520  * @return True if there are no attributes.
521  * @return False if there is at least one attribute.
522  * @author Peter Jones
523  **/
524  //####################################################################
525  bool empty (void) const;
526 
527  //####################################################################
528  /**
529  * Find out how many attributes there are in this xml::attributes
530  * object.
531  *
532  * @return The number of attributes in this xml::attributes object.
533  * @author Peter Jones
534  **/
535  //####################################################################
536  size_type size (void) const;
537 
538  //####################################################################
539  /**
540  * Sorts the attributes in place
541  *
542  **/
543  //####################################################################
544  void sort (void);
545 
546 private:
547  struct pimpl; pimpl *pimpl_;
548 
549  // private ctor to create uninitialized instance
550  explicit attributes (int);
551 
552  // The attr class needs to create an unsafe namespace using a pointer.
553  // The corresponding xml::ns constructor is private and C++ forbids
554  // making nested classes friends. So this member function does nothing
555  // but creates an xml::ns object using the given pointer
556  static xml::ns createUnsafeNamespace (void * libxml2RawNamespace);
557 
558  // Similar to the above
559  static void * getUnsafeNamespacePointer (const xml::ns &name_space);
560 
561  void set_data (void *node);
562  void* get_data (void);
563  friend struct impl::node_impl;
564  friend class node;
565 }; // end xml::attributes class
566 
567 } // end xml namespace
568 #endif
569 
The xml::attributes::attr class is used to hold information about one attribute.
Definition: attributes.hpp:151
void erase_namespace(void)
Unset the attribute's namespace.
Definition: ait_impl.cpp:453
const char * get_value(void) const
Get the value of this attribute.
Definition: ait_impl.cpp:350
void * normalize(void) const
Definition: ait_impl.cpp:307
ns set_namespace(const char *prefix)
Set the attribute's namespace.
Definition: ait_impl.cpp:459
void swap(attr &other)
Definition: ait_impl.cpp:287
void * get_node(void) const
Definition: ait_impl.cpp:320
bool operator==(const attr &other) const
Definition: ait_impl.cpp:325
void set_data(void *node, void *prop, bool def_prop)
Definition: ait_impl.cpp:294
attr & operator=(const attr &other)
Definition: ait_impl.cpp:281
bool is_default(void) const
Test if the attribute is default.
Definition: ait_impl.cpp:329
void * resolve_default_attr_ns(void) const
Definition: ait_impl.cpp:405
ns get_namespace(ns::ns_safety_type type=ns::type_safe_ns) const
Get the attribute's namespace.
Definition: ait_impl.cpp:380
void set_value(const char *value)
Set the value of this attribute.
Definition: ait_impl.cpp:443
const char * get_name(void) const
Get the name of this attribute.
Definition: ait_impl.cpp:335
Const Iterator class for accessing attribute pairs.
Definition: attributes.hpp:320
const_iterator & operator=(const const_iterator &other)
Definition: ait_impl.cpp:222
pointer operator->(void) const
Definition: ait_impl.cpp:246
friend bool operator!=(const const_iterator &lhs, const const_iterator &rhs)
Definition: ait_impl.cpp:645
friend bool operator==(const const_iterator &lhs, const const_iterator &rhs)
Definition: ait_impl.cpp:640
std::forward_iterator_tag iterator_category
Definition: attributes.hpp:326
void swap(const_iterator &other)
Definition: ait_impl.cpp:228
reference operator*(void) const
Definition: ait_impl.cpp:237
const_iterator & operator++(void)
prefix increment
Definition: ait_impl.cpp:255
Iterator class for accessing attribute pairs.
Definition: attributes.hpp:285
pointer operator->(void) const
Definition: ait_impl.cpp:173
friend bool operator==(const iterator &lhs, const iterator &rhs)
Definition: ait_impl.cpp:630
std::forward_iterator_tag iterator_category
Definition: attributes.hpp:291
iterator & operator=(const iterator &other)
Definition: ait_impl.cpp:149
impl::ait_impl * pimpl_
Definition: attributes.hpp:310
void swap(iterator &other)
Definition: ait_impl.cpp:155
reference operator*(void) const
Definition: ait_impl.cpp:164
friend bool operator!=(const iterator &lhs, const iterator &rhs)
Definition: ait_impl.cpp:635
iterator & operator++(void)
prefix increment
Definition: ait_impl.cpp:181
std::ptrdiff_t difference_type
Definition: attributes.hpp:288
The xml::attributes class is used to access all the attributes of one xml::node.
Definition: attributes.hpp:78
std::size_t size_type
size type
Definition: attributes.hpp:80
size_type size(void) const
Find out how many attributes there are in this xml::attributes object.
Definition: attributes.cpp:417
iterator erase(iterator to_erase)
Erase the attribute that is pointed to by the given iterator.
Definition: attributes.cpp:314
void swap(attributes &other)
Swap this xml::attributes object with another one.
Definition: attributes.cpp:115
attributes(void)
Create a new xml::attributes object with no attributes.
Definition: attributes.cpp:97
iterator find(const char *name, const ns *nspace=NULL)
Find the attribute with the given name and namespace.
Definition: attributes.cpp:288
iterator begin(void)
Get an iterator that points to the first attribute.
Definition: attributes.cpp:160
static xml::ns createUnsafeNamespace(void *libxml2RawNamespace)
Definition: attributes.cpp:144
static void * getUnsafeNamespacePointer(const xml::ns &name_space)
Definition: attributes.cpp:148
void sort(void)
Sorts the attributes in place.
Definition: attributes.cpp:432
attributes & operator=(const attributes &other)
Copy the given xml::attributes object into this one.
Definition: attributes.cpp:109
iterator end(void)
Get an iterator that points one past the the last attribute.
Definition: attributes.cpp:174
void set_data(void *node)
Definition: attributes.cpp:152
bool empty(void) const
Find out if there are any attributes in this xml::attributes object.
Definition: attributes.cpp:413
virtual ~attributes(void)
Clean up after a xml::attributes object.
Definition: attributes.cpp:119
void insert(const char *name, const char *value, const ns *nspace=NULL)
Add an attribute to the attributes list.
Definition: attributes.cpp:188
void * get_data(void)
Definition: attributes.cpp:140
the class that does all the work behind xml::attributes::iterator and xml::attributes::const_iterator...
Definition: ait_impl.hpp:67
The xml::node class is used to hold information about one XML node.
Definition: node.hpp:106
The xml::ns class is used to access and handle namespaces of nodes and attributes.
Definition: namespace.hpp:64
ns_safety_type
Namespace object "safety".
Definition: namespace.hpp:67
@ type_safe_ns
Definition: namespace.hpp:68
string
Definition: cgiapp.hpp:687
#define NULL
Definition: ncbistd.hpp:225
XML namespace API for XmlWrapp.
const GenericPointer< typename T::ValueType > T2 value
Definition: pointer.h:1227
void * get_ptr_to_attr_instance(void *)
Definition: deref_impl.cpp:119
bool operator==(const ait_impl &lhs, const ait_impl &rhs)
Definition: ait_impl.cpp:651
XML library namespace.
Definition: attributes.hpp:57
static const char * prefix[]
Definition: pcregrep.c:405
Definition: type.c:6
This file contains the definition of the xml::init class.
Modified on Tue May 28 05:54:46 2024 by modify_doxy.py rev. 669887