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

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