pointer.h

Go to the documentation of this file.
00001 // Custom pointer adapter and sample storage policies
00002 
00003 // Copyright (C) 2008, 2009 Free Software Foundation, Inc.
00004 //
00005 // This file is part of the GNU ISO C++ Library.  This library is free
00006 // software; you can redistribute it and/or modify it under the
00007 // terms of the GNU General Public License as published by the
00008 // Free Software Foundation; either version 3, or (at your option)
00009 // any later version.
00010 
00011 // This library is distributed in the hope that it will be useful,
00012 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00013 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014 // GNU General Public License for more details.
00015 
00016 // Under Section 7 of GPL version 3, you are granted additional
00017 // permissions described in the GCC Runtime Library Exception, version
00018 // 3.1, as published by the Free Software Foundation.
00019 
00020 // You should have received a copy of the GNU General Public License and
00021 // a copy of the GCC Runtime Library Exception along with this program;
00022 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
00023 // <http://www.gnu.org/licenses/>.
00024 
00025 /**
00026  * @file ext/pointer.h
00027  * @author Bob Walters
00028  *
00029  * Provides reusable _Pointer_adapter for assisting in the development of
00030  * custom pointer types that can be used with the standard containers via
00031  * the allocator::pointer and allocator::const_pointer typedefs.
00032  */
00033 
00034 #ifndef _POINTER_H
00035 #define _POINTER_H 1
00036 
00037 #include <iosfwd>
00038 #include <bits/stl_iterator_base_types.h>
00039 #include <ext/cast.h>
00040 #include <ext/type_traits.h>
00041 
00042 _GLIBCXX_BEGIN_NAMESPACE(__gnu_cxx)
00043 
00044   /** 
00045    * @brief A storage policy for use with _Pointer_adapter<> which yields a
00046    *        standard pointer.
00047    * 
00048    *  A _Storage_policy is required to provide 4 things:
00049    *    1) A get() API for returning the stored pointer value.
00050    *    2) An set() API for storing a pointer value.
00051    *    3) An element_type typedef to define the type this points to.
00052    *    4) An operator<() to support pointer comparison.
00053    *    5) An operator==() to support pointer comparison.
00054    */
00055   template<typename _Tp> 
00056     class _Std_pointer_impl 
00057     {
00058     public:
00059       // the type this pointer points to.
00060       typedef _Tp element_type;
00061   
00062       // A method to fetch the pointer value as a standard T* value;
00063       inline _Tp* 
00064       get() const 
00065       { return _M_value; }
00066   
00067       // A method to set the pointer value, from a standard T* value;
00068       inline void 
00069       set(element_type* __arg) 
00070       { _M_value = __arg; }
00071   
00072       // Comparison of pointers
00073       inline bool
00074       operator<(const _Std_pointer_impl& __rarg) const
00075       { return (_M_value < __rarg._M_value); }
00076   
00077       inline bool
00078       operator==(const _Std_pointer_impl& __rarg) const
00079       { return (_M_value == __rarg._M_value); }
00080 
00081     private:
00082       element_type* _M_value;
00083     };
00084 
00085   /**
00086    * @brief A storage policy for use with _Pointer_adapter<> which stores
00087    *        the pointer's address as an offset value which is relative to
00088    *        its own address.
00089    * 
00090    * This is intended for pointers
00091    * within shared memory regions which might be mapped at different
00092    * addresses by different processes.  For null pointers, a value of 1 is
00093    * used.  (0 is legitimate sometimes for nodes in circularly linked lists)
00094    * This value was chosen as the least likely to generate an incorrect null,
00095    * As there is no reason why any normal pointer would point 1 byte into
00096    * its own pointer address.
00097    */
00098   template<typename _Tp> 
00099     class _Relative_pointer_impl 
00100     {
00101     public:
00102       typedef _Tp element_type;
00103   
00104       _Tp*
00105       get() const 
00106       {
00107         if (_M_diff == 1)
00108           return 0;
00109         else
00110           return reinterpret_cast<_Tp*>(reinterpret_cast<_UIntPtrType>(this)
00111                     + _M_diff);
00112       }
00113   
00114       void 
00115       set(_Tp* __arg)
00116       {
00117         if (!__arg)
00118           _M_diff = 1;
00119         else
00120           _M_diff = reinterpret_cast<_UIntPtrType>(__arg) 
00121                     - reinterpret_cast<_UIntPtrType>(this);
00122       }
00123   
00124       // Comparison of pointers
00125       inline bool
00126       operator<(const _Relative_pointer_impl& __rarg) const
00127       { return (reinterpret_cast<_UIntPtrType>(this->get())
00128         < reinterpret_cast<_UIntPtrType>(__rarg.get())); }
00129 
00130       inline bool
00131       operator==(const _Relative_pointer_impl& __rarg) const
00132       { return (reinterpret_cast<_UIntPtrType>(this->get())
00133         == reinterpret_cast<_UIntPtrType>(__rarg.get())); }
00134 
00135     private:
00136       typedef __gnu_cxx::__conditional_type<
00137      (sizeof(unsigned long) >= sizeof(void*)),
00138      unsigned long, unsigned long long>::__type _UIntPtrType;
00139       _UIntPtrType _M_diff;
00140     };
00141   
00142   /**
00143    * Relative_pointer_impl needs a specialization for const T because of
00144    * the casting done during pointer arithmetic.
00145    */
00146   template<typename _Tp> 
00147     class _Relative_pointer_impl<const _Tp> 
00148     {
00149     public:
00150       typedef const _Tp element_type;
00151   
00152       const _Tp*
00153       get() const
00154       {
00155         if (_M_diff == 1)
00156           return 0;
00157         else
00158           return reinterpret_cast<const _Tp*>
00159           (reinterpret_cast<_UIntPtrType>(this) + _M_diff);
00160       }
00161   
00162       void 
00163       set(const _Tp* __arg)
00164       {
00165         if (!__arg)
00166           _M_diff = 1;
00167         else
00168           _M_diff = reinterpret_cast<_UIntPtrType>(__arg) 
00169                     - reinterpret_cast<_UIntPtrType>(this);
00170       }
00171   
00172       // Comparison of pointers
00173       inline bool
00174       operator<(const _Relative_pointer_impl& __rarg) const
00175       { return (reinterpret_cast<_UIntPtrType>(this->get())
00176         < reinterpret_cast<_UIntPtrType>(__rarg.get())); }
00177 
00178       inline bool
00179       operator==(const _Relative_pointer_impl& __rarg) const
00180       { return (reinterpret_cast<_UIntPtrType>(this->get())
00181         == reinterpret_cast<_UIntPtrType>(__rarg.get())); }
00182   
00183     private:
00184       typedef __gnu_cxx::__conditional_type
00185     <(sizeof(unsigned long) >= sizeof(void*)),
00186      unsigned long, unsigned long long>::__type _UIntPtrType;
00187       _UIntPtrType _M_diff;
00188     };
00189 
00190   /**
00191    * The specialization on this type helps resolve the problem of
00192    * reference to void, and eliminates the need to specialize _Pointer_adapter
00193    * for cases of void*, const void*, and so on.
00194    */
00195   struct _Invalid_type { };
00196   
00197   template<typename _Tp>
00198     struct _Reference_type 
00199     { typedef _Tp& reference; };
00200 
00201   template<> 
00202     struct _Reference_type<void> 
00203     { typedef _Invalid_type& reference; };
00204 
00205   template<> 
00206     struct _Reference_type<const void> 
00207     { typedef const _Invalid_type& reference; };
00208 
00209   template<> 
00210     struct _Reference_type<volatile void> 
00211     { typedef volatile _Invalid_type&  reference; };
00212 
00213   template<> 
00214     struct _Reference_type<volatile const void> 
00215     { typedef const volatile _Invalid_type&  reference; };
00216 
00217   /**
00218    * This structure accomodates the way in which std::iterator_traits<>
00219    * is normally specialized for const T*, so that value_type is still T.
00220    */
00221   template<typename _Tp> 
00222     struct _Unqualified_type 
00223     { typedef _Tp type; };
00224     
00225   template<typename _Tp> 
00226     struct _Unqualified_type<const _Tp> 
00227     { typedef _Tp type; };
00228     
00229   template<typename _Tp> 
00230     struct _Unqualified_type<volatile _Tp> 
00231     { typedef volatile _Tp type; };
00232     
00233   template<typename _Tp> 
00234     struct _Unqualified_type<volatile const _Tp> 
00235     { typedef volatile _Tp type; };
00236   
00237   /**
00238    * The following provides an 'alternative pointer' that works with the
00239    * containers when specified as the pointer typedef of the allocator.
00240    *
00241    * The pointer type used with the containers doesn't have to be this class,
00242    * but it must support the implicit conversions, pointer arithmetic,
00243    * comparison operators, etc. that are supported by this class, and avoid
00244    * raising compile-time ambiguities.  Because creating a working pointer can
00245    * be challenging, this pointer template was designed to wrapper an 
00246    * easier storage policy type, so that it becomes reusable for creating
00247    * other pointer types. 
00248    *
00249    * A key point of this class is also that it allows container writers to
00250    * 'assume' Alocator::pointer is a typedef for a normal pointer.  This class
00251    * supports most of the conventions of a true pointer, and can, for instance
00252    * handle implicit conversion to const and base class pointer types.  The
00253    * only impositions on container writers to support extended pointers are:
00254    * 1) use the Allocator::pointer typedef appropriately for pointer types.
00255    * 2) if you need pointer casting, use the __pointer_cast<> functions
00256    *    from ext/cast.h.  This allows pointer cast operations to be overloaded
00257    *    is necessary by custom pointers.
00258    *
00259    * Note:  The const qualifier works with this pointer adapter as follows:
00260    *
00261    * _Tp*             == _Pointer_adapter<_Std_pointer_impl<_Tp> >;
00262    * const _Tp*       == _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
00263    * _Tp* const       == const _Pointer_adapter<_Std_pointer_impl<_Tp> >;
00264    * const _Tp* const == const _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
00265    */
00266   template<typename _Storage_policy>
00267     class _Pointer_adapter : public _Storage_policy 
00268     {
00269     public:
00270       typedef typename _Storage_policy::element_type element_type;
00271 
00272       // These are needed for iterator_traits
00273       typedef std::random_access_iterator_tag                iterator_category;
00274       typedef typename _Unqualified_type<element_type>::type value_type;
00275       typedef std::ptrdiff_t                                 difference_type;
00276       typedef _Pointer_adapter                               pointer;
00277       typedef typename _Reference_type<element_type>::reference  reference;
00278 
00279       // Reminder: 'const' methods mean that the method is valid when the 
00280       // pointer is immutable, and has nothing to do with whether the 
00281       // 'pointee' is const.
00282 
00283       // Default Constructor (Convert from element_type*)
00284       _Pointer_adapter(element_type* __arg = 0)
00285       { _Storage_policy::set(__arg); }
00286 
00287       // Copy constructor from _Pointer_adapter of same type.
00288       _Pointer_adapter(const _Pointer_adapter& __arg) 
00289       { _Storage_policy::set(__arg.get()); }
00290 
00291       // Convert from _Up* if conversion to element_type* is valid.
00292       template<typename _Up>
00293         _Pointer_adapter(_Up* __arg)
00294         { _Storage_policy::set(__arg); }
00295 
00296       // Conversion from another _Pointer_adapter if _Up if static cast is
00297       // valid.
00298       template<typename _Up>
00299         _Pointer_adapter(const _Pointer_adapter<_Up>& __arg)
00300         { _Storage_policy::set(__arg.get()); }
00301 
00302       // Destructor
00303       ~_Pointer_adapter() { }
00304   
00305       // Assignment operator
00306       _Pointer_adapter&
00307       operator=(const _Pointer_adapter& __arg) 
00308       {
00309         _Storage_policy::set(__arg.get()); 
00310         return *this; 
00311       }
00312 
00313       template<typename _Up>
00314         _Pointer_adapter&
00315         operator=(const _Pointer_adapter<_Up>& __arg)
00316         {
00317           _Storage_policy::set(__arg.get()); 
00318           return *this; 
00319         }
00320 
00321       template<typename _Up>
00322         _Pointer_adapter&
00323         operator=(_Up* __arg)
00324         {
00325           _Storage_policy::set(__arg); 
00326           return *this; 
00327         }
00328 
00329       // Operator*, returns element_type&
00330       inline reference 
00331       operator*() const 
00332       { return *(_Storage_policy::get()); }
00333 
00334       // Operator->, returns element_type*
00335       inline element_type* 
00336       operator->() const 
00337       { return _Storage_policy::get(); }
00338 
00339       // Operator[], returns a element_type& to the item at that loc.
00340       inline reference
00341       operator[](std::ptrdiff_t __index) const
00342       { return _Storage_policy::get()[__index]; }
00343 
00344       // To allow implicit conversion to "bool", for "if (ptr)..."
00345     private:
00346       typedef element_type*(_Pointer_adapter::*__unspecified_bool_type)() const;
00347 
00348     public:
00349       operator __unspecified_bool_type() const
00350       {
00351         return _Storage_policy::get() == 0 ? 0 : 
00352                          &_Pointer_adapter::operator->; 
00353       }
00354 
00355       // ! operator (for: if (!ptr)...)
00356       inline bool
00357       operator!() const 
00358       { return (_Storage_policy::get() == 0); }
00359   
00360       // Pointer differences
00361       inline friend std::ptrdiff_t 
00362       operator-(const _Pointer_adapter& __lhs, element_type* __rhs) 
00363       { return (__lhs.get() - __rhs); }
00364   
00365       inline friend std::ptrdiff_t 
00366       operator-(element_type* __lhs, const _Pointer_adapter& __rhs) 
00367       { return (__lhs - __rhs.get()); }
00368   
00369       template<typename _Up>
00370         inline friend std::ptrdiff_t 
00371         operator-(const _Pointer_adapter& __lhs, _Up* __rhs) 
00372         { return (__lhs.get() - __rhs); }
00373     
00374       template<typename _Up>
00375         inline friend std::ptrdiff_t 
00376         operator-(_Up* __lhs, const _Pointer_adapter& __rhs)
00377         { return (__lhs - __rhs.get()); }
00378 
00379       template<typename _Up>
00380         inline std::ptrdiff_t 
00381         operator-(const _Pointer_adapter<_Up>& __rhs) const 
00382         { return (_Storage_policy::get() - __rhs.get()); }
00383   
00384       // Pointer math
00385       // Note: There is a reason for all this overloading based on different
00386       // integer types.  In some libstdc++-v3 test cases, a templated
00387       // operator+ is declared which can match any types.  This operator
00388       // tends to "steal" the recognition of _Pointer_adapter's own operator+ 
00389       // unless the integer type matches perfectly.
00390 
00391 #define _CXX_POINTER_ARITH_OPERATOR_SET(INT_TYPE) \
00392       inline friend _Pointer_adapter \
00393       operator+(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
00394       { return _Pointer_adapter(__lhs.get() + __offset); } \
00395 \
00396       inline friend _Pointer_adapter \
00397       operator+(INT_TYPE __offset, const _Pointer_adapter& __rhs) \
00398       { return _Pointer_adapter(__rhs.get() + __offset); } \
00399 \
00400       inline friend _Pointer_adapter \
00401       operator-(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
00402       { return _Pointer_adapter(__lhs.get() - __offset); } \
00403 \
00404       inline _Pointer_adapter& \
00405       operator+=(INT_TYPE __offset) \
00406       { \
00407         _Storage_policy::set(_Storage_policy::get() + __offset); \
00408         return *this; \
00409       } \
00410 \
00411       inline _Pointer_adapter& \
00412       operator-=(INT_TYPE __offset) \
00413       { \
00414         _Storage_policy::set(_Storage_policy::get() - __offset); \
00415         return *this; \
00416       } \
00417 // END of _CXX_POINTER_ARITH_OPERATOR_SET macro
00418   
00419       // Expand into the various pointer arithmatic operators needed.
00420       _CXX_POINTER_ARITH_OPERATOR_SET(short);
00421       _CXX_POINTER_ARITH_OPERATOR_SET(unsigned short);
00422       _CXX_POINTER_ARITH_OPERATOR_SET(int);
00423       _CXX_POINTER_ARITH_OPERATOR_SET(unsigned int);
00424       _CXX_POINTER_ARITH_OPERATOR_SET(long);
00425       _CXX_POINTER_ARITH_OPERATOR_SET(unsigned long);
00426 
00427       // Mathematical Manipulators
00428       inline _Pointer_adapter& 
00429       operator++()
00430       {
00431         _Storage_policy::set(_Storage_policy::get() + 1); 
00432         return *this;
00433       }
00434   
00435       inline _Pointer_adapter 
00436       operator++(int __unused) 
00437       {
00438         _Pointer_adapter tmp(*this);
00439         _Storage_policy::set(_Storage_policy::get() + 1);
00440         return tmp;
00441       }
00442   
00443       inline _Pointer_adapter& 
00444       operator--() 
00445       {
00446         _Storage_policy::set(_Storage_policy::get() - 1); 
00447         return *this;
00448       }
00449   
00450       inline _Pointer_adapter
00451       operator--(int) 
00452       {
00453         _Pointer_adapter tmp(*this);
00454         _Storage_policy::set(_Storage_policy::get() - 1);
00455         return tmp;
00456       }
00457   
00458     }; // class _Pointer_adapter
00459 
00460 
00461 #define _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(OPERATOR,BLANK) \
00462   template<typename _Tp1, typename _Tp2> \
00463     inline bool \
00464     operator OPERATOR##BLANK (const _Pointer_adapter<_Tp1>& __lhs, _Tp2 __rhs) \
00465     { return __lhs.get() OPERATOR##BLANK __rhs; } \
00466 \
00467   template<typename _Tp1, typename _Tp2> \
00468     inline bool \
00469     operator OPERATOR##BLANK (_Tp1 __lhs, const _Pointer_adapter<_Tp2>& __rhs) \
00470     { return __lhs OPERATOR##BLANK __rhs.get(); } \
00471 \
00472   template<typename _Tp1, typename _Tp2> \
00473     inline bool \
00474     operator OPERATOR##BLANK (const _Pointer_adapter<_Tp1>& __lhs, \
00475                               const _Pointer_adapter<_Tp2>& __rhs) \
00476     { return __lhs.get() OPERATOR##BLANK __rhs.get(); } \
00477 \
00478 // End GCC_CXX_POINTER_COMPARISON_OPERATION_SET Macro
00479   
00480   // Expand into the various comparison operators needed.
00481   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(==,);
00482   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(!=,);
00483   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<,);
00484   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<=,);
00485   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>,);
00486   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>=,);
00487 
00488   // These are here for expressions like "ptr == 0", "ptr != 0"
00489   template<typename _Tp>
00490     inline bool
00491     operator==(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
00492     { return __lhs.get() == reinterpret_cast<void*>(__rhs); } 
00493 
00494   template<typename _Tp>
00495     inline bool
00496     operator==(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
00497     { return __rhs.get() == reinterpret_cast<void*>(__lhs); } 
00498 
00499   template<typename _Tp>
00500     inline bool
00501     operator!=(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
00502     { return __lhs.get() != reinterpret_cast<void*>(__rhs); } 
00503 
00504   template<typename _Tp>
00505     inline bool
00506     operator!=(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
00507     { return __rhs.get() != reinterpret_cast<void*>(__lhs); } 
00508 
00509   /**
00510    * Comparison operators for _Pointer_adapter defer to the base class'es
00511    * comparison operators, when possible.
00512    */
00513   template<typename _Tp>
00514     inline bool
00515     operator==(const _Pointer_adapter<_Tp>& __lhs, 
00516                const _Pointer_adapter<_Tp>& __rhs)
00517     { return __lhs._Tp::operator==(__rhs); }
00518 
00519   template<typename _Tp>
00520     inline bool
00521     operator<=(const _Pointer_adapter<_Tp>& __lhs, 
00522                const _Pointer_adapter<_Tp>& __rhs)
00523     { return __lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs); }
00524 
00525   template<typename _Tp>
00526     inline bool
00527     operator!=(const _Pointer_adapter<_Tp>& __lhs, 
00528                const _Pointer_adapter<_Tp>& __rhs)
00529     { return !(__lhs._Tp::operator==(__rhs)); }
00530 
00531   template<typename _Tp>
00532     inline bool
00533     operator>(const _Pointer_adapter<_Tp>& __lhs, 
00534               const _Pointer_adapter<_Tp>& __rhs)
00535     { return !(__lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs)); }
00536 
00537   template<typename _Tp>
00538     inline bool
00539     operator>=(const _Pointer_adapter<_Tp>& __lhs, 
00540                const _Pointer_adapter<_Tp>& __rhs)
00541     { return !(__lhs._Tp::operator<(__rhs)); }
00542 
00543   template<typename _CharT, typename _Traits, typename _StoreT>
00544     inline std::basic_ostream<_CharT, _Traits>&
00545     operator<<(std::basic_ostream<_CharT, _Traits>& __os, 
00546                const _Pointer_adapter<_StoreT>& __p)
00547     { return (__os << __p.get()); }
00548 
00549 _GLIBCXX_END_NAMESPACE
00550 
00551 #endif // _POINTER_H

Generated on Thu Jul 23 21:16:12 2009 for libstdc++ by  doxygen 1.5.8