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 69433 2015-10-22 16:10:24Z 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  /**
114  * Swap this xml::attributes object with another one.
115  *
116  * @param other The other xml::attributes object to swap with.
117  * @author Peter Jones
118  **/
119  //####################################################################
120  void swap (attributes &other);
121 
122  //####################################################################
123  /**
124  * Clean up after a xml::attributes object.
125  *
126  * @author Peter Jones
127  **/
128  //####################################################################
129  virtual ~attributes (void);
130 
131  // forward declarations
132  class const_iterator;
133  class iterator;
134 
135  /**
136  * The xml::attributes::attr class is used to hold information about one
137  * attribute.
138  */
139  class attr {
140  public:
141  //####################################################################
142  /**
143  * Test if the attribute is default.
144  *
145  * @return true if the attribute is default
146  * @author Sergey Satskiy, NCBI
147  **/
148  //####################################################################
149  bool is_default (void) const;
150 
151  //####################################################################
152  /**
153  * Get the name of this attribute.
154  *
155  * @return The name for this attribute.
156  * @author Peter Jones
157  **/
158  //####################################################################
159  const char* get_name (void) const;
160 
161  //####################################################################
162  /**
163  * Get the value of this attribute.
164  *
165  * @return The value for this attribute.
166  * @author Peter Jones
167  **/
168  //####################################################################
169  const char* get_value (void) const;
170 
171  //####################################################################
172  /**
173  * Set the value of this attribute.
174  *
175  * @param value The value for this attribute.
176  * @note If the value is set for the default attribute then it
177  * will be implicilty converted to a regular one and then the
178  * value will be changed.
179  * @author Sergey Satskiy, NCBI
180  **/
181  //####################################################################
182  void set_value (const char* value);
183 
184  //####################################################################
185  /**
186  * Get the attribute's namespace.
187  *
188  * @param type The required type of namespace object (safe/unsafe).
189  * @return
190  * The attribute's namespace ("void" namespace if the attribute has
191  * no namespace set).
192  * @author Sergey Satskiy, NCBI
193  **/
194  //####################################################################
196 
197  //####################################################################
198  /**
199  * Unset the attribute's namespace.
200  *
201  * @author Sergey Satskiy, NCBI
202  **/
203  //####################################################################
204  void erase_namespace (void);
205 
206  //####################################################################
207  /**
208  * Set the attribute's namespace.
209  *
210  * The namespace definition is searched up in the hierarchy of nodes.
211  * If a namespace with the given prefix is not found then throw an
212  * exception.
213  *
214  * @param prefix
215  * Namespace prefix.
216  * You can use empty string or NULL to remove the namespace -- it
217  * works exactly the same as erase_namespace() call.
218  * @return Unsafe namespace
219  * @author Sergey Satskiy, NCBI
220  **/
221  //####################################################################
222  ns set_namespace (const char* prefix);
223 
224  //####################################################################
225  /**
226  * Set the attribute's namespace.
227  *
228  * The namespace definition is searched up in the hierarchy of nodes.
229  * If a namespace with the given prefix and URI is not found
230  * then throw an exception.
231  *
232  * @param name_space
233  * Namespace object.
234  * You can use "void" or default namespace to remove the namespace --
235  * it works exactly the same as erase_namespace() call.
236  * @note There are no checks at all if an unsafe ns object is provided.
237  * @return unsafe namespace
238  * @author Sergey Satskiy, NCBI
239  **/
240  //####################################################################
241  ns set_namespace (const ns& name_space);
242 
243  private:
244  void *xmlnode_;
245  void *prop_;
248 
249  attr (void);
250  attr (const attr &other);
251  attr& operator= (const attr &other);
252  void swap (attr &other);
253 
254  void set_data (void *node, void *prop, bool def_prop);
255  void *normalize (void) const;
256  void *get_node (void) const;
257  bool operator==(const attr &other) const;
258  void convert (void);
259  void *resolve_default_attr_ns (void) const;
260 
261  friend bool impl::operator== (const impl::ait_impl &lhs, const impl::ait_impl &rhs);
262  friend class impl::ait_impl;
263  friend class iterator;
264  friend class const_iterator;
265  friend class attributes;
267  friend void * xml::impl::get_ptr_to_attr_instance(void *);
268  }; // end xml::attributes::attr class
269 
270  /**
271  * Iterator class for accessing attribute pairs.
272  */
273  class iterator {
274  public:
275  typedef attr value_type;
276  typedef std::ptrdiff_t difference_type;
277  typedef value_type* pointer;
278  typedef value_type& reference;
279  typedef std::forward_iterator_tag iterator_category;
280 
281  iterator (void);
282  iterator (const iterator &other);
283  iterator& operator= (const iterator& other);
284  ~iterator (void);
285 
286  reference operator* (void) const;
287  pointer operator-> (void) const;
288 
289  /// prefix increment
290  iterator& operator++ (void);
291 
292  /// postfix increment (avoid if possible for better performance)
293  iterator operator++ (int);
294 
295  friend bool operator== (const iterator &lhs, const iterator &rhs);
296  friend bool operator!= (const iterator &lhs, const iterator &rhs);
297  private:
299  iterator (void *node, void *prop, bool def_prop, bool from_find);
300  void swap (iterator &other);
301  friend class attributes;
302  friend class const_iterator;
303  }; // end xml::attributes::iterator class
304 
305  /**
306  * Const Iterator class for accessing attribute pairs.
307  */
309  public:
310  typedef const attr value_type;
311  typedef std::ptrdiff_t difference_type;
312  typedef value_type* pointer;
313  typedef value_type& reference;
314  typedef std::forward_iterator_tag iterator_category;
315 
316  const_iterator (void);
317  const_iterator (const const_iterator &other);
318  const_iterator (const iterator &other);
320  ~const_iterator (void);
321 
322  reference operator* (void) const;
323  pointer operator-> (void) const;
324 
325  /// prefix increment
327 
328  /// postfix increment (avoid if possible better for performance)
330 
331  friend bool operator== (const const_iterator &lhs, const const_iterator &rhs);
332  friend bool operator!= (const const_iterator &lhs, const const_iterator &rhs);
333  private:
335  const_iterator (void *node, void *prop, bool def_prop, bool from_find);
336  void swap (const_iterator &other);
337  friend class attributes;
338  }; // end xml::attributes::const_iterator class
339 
340  //####################################################################
341  /**
342  * Get an iterator that points to the first attribute.
343  *
344  * @return An iterator that points to the first attribute.
345  * @return An iterator equal to end() if there are no attributes.
346  * @see xml::attributes::iterator
347  * @see xml::attributes::attr
348  * @author Peter Jones
349  **/
350  //####################################################################
351  iterator begin (void);
352 
353  //####################################################################
354  /**
355  * Get a const_iterator that points to the first attribute.
356  *
357  * @return A const_iterator that points to the first attribute.
358  * @return A const_iterator equal to end() if there are no attributes.
359  * @see xml::attributes::const_iterator
360  * @see xml::attributes::attr
361  * @author Peter Jones
362  **/
363  //####################################################################
364  const_iterator begin (void) const;
365 
366  //####################################################################
367  /**
368  * Get an iterator that points one past the the last attribute.
369  *
370  * @return An "end" iterator.
371  * @author Peter Jones
372  **/
373  //####################################################################
374  iterator end (void);
375 
376  //####################################################################
377  /**
378  * Get a const_iterator that points one past the last attribute.
379  *
380  * @return An "end" const_iterator.
381  * @author Peter Jones
382  **/
383  //####################################################################
384  const_iterator end (void) const;
385 
386  //####################################################################
387  /**
388  * Add an attribute to the attributes list. If there is another
389  * attribute with the same name, it will be replaced with this one.
390  *
391  * @param name The name of the attribute to add. The name could be
392  * qualified. If it is qualified then the namespace parameter must be
393  * NULL.
394  * @param value The value of the attribute to add.
395  * @param nspace
396  * The namespace of the atrribute to insert:
397  * - NULL or void namespace insert an attribute without a namespace.
398  * - default namespace causes an exception because attributes may not
399  * have default namespace.
400  * - Unsafe namespace is used as it is.
401  * - A safe namespace is resolved basing on the uri only
402  * @exception Throws exceptions in case of problems.
403  * @author Peter Jones, Sergey Satskiy
404  **/
405  //####################################################################
406  void insert (const char *name, const char *value, const ns *nspace=NULL);
407 
408  //####################################################################
409  /**
410  * Find the attribute with the given name and namespace. If the
411  * attribute is not found on the current node, the DTD will be searched
412  * for a default value. This is, of course, if there was a DTD parsed
413  * with the XML document. If the search comes to DTD and the namespace is
414  * provided then the only namespace prefix is taken into account.
415  *
416  * @param name
417  * The name of the attribute to find. The name could be given as a
418  * qualified name, e.g. 'prefix:attr_name'. If the name is qualified then
419  * the nspace argument must be NULL (otherwise an exception is
420  * generated) and the attribute search is namespace aware with an
421  * effective namespace identified by the given prefix.
422  * @param nspace
423  * The namespace of the atrribute to find:
424  * - NULL matches any namespace
425  * - Void namespace matches attributes without a namespace set
426  * - Unsafe namespace is used as it is
427  * - A safe namespace is resolved basing on the uri only
428  * @return An iterator that points to the attribute with the given name.
429  * @return If the attribute was not found, find will return end().
430  * @see xml::attributes::iterator
431  * @see xml::attributes::attr
432  * @author Peter Jones; Sergey Satskiy, NCBI
433  **/
434  //####################################################################
435  iterator find (const char *name, const ns *nspace=NULL);
436 
437  //####################################################################
438  /**
439  * Find the attribute with the given name and namespace. If the
440  * attribute is not found on the current node, the DTD will be searched
441  * for a default value. This is, of course, if there was a DTD parsed
442  * with the XML document. If the search comes to DTD and the namespace is
443  * provided then the only namespace prefix is taken into account.
444  *
445  * @param name
446  * The name of the attribute to find. The name could be given as a
447  * qualified name, e.g. 'prefix:attr_name'. If the name is qualified then
448  * the nspace argument must be NULL (otherwise an exception is
449  * generated) and the attribute search is namespace aware with an
450  * effective namespace identified by the given prefix.
451  * @param nspace
452  * The namespace of the atrribute to find:
453  * - NULL matches any namespace
454  * - Void namespace matches attributes without a namespace set
455  * - Unsafe namespace is used as it is
456  * - A safe namespace is resolved basing on the uri only
457  * @return A const_iterator that points to the attribute with the given name.
458  * @return If the attribute was not found, find will return end().
459  * @see xml::attributes::const_iterator
460  * @see xml::attributes::attr
461  * @author Peter Jones; Sergey Satskiy, NCBI
462  **/
463  //####################################################################
464  const_iterator find (const char *name, const ns *nspace=NULL) const;
465 
466  //####################################################################
467  /**
468  * Erase the attribute that is pointed to by the given iterator. This
469  * will invalidate any iterators for this attribute, as well as any
470  * pointers or references to it.
471  *
472  * @param to_erase An iterator that points to the attribute to erased.
473  * @return An iterator that points to the attribute after the one to be erased.
474  * @see xml::attributes::iterator
475  * @see xml::attributes::attr
476  * @author Peter Jones
477  **/
478  //####################################################################
479  iterator erase (iterator to_erase);
480 
481  //####################################################################
482  /**
483  * Erase the attribute with the given name. This will invalidate any
484  * iterators that are pointing to that attribute, as well as any
485  * pointers or references to that attribute.
486  *
487  * This function does not throw any exceptions.
488  *
489  * @param name The name of the attribute to erase. The name may be
490  * qualified. If it is qualified then the namespace parameter must be
491  * NULL.
492  * @param nspace
493  * The namespace of the atrribute to erase:
494  * - NULL matches any namespace
495  * - Void namespace matches attributes without a namespace set
496  * - Unsafe namespace is used as it is
497  * - A safe namespace is resolved basing on the uri only
498  * @return The number of erased attributes.
499  * @author Peter Jones, Sergey Satskiy
500  **/
501  //####################################################################
502  size_type erase (const char *name, const ns *nspace=NULL);
503 
504  //####################################################################
505  /**
506  * Find out if there are any attributes in this xml::attributes object.
507  *
508  * @return True if there are no attributes.
509  * @return False if there is at least one attribute.
510  * @author Peter Jones
511  **/
512  //####################################################################
513  bool empty (void) const;
514 
515  //####################################################################
516  /**
517  * Find out how many attributes there are in this xml::attributes
518  * object.
519  *
520  * @return The number of attributes in this xml::attributes object.
521  * @author Peter Jones
522  **/
523  //####################################################################
524  size_type size (void) const;
525 
526  //####################################################################
527  /**
528  * Sorts the attributes in place
529  *
530  **/
531  //####################################################################
532  void sort (void);
533 
534 private:
535  struct pimpl; pimpl *pimpl_;
536 
537  // private ctor to create uninitialized instance
538  explicit attributes (int);
539 
540  // The attr class needs to create an unsafe namespace using a pointer.
541  // The corresponding xml::ns constructor is private and C++ forbids
542  // making nested classes friends. So this member function does nothing
543  // but creates an xml::ns object using the given pointer
544  static xml::ns createUnsafeNamespace (void * libxml2RawNamespace);
545 
546  // Similar to the above
547  static void * getUnsafeNamespacePointer (const xml::ns &name_space);
548 
549  void set_data (void *node);
550  void* get_data (void);
551  friend struct impl::node_impl;
552  friend class node;
553 }; // end xml::attributes class
554 
555 } // end xml namespace
556 #endif
557 
const char * get_name(void) const
Get the name of this attribute.
Definition: ait_impl.cpp:334
virtual ~attributes(void)
Clean up after a xml::attributes object.
Definition: attributes.cpp:119
bool operator==(const attr &other) const
Definition: ait_impl.cpp:324
void * get_data(void)
Definition: attributes.cpp:123
iterator end(void)
Get an iterator that points one past the the last attribute.
Definition: attributes.cpp:157
iterator begin(void)
Get an iterator that points to the first attribute.
Definition: attributes.cpp:143
The xml::attributes::attr class is used to hold information about one attribute.
Definition: attributes.hpp:139
size_type size(void) const
Find out how many attributes there are in this xml::attributes object.
Definition: attributes.cpp:400
iterator & operator=(const iterator &other)
Definition: ait_impl.cpp:148
pointer operator->(void) const
Definition: ait_impl.cpp:245
void insert(const char *name, const char *value, const ns *nspace=NULL)
Add an attribute to the attributes list.
Definition: attributes.cpp:171
the class that does all the work behind xml::attributes::iterator and xml::attributes::const_iterator...
Definition: ait_impl.hpp:66
const_iterator & operator=(const const_iterator &other)
Definition: ait_impl.cpp:221
impl::ait_impl * pimpl_
Definition: attributes.hpp:298
Iterator class for accessing attribute pairs.
Definition: attributes.hpp:273
string
Definition: cgiapp.hpp:498
friend bool operator!=(const iterator &lhs, const iterator &rhs)
Definition: ait_impl.cpp:634
const_iterator & operator++(void)
prefix increment
Definition: ait_impl.cpp:254
#define NULL
Definition: ncbistd.hpp:225
void * normalize(void) const
Definition: ait_impl.cpp:306
attributes(void)
Create a new xml::attributes object with no attributes.
Definition: attributes.cpp:97
ns set_namespace(const char *prefix)
Set the attribute's namespace.
Definition: ait_impl.cpp:458
void swap(attr &other)
Definition: ait_impl.cpp:286
friend bool operator==(const const_iterator &lhs, const const_iterator &rhs)
Definition: ait_impl.cpp:639
void set_value(const char *value)
Set the value of this attribute.
Definition: ait_impl.cpp:442
const char * get_value(void) const
Get the value of this attribute.
Definition: ait_impl.cpp:349
ns get_namespace(ns::ns_safety_type type=ns::type_safe_ns) const
Get the attribute's namespace.
Definition: ait_impl.cpp:379
XML library namespace.
Definition: attributes.hpp:57
bool empty(void) const
Find out if there are any attributes in this xml::attributes object.
Definition: attributes.cpp:396
void erase_namespace(void)
Unset the attribute's namespace.
Definition: ait_impl.cpp:452
iterator find(const char *name, const ns *nspace=NULL)
Find the attribute with the given name and namespace.
Definition: attributes.cpp:271
std::size_t size_type
size type
Definition: attributes.hpp:80
Definition: type.c:8
void set_data(void *node, void *prop, bool def_prop)
Definition: ait_impl.cpp:293
void * get_ptr_to_attr_instance(void *)
Definition: deref_impl.cpp:114
void swap(const_iterator &other)
Definition: ait_impl.cpp:227
friend bool operator!=(const const_iterator &lhs, const const_iterator &rhs)
Definition: ait_impl.cpp:644
The xml::ns class is used to access and handle namespaces of nodes and attributes.
Definition: namespace.hpp:64
The xml::node class is used to hold information about one XML node.
Definition: node.hpp:106
reference operator*(void) const
Definition: ait_impl.cpp:163
Const Iterator class for accessing attribute pairs.
Definition: attributes.hpp:308
std::forward_iterator_tag iterator_category
Definition: attributes.hpp:279
void * resolve_default_attr_ns(void) const
Definition: ait_impl.cpp:404
The xml::attributes class is used to access all the attributes of one xml::node.
Definition: attributes.hpp:78
char value[7]
Definition: config.c:428
bool is_default(void) const
Test if the attribute is default.
Definition: ait_impl.cpp:328
pointer operator->(void) const
Definition: ait_impl.cpp:172
void * get_node(void) const
Definition: ait_impl.cpp:319
ns_safety_type
Namespace object "safety".
Definition: namespace.hpp:68
iterator & operator++(void)
prefix increment
Definition: ait_impl.cpp:180
attributes & operator=(const attributes &other)
Copy the given xml::attributes object into this one.
Definition: attributes.cpp:109
attr & operator=(const attr &other)
Definition: ait_impl.cpp:280
void set_data(void *node)
Definition: attributes.cpp:135
std::ptrdiff_t difference_type
Definition: attributes.hpp:276
bool operator==(const ait_impl &lhs, const ait_impl &rhs)
Definition: ait_impl.cpp:650
This file contains the definition of the xml::init class.
std::forward_iterator_tag iterator_category
Definition: attributes.hpp:314
static const char * prefix[]
Definition: pcregrep.c:251
void sort(void)
Sorts the attributes in place.
Definition: attributes.cpp:415
void swap(attributes &other)
Swap this xml::attributes object with another one.
Definition: attributes.cpp:115
iterator erase(iterator to_erase)
Erase the attribute that is pointed to by the given iterator.
Definition: attributes.cpp:297
static xml::ns createUnsafeNamespace(void *libxml2RawNamespace)
Definition: attributes.cpp:127
XML namespace API for XmlWrapp.
static void * getUnsafeNamespacePointer(const xml::ns &name_space)
Definition: attributes.cpp:131
reference operator*(void) const
Definition: ait_impl.cpp:236
void swap(iterator &other)
Definition: ait_impl.cpp:154
friend bool operator==(const iterator &lhs, const iterator &rhs)
Definition: ait_impl.cpp:629
Modified on Sat May 27 15:27:52 2017 by modify_doxy.py rev. 533848