00001 /* 00002 * Copyright (C) 2001-2003 Peter J Jones (pjones@pmade.org) 00003 * All Rights Reserved 00004 * 00005 * Redistribution and use in source and binary forms, with or without 00006 * modification, are permitted provided that the following conditions 00007 * are met: 00008 * 00009 * 1. Redistributions of source code must retain the above copyright 00010 * notice, this list of conditions and the following disclaimer. 00011 * 2. Redistributions in binary form must reproduce the above copyright 00012 * notice, this list of conditions and the following disclaimer in 00013 * the documentation and/or other materials provided with the 00014 * distribution. 00015 * 3. Neither the name of the Author nor the names of its contributors 00016 * may be used to endorse or promote products derived from this software 00017 * without specific prior written permission. 00018 * 00019 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' 00020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 00021 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 00022 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR 00023 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 00024 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 00025 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 00026 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 00027 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 00028 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 00029 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 00030 * SUCH DAMAGE. 00031 */ 00032 00033 /** @file 00034 * This file contains the definition of the xml::attributes class. 00035 **/ 00036 00037 #ifndef _xmlwrapp_attributes_h_ 00038 #define _xmlwrapp_attributes_h_ 00039 00040 // standard includes 00041 #include <cstddef> 00042 #include <iosfwd> 00043 #include <string> 00044 00045 namespace xml { 00046 00047 // forward declarations 00048 class node; 00049 class ait_impl; 00050 struct node_impl; 00051 00052 /** 00053 * The xml::attributes class is used to access all the attributes of one 00054 * xml::node. You can add, find and erase attributes by name, and for some 00055 * member functions, use the provided iterator classes. 00056 * 00057 * The iterator classes allow you to access one XML attribute. This is done 00058 * using the xml::attributes::attr class interface. 00059 **/ 00060 class attributes { 00061 public: 00062 typedef std::size_t size_type; ///< size type 00063 00064 //#################################################################### 00065 /** 00066 * Create a new xml::attributes object with no attributes. 00067 * 00068 * @author Peter Jones 00069 **/ 00070 //#################################################################### 00071 attributes (void); 00072 00073 //#################################################################### 00074 /** 00075 * Copy construct a xml::attributes object. 00076 * 00077 * @param other The xml::attributes object to copy from. 00078 * @author Peter Jones 00079 **/ 00080 //#################################################################### 00081 attributes (const attributes &other); 00082 00083 //#################################################################### 00084 /** 00085 * Copy the given xml::attributes object into this one. 00086 * 00087 * @param other The xml::attributes object to copy from. 00088 * @return *this. 00089 * @author Peter Jones 00090 **/ 00091 //#################################################################### 00092 attributes& operator= (const attributes &other); 00093 00094 //#################################################################### 00095 /** 00096 * Swap this xml::attributes object with another one. 00097 * 00098 * @param other The other xml::attributes object to swap with. 00099 * @author Peter Jones 00100 **/ 00101 //#################################################################### 00102 void swap (attributes &other); 00103 00104 //#################################################################### 00105 /** 00106 * Clean up after a xml::attributes object. 00107 * 00108 * @author Peter Jones 00109 **/ 00110 //#################################################################### 00111 ~attributes (void); 00112 00113 // forward declarations 00114 class const_iterator; 00115 00116 /** 00117 * The xml::attributes::attr class is used to hold information about one 00118 * attribute. 00119 */ 00120 class attr { 00121 public: 00122 //#################################################################### 00123 /** 00124 * Get the name of this attribute. 00125 * 00126 * @return The name for this attribute. 00127 * @author Peter Jones 00128 **/ 00129 //#################################################################### 00130 const char* get_name (void) const; 00131 00132 //#################################################################### 00133 /** 00134 * Get the value of this attribute. 00135 * 00136 * @return The value for this attribute. 00137 * @author Peter Jones 00138 **/ 00139 //#################################################################### 00140 const char* get_value (void) const; 00141 private: 00142 void *node_; 00143 void *prop_; 00144 std::string name_; 00145 mutable std::string value_; 00146 00147 attr (void); 00148 attr (const attr &other); 00149 attr& operator= (const attr &other); 00150 void swap (attr &other); 00151 00152 void set_data (void *node, void *prop); 00153 void set_data (const char *name, const char *value, bool); 00154 friend class ait_impl; 00155 }; // end xml::attributes::attr class 00156 00157 /** 00158 * Iterator class for accessing attribute pairs. 00159 */ 00160 class iterator { 00161 public: 00162 typedef attr value_type; 00163 typedef std::ptrdiff_t difference_type; 00164 typedef value_type* pointer; 00165 typedef value_type& reference; 00166 typedef std::forward_iterator_tag iterator_category; 00167 00168 iterator (void); 00169 iterator (const iterator &other); 00170 iterator& operator= (const iterator& other); 00171 ~iterator (void); 00172 00173 reference operator* (void) const; 00174 pointer operator-> (void) const; 00175 00176 /// prefix increment 00177 iterator& operator++ (void); 00178 00179 /// postfix increment (avoid if possible for better performance) 00180 iterator operator++ (int); 00181 00182 friend bool operator== (const iterator &lhs, const iterator &rhs); 00183 friend bool operator!= (const iterator &lhs, const iterator &rhs); 00184 private: 00185 ait_impl *pimpl_; 00186 iterator (void *node, void *prop); 00187 iterator (const char *name, const char *value, bool); 00188 void swap (iterator &other); 00189 void* get_raw_attr (void); 00190 friend class attributes; 00191 friend class const_iterator; 00192 }; // end xml::attributes::iterator class 00193 00194 /** 00195 * Const Iterator class for accessing attribute pairs. 00196 */ 00197 class const_iterator { 00198 public: 00199 typedef const attr value_type; 00200 typedef std::ptrdiff_t difference_type; 00201 typedef value_type* pointer; 00202 typedef value_type& reference; 00203 typedef std::forward_iterator_tag iterator_category; 00204 00205 const_iterator (void); 00206 const_iterator (const const_iterator &other); 00207 const_iterator (const iterator &other); 00208 const_iterator& operator= (const const_iterator& other); 00209 ~const_iterator (void); 00210 00211 reference operator* (void) const; 00212 pointer operator-> (void) const; 00213 00214 /// prefix increment 00215 const_iterator& operator++ (void); 00216 00217 /// postfix increment (avoid if possible better for performance) 00218 const_iterator operator++ (int); 00219 00220 friend bool operator== (const const_iterator &lhs, const const_iterator &rhs); 00221 friend bool operator!= (const const_iterator &lhs, const const_iterator &rhs); 00222 private: 00223 ait_impl *pimpl_; 00224 const_iterator (void *node, void *prop); 00225 const_iterator (const char *name, const char *value, bool); 00226 void swap (const_iterator &other); 00227 void* get_raw_attr (void); 00228 friend class attributes; 00229 }; // end xml::attributes::const_iterator class 00230 00231 //#################################################################### 00232 /** 00233 * Get an iterator that points to the first attribute. 00234 * 00235 * @return An iterator that points to the first attribute. 00236 * @return An iterator equal to end() if there are no attributes. 00237 * @see xml::attributes::iterator 00238 * @see xml::attributes::attr 00239 * @author Peter Jones 00240 **/ 00241 //#################################################################### 00242 iterator begin (void); 00243 00244 //#################################################################### 00245 /** 00246 * Get a const_iterator that points to the first attribute. 00247 * 00248 * @return A const_iterator that points to the first attribute. 00249 * @return A const_iterator equal to end() if there are no attributes. 00250 * @see xml::attributes::const_iterator 00251 * @see xml::attributes::attr 00252 * @author Peter Jones 00253 **/ 00254 //#################################################################### 00255 const_iterator begin (void) const; 00256 00257 //#################################################################### 00258 /** 00259 * Get an iterator that points one past the the last attribute. 00260 * 00261 * @return An "end" iterator. 00262 * @author Peter Jones 00263 **/ 00264 //#################################################################### 00265 iterator end (void); 00266 00267 //#################################################################### 00268 /** 00269 * Get a const_iterator that points one past the last attribute. 00270 * 00271 * @return An "end" const_iterator. 00272 * @author Peter Jones 00273 **/ 00274 //#################################################################### 00275 const_iterator end (void) const; 00276 00277 //#################################################################### 00278 /** 00279 * Add an attribute to the attributes list. If there is another 00280 * attribute with the same name, it will be replaced with this one. 00281 * 00282 * @param name The name of the attribute to add. 00283 * @param value The value of the attribute to add. 00284 * @author Peter Jones 00285 **/ 00286 //#################################################################### 00287 void insert (const char *name, const char *value); 00288 00289 //#################################################################### 00290 /** 00291 * Find the attribute with the given name. If the attribute is not found 00292 * on the current node, the DTD will be searched for a default value. 00293 * This is, of course, if there was a DTD parsed with the XML document. 00294 * 00295 * @param name The name of the attribute to find. 00296 * @return An iterator that points to the attribute with the given name. 00297 * @return If the attribute was not found, find will return end(). 00298 * @see xml::attributes::iterator 00299 * @see xml::attributes::attr 00300 * @author Peter Jones 00301 **/ 00302 //#################################################################### 00303 iterator find (const char *name); 00304 00305 //#################################################################### 00306 /** 00307 * Find the attribute with the given name. If the attribute is not found 00308 * on the current node, the DTD will be searched for a default value. 00309 * This is, of course, if there was a DTD parsed with the XML document. 00310 * 00311 * @param name The name of the attribute to find. 00312 * @return A const_iterator that points to the attribute with the given name. 00313 * @return If the attribute was not found, find will return end(). 00314 * @see xml::attributes::const_iterator 00315 * @see xml::attributes::attr 00316 * @author Peter Jones 00317 **/ 00318 //#################################################################### 00319 const_iterator find (const char *name) const; 00320 00321 //#################################################################### 00322 /** 00323 * Erase the attribute that is pointed to by the given iterator. This 00324 * will invalidate any iterators for this attribute, as well as any 00325 * pointers or references to it. 00326 * 00327 * @param to_erase An iterator that points to the attribute to erased. 00328 * @return An iterator that points to the attribute after the one to be erased. 00329 * @see xml::attributes::iterator 00330 * @see xml::attributes::attr 00331 * @author Peter Jones 00332 **/ 00333 //#################################################################### 00334 iterator erase (iterator to_erase); 00335 00336 //#################################################################### 00337 /** 00338 * Erase the attribute with the given name. This will invalidate any 00339 * iterators that are pointing to that attribute, as well as any 00340 * pointers or references to that attribute. 00341 * 00342 * @param name The name of the attribute to erase. 00343 * @author Peter Jones 00344 **/ 00345 //#################################################################### 00346 void erase (const char *name); 00347 00348 //#################################################################### 00349 /** 00350 * Find out if there are any attributes in this xml::attributes object. 00351 * 00352 * @return True if there are no attributes. 00353 * @return False if there is at least one attribute. 00354 * @author Peter Jones 00355 **/ 00356 //#################################################################### 00357 bool empty (void) const; 00358 00359 //#################################################################### 00360 /** 00361 * Find out how many attributes there are in this xml::attributes 00362 * object. 00363 * 00364 * @return The number of attributes in this xml::attributes object. 00365 * @author Peter Jones 00366 **/ 00367 //#################################################################### 00368 size_type size (void) const; 00369 00370 private: 00371 struct pimpl; pimpl *pimpl_; 00372 explicit attributes (int); 00373 void set_data (void *node); 00374 void* get_data (void); 00375 friend struct node_impl; 00376 friend class node; 00377 }; // end xml::attributes class 00378 00379 } // end xml namespace 00380 #endif