Polaris: BaseRefElement.h Source File

00001 ///
00002 ///
00003 #ifndef _BASE_REF_ELEMENT_H
00004 #define _BASE_REF_ELEMENT_H
00005 ///
00006 /// \class RefElement 
00007 /// \brief template for types derived from Listable
00008 /// \defgroup Polaris
00009 /// \ingroup Polaris
00010 ///  C++ VDL
00011 /// \see BaseRefElement.h
00012 ///
00013 /// \endcode
00014 /// \section DESCRIPTION DESCRIPTION
00015 /// RefElement is a Collection structure which allows a reference to a
00016 /// single Listable object.  It can be viewed as providing the
00017 /// functionality of a single-element RefList.  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 ///   RefElement<Statement> p;
00028 /// 
00029 ///   p = stmt; // 'p' now references 'stmt'
00030 ///             // 'p.modify(stmt);' does the same thing.
00031 ///
00032 ///
00033 ///   cout << *p;  // '*p' returns a reference to stmt
00034 ///   cout << p->tag();  // 'p->' allows access to stmt's class members
00035 ///
00036 ///   Element<Statement> q = p;  // Copies p's reference
00037 ///
00038 ///   Statement &s = q.grab();  // Returns reference from q
00039 ///
00040 ///   p.del();      // Removes p's reference
00041 /// }
00042 /// \endcode
00043 ///
00044 /// There also exist methods valid, member and modify_and_grab.
00045 ///
00046 #ifdef POLARIS_GNU_PRAGMAS
00047 #pragma interface
00048 #endif
00049 ///
00050 #include <stream.h>
00051 #include "../Listable.h"
00052 #include "../macros.h"
00053 #include "ProtoWrapper.h"
00054 ///
00055 class BaseRefElement : public Listable {
00056     friend ostream & operator << (ostream & o, const BaseRefElement &e);
00057 
00058  protected:
00059     ProtoWrapper            _wrap;
00060 
00061  public:
00062     INLINE BaseRefElement();
00063     INLINE BaseRefElement(Listable &e);
00064     INLINE BaseRefElement(const BaseRefElement &e);
00065 
00066     ~BaseRefElement();
00067 
00068     INLINE BaseRefElement & operator=(const Listable &l);
00069     ///< Change reference to l
00070     
00071     INLINE const Listable & operator*() const;
00072     INLINE Listable & operator*();
00073     ///< Return a reference to the object referenced by Element.
00074 
00075     INLINE const Listable * operator->() const;
00076     INLINE Listable * operator->();
00077     ///< Allows class member access of the object referenced by Element
00078 
00079     void     modify(Listable &el);
00080     ///< change the reference.
00081 
00082     void     del();
00083     ///< Delete the reference.
00084 
00085     Listable &      grab();
00086     ///< Delete and return the reference
00087     
00088     Listable &      modify_and_grab(Listable &el);
00089     ///< Switch reference to el and return the old reference
00090 
00091     INLINE Boolean  member(Listable &el) const;
00092     ///< Check to see if node 'el' the same as the BaseRefElement.  Return
00093     ///< 0 if the element was not the same, else return 1.
00094 
00095     INLINE Boolean  valid() const;
00096     ///< Check to see if the element if valid.
00097 
00098     INLINE BaseRefElement & operator = (const BaseRefElement &e);
00099     ///< Copy operator copies all the reference from BaseRefElement e
00100 
00101     int      structures_OK() const;
00102     ///< Check the structure of the data for errors or inconsistency
00103     ///< Return 0 and print error message if problems found, otherwise
00104     ///< return 1 without message.
00105 
00106     Listable *listable_clone() const;
00107     ///< Needed for Listable class.
00108 
00109     void      print(ostream &o) const;
00110     ///< Needed for Listable class.
00111 };
00112 
00113 
00114 ///< implementation
00115 
00116 INLINE 
00117 BaseRefElement::BaseRefElement()
00118 {
00119     _wrap.set(0);
00120 }
00121 
00122 INLINE 
00123 BaseRefElement::BaseRefElement(const BaseRefElement &e)
00124 {
00125     if (e._wrap.get())
00126         modify(*( e._wrap.get()));
00127     else
00128         _wrap.set(0);
00129 }
00130 
00131 INLINE BaseRefElement &
00132 BaseRefElement::operator=(const Listable &l)
00133 {
00134     modify( CASTAWAY(Listable &) l);
00135 
00136     return *this;
00137 }
00138     
00139 INLINE const Listable &
00140 BaseRefElement::operator*() const
00141 {
00142     return *_wrap.get();
00143 }
00144 
00145 INLINE Listable &
00146 BaseRefElement::operator*()
00147 {
00148     return *_wrap.get();
00149 }
00150 
00151 INLINE const Listable *
00152 BaseRefElement::operator->() const
00153 {
00154     return _wrap.get();
00155 }
00156 
00157 INLINE Listable *
00158 BaseRefElement::operator->()
00159 {
00160     return _wrap.get();
00161 }
00162 
00163 INLINE Boolean  
00164 BaseRefElement::member(Listable &el) const
00165 {
00166     return (_wrap.get() == &el);
00167 }
00168 
00169 INLINE Boolean  
00170 BaseRefElement::valid() const
00171 {
00172     return (_wrap.get() != 0);
00173 }
00174 
00175 INLINE BaseRefElement &
00176 BaseRefElement::operator = (const BaseRefElement &e) 
00177 {
00178     if (e._wrap.get()) 
00179         modify(*e._wrap.get() );
00180     else
00181         _wrap.set(0);
00182 
00183     return *this;
00184 }
00185 
00186 #endif