Main Page | Class Hierarchy | Class List | File List | Class Members

attributes.h

Go to the documentation of this file.
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

Generated on Tue Oct 19 12:26:02 2004 for xmlwrapp by doxygen 1.3.6