libstdc++-v3/include/ext/pointer.h

   1 // Custom pointer adapter and sample storage policies
   2
   3 // Copyright (C) 2008 Free Software Foundation, Inc.
   4 //
   5 // This file is part of the GNU ISO C++ Library.  This library is free
   6 // software; you can redistribute it and/or modify it under the
   7 // terms of the GNU General Public License as published by the
   8 // Free Software Foundation; either version 2, or (at your option)
   9 // any later version.
  10
  11 // This library is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15
  16 // You should have received a copy of the GNU General Public License along
  17 // with this library; see the file COPYING.  If not, write to the Free
  18 // Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
  19 // USA.
  20
  21 // As a special exception, you may use this file as part of a free software
  22 // library without restriction.  Specifically, if other files instantiate
  23 // templates or use macros or inline functions from this file, or you compile
  24 // this file and link it with other files to produce an executable, this
  25 // file does not by itself cause the resulting executable to be covered by
  26 // the GNU General Public License.  This exception does not however
  27 // invalidate any other reasons why the executable file might be covered by
  28 // the GNU General Public License.
  29
  30 /**
  31  * @file ext/pointer.h
  32  * @author Bob Walters
  33  *
  34  * Provides reusable _Pointer_adapter for assisting in the development of
  35  * custom pointer types that can be used with the standard containers via
  36  * the allocator::pointer and allocator::const_pointer typedefs.
  37  */
  38
  39 #ifndef _POINTER_H
  40 #define _POINTER_H 1
  41
  42 #include <iosfwd>
  43 #include <bits/stl_iterator_base_types.h>
  44 #include <ext/cast.h>
  45 #include <ext/type_traits.h>
  46
  47 _GLIBCXX_BEGIN_NAMESPACE(__gnu_cxx)
  48
  49   /**
  50    * @brief A storage policy for use with _Pointer_adapter<> which yields a
  51    *        standard pointer.
  52    *
  53    *  A _Storage_policy is required to provide 4 things:
  54    *    1) A get() API for returning the stored pointer value.
  55    *    2) An set() API for storing a pointer value.
  56    *    3) An element_type typedef to define the type this points to.
  57    *    4) An operator<() to support pointer comparison.
  58    *    5) An operator==() to support pointer comparison.
  59    */
  60   template<typename _Tp>
  61     class _Std_pointer_impl
  62     {
  63     public:
  64       // the type this pointer points to.
  65       typedef _Tp element_type;
  66
  67       // A method to fetch the pointer value as a standard T* value;
  68       inline _Tp*
  69       get() const
  70       { return _M_value; }
  71
  72       // A method to set the pointer value, from a standard T* value;
  73       inline void
  74       set(element_type* __arg)
  75       { _M_value = __arg; }
  76
  77       // Comparison of pointers
  78       inline bool
  79       operator<(const _Std_pointer_impl& __rarg) const
  80       { return (_M_value < __rarg._M_value); }
  81
  82       inline bool
  83       operator==(const _Std_pointer_impl& __rarg) const
  84       { return (_M_value == __rarg._M_value); }
  85
  86     private:
  87       element_type* _M_value;
  88     };
  89
  90   /**
  91    * @brief A storage policy for use with _Pointer_adapter<> which stores
  92    *        the pointer's address as an offset value which is relative to
  93    *        its own address.
  94    *
  95    * This is intended for pointers
  96    * within shared memory regions which might be mapped at different
  97    * addresses by different processes.  For null pointers, a value of 1 is
  98    * used.  (0 is legitimate sometimes for nodes in circularly linked lists)
  99    * This value was chosen as the least likely to generate an incorrect null,
 100    * As there is no reason why any normal pointer would point 1 byte into
 101    * its own pointer address.
 102    */
 103   template<typename _Tp>
 104     class _Relative_pointer_impl
 105     {
 106     public:
 107       typedef _Tp element_type;
 108
 109       _Tp*
 110       get() const
 111       {
 112         if (_M_diff == 1)
 113           return 0;
 114         else
 115           return reinterpret_cast<_Tp*>(reinterpret_cast<_UIntPtrType>(this)
 116                                         + _M_diff);
 117       }
 118
 119       void
 120       set(_Tp* __arg)
 121       {
 122         if (!__arg)
 123           _M_diff = 1;
 124         else
 125           _M_diff = reinterpret_cast<_UIntPtrType>(__arg)
 126                     - reinterpret_cast<_UIntPtrType>(this);
 127       }
 128
 129       // Comparison of pointers
 130       inline bool
 131       operator<(const _Relative_pointer_impl& __rarg) const
 132       { return (reinterpret_cast<_UIntPtrType>(this->get())
 133                 < reinterpret_cast<_UIntPtrType>(__rarg.get())); }
 134
 135       inline bool
 136       operator==(const _Relative_pointer_impl& __rarg) const
 137       { return (reinterpret_cast<_UIntPtrType>(this->get())
 138                 == reinterpret_cast<_UIntPtrType>(__rarg.get())); }
 139
 140     private:
 141       typedef __gnu_cxx::__conditional_type<
 142          (sizeof(unsigned long) >= sizeof(void*)),
 143          unsigned long, unsigned long long>::__type _UIntPtrType;
 144       _UIntPtrType _M_diff;
 145     };
 146
 147   /**
 148    * Relative_pointer_impl needs a specialization for const T because of
 149    * the casting done during pointer arithmetic.
 150    */
 151   template<typename _Tp>
 152     class _Relative_pointer_impl<const _Tp>
 153     {
 154     public:
 155       typedef const _Tp element_type;
 156
 157       const _Tp*
 158       get() const
 159       {
 160         if (_M_diff == 1)
 161           return 0;
 162         else
 163           return reinterpret_cast<const _Tp*>
 164               (reinterpret_cast<_UIntPtrType>(this) + _M_diff);
 165       }
 166
 167       void
 168       set(const _Tp* __arg)
 169       {
 170         if (!__arg)
 171           _M_diff = 1;
 172         else
 173           _M_diff = reinterpret_cast<_UIntPtrType>(__arg)
 174                     - reinterpret_cast<_UIntPtrType>(this);
 175       }
 176
 177       // Comparison of pointers
 178       inline bool
 179       operator<(const _Relative_pointer_impl& __rarg) const
 180       { return (reinterpret_cast<_UIntPtrType>(this->get())
 181                 < reinterpret_cast<_UIntPtrType>(__rarg.get())); }
 182
 183       inline bool
 184       operator==(const _Relative_pointer_impl& __rarg) const
 185       { return (reinterpret_cast<_UIntPtrType>(this->get())
 186                 == reinterpret_cast<_UIntPtrType>(__rarg.get())); }
 187
 188     private:
 189       typedef __gnu_cxx::__conditional_type
 190         <(sizeof(unsigned long) >= sizeof(void*)),
 191          unsigned long, unsigned long long>::__type _UIntPtrType;
 192       _UIntPtrType _M_diff;
 193     };
 194
 195   /**
 196    * The specialization on this type helps resolve the problem of
 197    * reference to void, and eliminates the need to specialize _Pointer_adapter
 198    * for cases of void*, const void*, and so on.
 199    */
 200   struct _Invalid_type { };
 201
 202   template<typename _Tp>
 203     struct _Reference_type
 204     { typedef _Tp& reference; };
 205
 206   template<>
 207     struct _Reference_type<void>
 208     { typedef _Invalid_type& reference; };
 209
 210   template<>
 211     struct _Reference_type<const void>
 212     { typedef const _Invalid_type& reference; };
 213
 214   template<>
 215     struct _Reference_type<volatile void>
 216     { typedef volatile _Invalid_type&  reference; };
 217
 218   template<>
 219     struct _Reference_type<volatile const void>
 220     { typedef const volatile _Invalid_type&  reference; };
 221
 222   /**
 223    * This structure accomodates the way in which std::iterator_traits<>
 224    * is normally specialized for const T*, so that value_type is still T.
 225    */
 226   template<typename _Tp>
 227     struct _Unqualified_type
 228     { typedef _Tp type; };
 229
 230   template<typename _Tp>
 231     struct _Unqualified_type<const _Tp>
 232     { typedef _Tp type; };
 233
 234   template<typename _Tp>
 235     struct _Unqualified_type<volatile _Tp>
 236     { typedef volatile _Tp type; };
 237
 238   template<typename _Tp>
 239     struct _Unqualified_type<volatile const _Tp>
 240     { typedef volatile _Tp type; };
 241
 242   /**
 243    * The following provides an 'alternative pointer' that works with the
 244    * containers when specified as the pointer typedef of the allocator.
 245    *
 246    * The pointer type used with the containers doesn't have to be this class,
 247    * but it must support the implicit conversions, pointer arithmetic,
 248    * comparison operators, etc. that are supported by this class, and avoid
 249    * raising compile-time ambiguities.  Because creating a working pointer can
 250    * be challenging, this pointer template was designed to wrapper an
 251    * easier storage policy type, so that it becomes reusable for creating
 252    * other pointer types.
 253    *
 254    * A key point of this class is also that it allows container writers to
 255    * 'assume' Alocator::pointer is a typedef for a normal pointer.  This class
 256    * supports most of the conventions of a true pointer, and can, for instance
 257    * handle implicit conversion to const and base class pointer types.  The
 258    * only impositions on container writers to support extended pointers are:
 259    * 1) use the Allocator::pointer typedef appropriately for pointer types.
 260    * 2) if you need pointer casting, use the __pointer_cast<> functions
 261    *    from ext/cast.h.  This allows pointer cast operations to be overloaded
 262    *    is necessary by custom pointers.
 263    *
 264    * Note:  The const qualifier works with this pointer adapter as follows:
 265    *
 266    * _Tp*             == _Pointer_adapter<_Std_pointer_impl<_Tp> >;
 267    * const _Tp*       == _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
 268    * _Tp* const       == const _Pointer_adapter<_Std_pointer_impl<_Tp> >;
 269    * const _Tp* const == const _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
 270    */
 271   template<typename _Storage_policy>
 272     class _Pointer_adapter : public _Storage_policy
 273     {
 274     public:
 275       typedef typename _Storage_policy::element_type element_type;
 276
 277       // These are needed for iterator_traits
 278       typedef std::random_access_iterator_tag                iterator_category;
 279       typedef typename _Unqualified_type<element_type>::type value_type;
 280       typedef std::ptrdiff_t                                 difference_type;
 281       typedef _Pointer_adapter                               pointer;
 282       typedef typename _Reference_type<element_type>::reference  reference;
 283
 284       // Reminder: 'const' methods mean that the method is valid when the
 285       // pointer is immutable, and has nothing to do with whether the
 286       // 'pointee' is const.
 287
 288       // Default Constructor (Convert from element_type*)
 289       _Pointer_adapter(element_type* __arg = 0)
 290       { _Storage_policy::set(__arg); }
 291
 292       // Copy constructor from _Pointer_adapter of same type.
 293       _Pointer_adapter(const _Pointer_adapter& __arg)
 294       { _Storage_policy::set(__arg.get()); }
 295
 296       // Convert from _Up* if conversion to element_type* is valid.
 297       template<typename _Up>
 298         _Pointer_adapter(_Up* __arg)
 299         { _Storage_policy::set(__arg); }
 300
 301       // Conversion from another _Pointer_adapter if _Up if static cast is
 302       // valid.
 303       template<typename _Up>
 304         _Pointer_adapter(const _Pointer_adapter<_Up>& __arg)
 305         { _Storage_policy::set(__arg.get()); }
 306
 307       // Destructor
 308       ~_Pointer_adapter() { }
 309
 310       // Assignment operator
 311       _Pointer_adapter&
 312       operator=(const _Pointer_adapter& __arg)
 313       {
 314         _Storage_policy::set(__arg.get());
 315         return *this;
 316       }
 317
 318       template<typename _Up>
 319         _Pointer_adapter&
 320         operator=(const _Pointer_adapter<_Up>& __arg)
 321         {
 322           _Storage_policy::set(__arg.get());
 323           return *this;
 324         }
 325
 326       template<typename _Up>
 327         _Pointer_adapter&
 328         operator=(_Up* __arg)
 329         {
 330           _Storage_policy::set(__arg);
 331           return *this;
 332         }
 333
 334       // Operator*, returns element_type&
 335       inline reference
 336       operator*() const
 337       { return *(_Storage_policy::get()); }
 338
 339       // Operator->, returns element_type*
 340       inline element_type*
 341       operator->() const
 342       { return _Storage_policy::get(); }
 343
 344       // Operator[], returns a element_type& to the item at that loc.
 345       inline reference
 346       operator[](std::ptrdiff_t __index) const
 347       { return _Storage_policy::get()[__index]; }
 348
 349       // To allow implicit conversion to "bool", for "if (ptr)..."
 350     private:
 351       typedef element_type*(_Pointer_adapter::*__unspecified_bool_type)() const;
 352
 353     public:
 354       operator __unspecified_bool_type() const
 355       {
 356         return _Storage_policy::get() == 0 ? 0 :
 357                          &_Pointer_adapter::operator->;
 358       }
 359
 360       // ! operator (for: if (!ptr)...)
 361       inline bool
 362       operator!() const
 363       { return (_Storage_policy::get() == 0); }
 364
 365       // Pointer differences
 366       inline friend std::ptrdiff_t
 367       operator-(const _Pointer_adapter& __lhs, element_type* __rhs)
 368       { return (__lhs.get() - __rhs); }
 369
 370       inline friend std::ptrdiff_t
 371       operator-(element_type* __lhs, const _Pointer_adapter& __rhs)
 372       { return (__lhs - __rhs.get()); }
 373
 374       template<typename _Up>
 375         inline friend std::ptrdiff_t
 376         operator-(const _Pointer_adapter& __lhs, _Up* __rhs)
 377         { return (__lhs.get() - __rhs); }
 378
 379       template<typename _Up>
 380         inline friend std::ptrdiff_t
 381         operator-(_Up* __lhs, const _Pointer_adapter& __rhs)
 382         { return (__lhs - __rhs.get()); }
 383
 384       template<typename _Up>
 385         inline std::ptrdiff_t
 386         operator-(const _Pointer_adapter<_Up>& __rhs) const
 387         { return (_Storage_policy::get() - __rhs.get()); }
 388
 389       // Pointer math
 390       // Note: There is a reason for all this overloading based on different
 391       // integer types.  In some libstdc++-v3 test cases, a templated
 392       // operator+ is declared which can match any types.  This operator
 393       // tends to "steal" the recognition of _Pointer_adapter's own operator+
 394       // unless the integer type matches perfectly.
 395
 396 #define _CXX_POINTER_ARITH_OPERATOR_SET(INT_TYPE) \
 397       inline friend _Pointer_adapter \
 398       operator+(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
 399       { return _Pointer_adapter(__lhs.get() + __offset); } \
 400 \
 401       inline friend _Pointer_adapter \
 402       operator+(INT_TYPE __offset, const _Pointer_adapter& __rhs) \
 403       { return _Pointer_adapter(__rhs.get() + __offset); } \
 404 \
 405       inline friend _Pointer_adapter \
 406       operator-(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
 407       { return _Pointer_adapter(__lhs.get() - __offset); } \
 408 \
 409       inline _Pointer_adapter& \
 410       operator+=(INT_TYPE __offset) \
 411       { \
 412         _Storage_policy::set(_Storage_policy::get() + __offset); \
 413         return *this; \
 414       } \
 415 \
 416       inline _Pointer_adapter& \
 417       operator-=(INT_TYPE __offset) \
 418       { \
 419         _Storage_policy::set(_Storage_policy::get() - __offset); \
 420         return *this; \
 421       } \
 422 // END of _CXX_POINTER_ARITH_OPERATOR_SET macro
 423
 424       // Expand into the various pointer arithmatic operators needed.
 425       _CXX_POINTER_ARITH_OPERATOR_SET(short);
 426       _CXX_POINTER_ARITH_OPERATOR_SET(unsigned short);
 427       _CXX_POINTER_ARITH_OPERATOR_SET(int);
 428       _CXX_POINTER_ARITH_OPERATOR_SET(unsigned int);
 429       _CXX_POINTER_ARITH_OPERATOR_SET(long);
 430       _CXX_POINTER_ARITH_OPERATOR_SET(unsigned long);
 431
 432       // Mathematical Manipulators
 433       inline _Pointer_adapter&
 434       operator++()
 435       {
 436         _Storage_policy::set(_Storage_policy::get() + 1);
 437         return *this;
 438       }
 439
 440       inline _Pointer_adapter
 441       operator++(int __unused)
 442       {
 443         _Pointer_adapter tmp(*this);
 444         _Storage_policy::set(_Storage_policy::get() + 1);
 445         return tmp;
 446       }
 447
 448       inline _Pointer_adapter&
 449       operator--()
 450       {
 451         _Storage_policy::set(_Storage_policy::get() - 1);
 452         return *this;
 453       }
 454
 455       inline _Pointer_adapter
 456       operator--(int)
 457       {
 458         _Pointer_adapter tmp(*this);
 459         _Storage_policy::set(_Storage_policy::get() - 1);
 460         return tmp;
 461       }
 462
 463     }; // class _Pointer_adapter
 464
 465
 466 #define _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(OPERATOR,BLANK) \
 467   template<typename _Tp1, typename _Tp2> \
 468     inline bool \
 469     operator OPERATOR##BLANK (const _Pointer_adapter<_Tp1>& __lhs, _Tp2 __rhs) \
 470     { return __lhs.get() OPERATOR##BLANK __rhs; } \
 471 \
 472   template<typename _Tp1, typename _Tp2> \
 473     inline bool \
 474     operator OPERATOR##BLANK (_Tp1 __lhs, const _Pointer_adapter<_Tp2>& __rhs) \
 475     { return __lhs OPERATOR##BLANK __rhs.get(); } \
 476 \
 477   template<typename _Tp1, typename _Tp2> \
 478     inline bool \
 479     operator OPERATOR##BLANK (const _Pointer_adapter<_Tp1>& __lhs, \
 480                               const _Pointer_adapter<_Tp2>& __rhs) \
 481     { return __lhs.get() OPERATOR##BLANK __rhs.get(); } \
 482 \
 483 // End GCC_CXX_POINTER_COMPARISON_OPERATION_SET Macro
 484
 485   // Expand into the various comparison operators needed.
 486   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(==,);
 487   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(!=,);
 488   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<,);
 489   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<=,);
 490   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>,);
 491   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>=,);
 492
 493   // These are here for expressions like "ptr == 0", "ptr != 0"
 494   template<typename _Tp>
 495     inline bool
 496     operator==(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
 497     { return __lhs.get() == reinterpret_cast<void*>(__rhs); }
 498
 499   template<typename _Tp>
 500     inline bool
 501     operator==(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
 502     { return __rhs.get() == reinterpret_cast<void*>(__lhs); }
 503
 504   template<typename _Tp>
 505     inline bool
 506     operator!=(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
 507     { return __lhs.get() != reinterpret_cast<void*>(__rhs); }
 508
 509   template<typename _Tp>
 510     inline bool
 511     operator!=(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
 512     { return __rhs.get() != reinterpret_cast<void*>(__lhs); }
 513
 514   /**
 515    * Comparison operators for _Pointer_adapter defer to the base class'es
 516    * comparison operators, when possible.
 517    */
 518   template<typename _Tp>
 519     inline bool
 520     operator==(const _Pointer_adapter<_Tp>& __lhs,
 521                const _Pointer_adapter<_Tp>& __rhs)
 522     { return __lhs._Tp::operator==(__rhs); }
 523
 524   template<typename _Tp>
 525     inline bool
 526     operator<=(const _Pointer_adapter<_Tp>& __lhs,
 527                const _Pointer_adapter<_Tp>& __rhs)
 528     { return __lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs); }
 529
 530   template<typename _Tp>
 531     inline bool
 532     operator!=(const _Pointer_adapter<_Tp>& __lhs,
 533                const _Pointer_adapter<_Tp>& __rhs)
 534     { return !(__lhs._Tp::operator==(__rhs)); }
 535
 536   template<typename _Tp>
 537     inline bool
 538     operator>(const _Pointer_adapter<_Tp>& __lhs,
 539               const _Pointer_adapter<_Tp>& __rhs)
 540     { return !(__lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs)); }
 541
 542   template<typename _Tp>
 543     inline bool
 544     operator>=(const _Pointer_adapter<_Tp>& __lhs,
 545                const _Pointer_adapter<_Tp>& __rhs)
 546     { return !(__lhs._Tp::operator<(__rhs)); }
 547
 548   template<typename _CharT, typename _Traits, typename _StoreT>
 549     inline std::basic_ostream<_CharT, _Traits>&
 550     operator<<(std::basic_ostream<_CharT, _Traits>& __os,
 551                const _Pointer_adapter<_StoreT>& __p)
 552     { return (__os << __p.get()); }
 553
 554 _GLIBCXX_END_NAMESPACE
 555
 556 #endif // _POINTER_H