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

Go to the SVN repository for this file.

1 /* $Id: namespace.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  * Credits: Denis Vakatov, NCBI (help with the original design)
27  *
28  */
29 
30 
31 /** @file
32  * XML namespace API for XmlWrapp.
33 **/
34 
35 #ifndef _xmlwrapp_ns_hpp_
36 #define _xmlwrapp_ns_hpp_
37 
38 // standard includes
39 #include <string>
40 #include <vector>
41 
42 namespace xml {
43 
44 namespace impl {
45  struct ns_util;
46 }
47 
48 
49 /**
50  * The xml::ns class is used to access and handle namespaces of nodes and
51  * attributes.
52  *
53  * There are two kinds of the object: safe and unsafe. The safe version holds
54  * copies of the namespace prefix and URI, and it is not linked to the libxml2
55  * data structures. The unsafe version holds a raw pointer to the libxml2 data
56  * structures. The unsafe version is faster but it must be used very carefully.
57  * Misuse of the unsafe version will lead to an unpredictable behavior. Example
58  * of improper usage of unsafe namespace: get an unsafe namespace from one
59  * document and use the object to set a namespace of a node in another
60  * document (the unsafe namespaces "belong" to a particular document).
61 **/
62 
63 class ns
64 {
65 public:
66  /// Namespace object "safety"
68  type_safe_ns, //< "safe" object - holds prefix and URI copies
69  type_unsafe_ns //< "unsafe" object - holds raw libxml2 pointer
70  };
71 
72  /**
73  * Create a new xml::ns object with the given prefix and URI.
74  * The created object is safe.
75  *
76  * @param prefix
77  * The namespace prefix. Use NULL or empty string for default namespace.
78  * @param uri
79  * The namespace URI.
80  **/
81  ns (const char* prefix, const char* uri);
82 
83 
84  /**
85  * Moving constructor.
86  * @param other The other namespace.
87  **/
88  ns (ns && other);
89 
90 
91  /**
92  * Moving assignment.
93  * @param other The other namespace.
94  **/
95  ns & operator= (ns && other);
96 
97  /**
98  * Get the namespace prefix.
99  *
100  * @return The namespace prefix.
101  * @note
102  * The lifetime of the returned string is either the lifetime of the
103  * namespace object itself (if it's a "safe" object) or the lifetime
104  * of the underlying libxml2 document (if it's an "unsafe" object).
105  **/
106  const char* get_prefix (void) const;
107 
108 
109  /**
110  * Get the namespace URI.
111  *
112  * @return The namespace URI.
113  * @note
114  * The lifetime of the returned string is either the lifetime of the
115  * namespace object itself (if it's a "safe" object) or the lifetime
116  * of the underlying libxml2 document (if it's an "unsafe" object).
117  **/
118  const char* get_uri (void) const;
119 
120 
121  /**
122  * If a node or an attribute has no namespace, then a namespace
123  * with empty prefix and empty URI is returned to the user. The
124  * method checks if the namespace is actually set.
125  *
126  * @return TRUE if the namespace is void
127  **/
128  bool is_void (void) const;
129 
130 
131  /**
132  * Convert the namespace object to a safe one (i.e. the object will
133  * hold copies of prefix and URI and will not be unsafely linked to
134  * internal libxml2 structures).
135  * If the object is safe already the function does nothing.
136  **/
137  void make_safe (void);
138 
139 
140  /**
141  * Check if the object is safe i.e. holds its own copies of prefix and URI.
142  *
143  * @return TRUE if the object is safe
144  **/
145  bool is_safe (void) const;
146 
147 
148  /**
149  * Compare with another namespace.
150  *
151  * @return TRUE if the namespaces have the equal URIs.
152  * @note libxml2 compares namespaces basing on URIs so xmlwrapp does.
153  **/
154  bool operator==(const ns& other) const;
155 
156 
157  /**
158  * Compare with another namespace.
159  *
160  * @return TRUE if the namespaces URIs differ.
161  * @note libxml2 compares namespaces basing on URIs so xmlwrapp does.
162  **/
163  bool operator!=(const ns& other) const;
164 
165 
166  // Create a "void" xml::ns object -- with both prefix and URI empty.
167  // The created object is safe. This is a rather unusual operation which
168  // is used by the XmlWrapp internal code.
169  enum ns_type {
170  type_void
171  };
172  explicit ns (enum ns_type type);
173 
174  ns (const ns& other) = default;
175  ns & operator= (const ns& other) = default;
176 
177 private:
178  /**
179  * Use more explicit "ns(enum ns_type)" ctor to create "void" namespace
180  **/
181  ns (void);
182 
183  /**
184  * Create a new unsafe xml::ns object with the given pointer.
185  * The unsafe objects cannot be created by the user and can be created only
186  * by the libxmlwrapp.
187  * It is not checked that the pointer is valid.
188  *
189  * @param rawLibXML2Namespace The libxml2 xmlNs structure pointer.
190  **/
191  ns (void* rawLibXML2Namespace);
192 
193 private:
194  std::string prefix_; // namespace prefix
195  std::string uri_; // namespace URI
196  void * unsafe_ns_; // pointer to the libxml2 structure
197  enum ns_safety_type safety_; // object type: safe/unsafe
198 
199  friend class node;
200  friend class attributes;
201  friend struct impl::ns_util;
202 };
203 
204 
205 /**
206  * type for holding XML namespaces
207 **/
208 typedef std::vector<xml::ns> ns_list_type;
209 
210 
211 } // xml namespace
212 
213 #endif
214 
The xml::attributes class is used to access all the attributes of one xml::node.
Definition: attributes.hpp:78
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
void * unsafe_ns_
Definition: namespace.hpp:196
void make_safe(void)
Convert the namespace object to a safe one (i.e.
Definition: namespace.cpp:135
ns_safety_type
Namespace object "safety".
Definition: namespace.hpp:67
@ type_safe_ns
Definition: namespace.hpp:68
@ type_unsafe_ns
Definition: namespace.hpp:69
std::string prefix_
Definition: namespace.hpp:194
ns(void)
Use more explicit "ns(enum ns_type)" ctor to create "void" namespace.
const char * get_prefix(void) const
Get the namespace prefix.
Definition: namespace.cpp:95
ns & operator=(ns &&other)
Moving assignment.
Definition: namespace.cpp:83
std::string uri_
Definition: namespace.hpp:195
const char * get_uri(void) const
Get the namespace URI.
Definition: namespace.cpp:109
bool is_safe(void) const
Check if the object is safe i.e.
Definition: namespace.cpp:154
bool operator==(const ns &other) const
Compare with another namespace.
Definition: namespace.cpp:160
enum ns_safety_type safety_
Definition: namespace.hpp:197
bool operator!=(const ns &other) const
Compare with another namespace.
Definition: namespace.cpp:166
bool is_void(void) const
If a node or an attribute has no namespace, then a namespace with empty prefix and empty URI is retur...
Definition: namespace.cpp:123
ns(const ns &other)=default
string
Definition: cgiapp.hpp:687
XML library namespace.
Definition: attributes.hpp:57
std::vector< xml::ns > ns_list_type
type for holding XML namespaces
Definition: namespace.hpp:208
static const char * prefix[]
Definition: pcregrep.c:405
Definition: type.c:6
Modified on Sat Jul 20 11:09:23 2024 by modify_doxy.py rev. 669887