Polaris: BaseElement.h Source File

00001 ///
00002 ///
00003 #ifndef _BASE_ELEMENT_H
00004 #define _BASE_ELEMENT_H
00005 ///
00006 /// \class Element 
00007 /// \brief template for types derived from Listable
00008 /// \defgroup Polaris
00009 /// \ingroup Polaris
00010 ///  C++ VDL
00011 /// \see BaseElement.h
00012 ///
00013 /// \endcode
00014 /// \section DESCRIPTION DESCRIPTION
00015 /// Element is a Collection structure which takes ownership of a
00016 /// single Listable object.  It can be viewed as providing the
00017 /// functionality of a single-element List.  However, there is
00018 /// much less overhead than a list and a more convenient
00019 /// (pointer-esque) interface.
00020 ///
00021 /// The following examples should describe it:
00022 ///
00023 /// \code
00024 /// void
00025 /// example( Statement *stmt, Statement *stmt2)
00026 /// {
00027 ///   Element<Statement> p;
00028 /// 
00029 ///   p = stmt; // 'p' now has ownership of 'stmt': Error if stmt already owned.
00030 ///             // 'p.modify(stmt);' does the same thing.
00031 ///
00032 ///   p = stmt2; // 'p' now owns 'stmt2'.  'stmt' either deleted or zombied.
00033 ///
00034 ///   cout << *p;  // '*p' returns a reference to stmt
00035 ///   cout << p->tag();  // 'p->' allows access to stmt's class members
00036 ///
00037 ///   Element<Statement> q = p;  // Copies (clones) p's object
00038 ///
00039 ///   Statement *s = q.grab();  // Returns ownership of object from q
00040 ///
00041 ///   p.del();      // Deletes p's owned object
00042 /// }
00043 ///
00044 /// \endcode
00045 /// There also exist methods valid, member and modify_and_grab.
00046 ///
00047 #ifdef POLARIS_GNU_PRAGMAS
00048 #pragma interface
00049 #endif
00050 ///
00051 #include <stream.h>
00052 #include "../Listable.h"
00053 #include "ProtoWrapper.h"
00054 ///
00055 class BaseElement : public Listable {
00056 
00057 friend ostream & operator << (ostream &o, const BaseElement &e);
00058 
00059   protected:
00060     ProtoWrapper            _wrap;
00061 
00062   public:
00063     INLINE BaseElement();
00064     INLINE BaseElement(Listable *e);
00065     INLINE BaseElement(const BaseElement &e);
00066 
00067     ~BaseElement();
00068 
00069     INLINE BaseElement & operator=(Listable *l);
00070     ///< BaseElement takes ownership of l.  If l already
00071     ///< owned an error is raised.  Previous object deleted or zombied.
00072 
00073     INLINE BaseElement & operator = (const BaseElement &e);
00074     ///< Copy operator copies object of Element
00075     
00076     INLINE const Listable & operator*() const;
00077     INLINE Listable & operator*();
00078     ///< Return a reference to the object owned by BaseElement.
00079 
00080     INLINE const Listable * operator->() const;
00081     INLINE Listable * operator->();
00082     ///< Allows class member access of the object owned by BaseElement
00083     
00084     void     modify(Listable *l);
00085     ///< BaseElement takes ownership of l.  If l already
00086     ///< owned an error is raised. Previous object deleted or zombied.
00087 
00088     Listable *grab();
00089     ///< Remove the object from the BaseElement and return it.
00090 
00091     void     del();
00092     ///< Delete the object (or Zombie it).
00093 
00094     Listable *modify_and_grab(Listable *el);
00095     ///< Change BaseElement's object to el and return the old object.
00096 
00097     INLINE Boolean  member(Listable &el) const;
00098     ///< Check to see if node 'el' the same as the BaseElement.  Return
00099     ///< 0 if the BaseElement was not the same, else return 1.
00100 
00101     INLINE Boolean  valid() const;
00102     ///< Check to see if the BaseElement if valid.
00103 
00104 
00105     INLINE int      structures_OK() const;
00106     ///< Check the structure of the data for errors or inconsistency
00107     ///< Return 0 and print error message if problems found, otherwise
00108     ///< return 1 without message.
00109 
00110     Listable *listable_clone() const;
00111     ///< Needed for Listable class.
00112 
00113     void      print(ostream &o) const;
00114     ///< Needed for Listable class.
00115 };
00116 
00117 
00118 ///< implementation
00119 
00120 
00121 INLINE 
00122 BaseElement::BaseElement()
00123 {
00124     _wrap.set(0);
00125 }
00126 
00127 INLINE 
00128 BaseElement::BaseElement(Listable *e)
00129 {
00130     _wrap.set(0);
00131     modify(e);
00132 }
00133 
00134 
00135 INLINE 
00136 BaseElement::BaseElement(const BaseElement &e)
00137 {
00138     if (e._wrap.get())
00139         modify(e._wrap.get()->listable_clone());
00140     else
00141         _wrap.set(0);
00142 }
00143 
00144 INLINE BaseElement &
00145 BaseElement::operator=(Listable *l)
00146 {
00147     modify(l);
00148     return *this;
00149 }
00150     
00151 INLINE const Listable &
00152 BaseElement::operator*() const
00153 {
00154     return *_wrap.get();
00155 }
00156 
00157 INLINE Listable &
00158 BaseElement::operator*()
00159 {
00160     return *_wrap.get();
00161 }
00162 
00163 INLINE const Listable *
00164 BaseElement::operator->() const
00165 {
00166     return  _wrap.get();
00167 }
00168 
00169 INLINE Listable *
00170 BaseElement::operator->()
00171 {
00172     return  _wrap.get();
00173 }
00174 
00175 INLINE Boolean  
00176 BaseElement::member(Listable &el) const
00177 {
00178     return (_wrap.get() == &el);
00179 }
00180 
00181 INLINE Boolean  
00182 BaseElement::valid() const
00183 {
00184     return (_wrap.get() != 0);
00185 }
00186 
00187 INLINE BaseElement &
00188 BaseElement::operator = (const BaseElement &e) 
00189 {
00190     if (e._wrap.get())
00191         modify(e._wrap.get()->listable_clone() );
00192     else
00193         _wrap.set(0);
00194 
00195     return *this;
00196 }
00197 
00198 INLINE int      
00199 BaseElement::structures_OK() const
00200 {
00201     return 1;   ///< I'm OK, you're OK
00202 }
00203 
00204 #endif
00205 
00206