# 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