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
  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
  95    * within shared memory regions which might be mapped at different
  96    * addresses by different processes.  For null pointers, a value of 1 is
  97    * used.  (0 is legitimate sometimes for nodes in circularly linked lists)
  98    * This value was chosen as the least likely to generate an incorrect null,
  99    * As 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*>(
 115                  const_cast<char*>(reinterpret_cast<const char*>(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<char*>(__arg)
 126                     - reinterpret_cast<char*>(this);
 127       }
 128
 129       // Comparison of pointers
 130       inline bool
 131       operator<(const _Relative_pointer_impl& __rarg) const
 132       { return (this->get() < __rarg.get()); }
 133
 134       inline bool
 135       operator==(const _Relative_pointer_impl& __rarg) const
 136       { return (this->get() == __rarg.get()); }
 137
 138     private:
 139       std::ptrdiff_t _M_diff;
 140     };
 141
 142   /**
 143    * Relative_pointer_impl needs a specialization for const T because of
 144    * the casting done during pointer arithmetic.
 145    */
 146   template<typename _Tp>
 147     class _Relative_pointer_impl<const _Tp>
 148     {
 149     public:
 150       typedef const _Tp element_type;
 151
 152       const _Tp*
 153       get() const
 154       {
 155         if (_M_diff == 1)
 156           return 0;
 157         else
 158           return reinterpret_cast<const _Tp*>(
 159                   (reinterpret_cast<const char*>(this)) + _M_diff);
 160       }
 161
 162       void
 163       set(const _Tp* __arg)
 164       {
 165         if (!__arg)
 166           _M_diff = 1;
 167         else
 168           _M_diff = reinterpret_cast<const char*>(__arg)
 169                     - reinterpret_cast<const char*>(this);
 170       }
 171
 172       // Comparison of pointers
 173       inline bool
 174       operator<(const _Relative_pointer_impl& __rarg) const
 175       { return (this->get() < __rarg.get()); }
 176
 177       inline bool
 178       operator==(const _Relative_pointer_impl& __rarg) const
 179       { return (this->get() == __rarg.get()); }
 180
 181     private:
 182       std::ptrdiff_t _M_diff;
 183     };
 184
 185   /**
 186    * The specialization on this type helps resolve the problem of
 187    * reference to void, and eliminates the need to specialize _Pointer_adapter
 188    * for cases of void*, const void*, and so on.
 189    */
 190   struct _Invalid_type { };
 191
 192   template<typename _Tp>
 193     struct _Reference_type
 194     { typedef _Tp& reference; };
 195
 196   template<>
 197     struct _Reference_type<void>
 198     { typedef _Invalid_type& reference; };
 199
 200   template<>
 201     struct _Reference_type<const void>
 202     { typedef const _Invalid_type& reference; };
 203
 204   template<>
 205     struct _Reference_type<volatile void>
 206     { typedef volatile _Invalid_type&  reference; };
 207
 208   template<>
 209     struct _Reference_type<volatile const void>
 210     { typedef const volatile _Invalid_type&  reference; };
 211
 212   /**
 213    * This structure accomodates the way in which std::iterator_traits<>
 214    * is normally specialized for const T*, so that value_type is still T.
 215    */
 216   template<typename _Tp>
 217     struct _Unqualified_type
 218     { typedef _Tp type; };
 219
 220   template<typename _Tp>
 221     struct _Unqualified_type<const _Tp>
 222     { typedef _Tp type; };
 223
 224   template<typename _Tp>
 225     struct _Unqualified_type<volatile _Tp>
 226     { typedef volatile _Tp type; };
 227
 228   template<typename _Tp>
 229     struct _Unqualified_type<volatile const _Tp>
 230     { typedef volatile _Tp type; };
 231
 232   /**
 233    * The following provides an 'alternative pointer' that works with the
 234    * containers when specified as the pointer typedef of the allocator.
 235    *
 236    * The pointer type used with the containers doesn't have to be this class,
 237    * but it must support the implicit conversions, pointer arithmetic,
 238    * comparison operators, etc. that are supported by this class, and avoid
 239    * raising compile-time ambiguities.  Because creating a working pointer can
 240    * be challenging, this pointer template was designed to wrapper an
 241    * easier storage policy type, so that it becomes reusable for creating
 242    * other pointer types.
 243    *
 244    * A key point of this class is also that it allows container writers to
 245    * 'assume' Alocator::pointer is a typedef for a normal pointer.  This class
 246    * supports most of the conventions of a true pointer, and can, for instance
 247    * handle implicit conversion to const and base class pointer types.  The
 248    * only impositions on container writers to support extended pointers are:
 249    * 1) use the Allocator::pointer typedef appropriately for pointer types.
 250    * 2) if you need pointer casting, use the __pointer_cast<> functions
 251    *    from ext/cast.h.  This allows pointer cast operations to be overloaded
 252    *    is necessary by custom pointers.
 253    *
 254    * Note:  The const qualifier works with this pointer adapter as follows:
 255    *
 256    * _Tp*             == _Pointer_adapter<_Std_pointer_impl<_Tp> >;
 257    * const _Tp*       == _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
 258    * _Tp* const       == const _Pointer_adapter<_Std_pointer_impl<_Tp> >;
 259    * const _Tp* const == const _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
 260    */
 261   template<typename _Storage_policy>
 262     class _Pointer_adapter : public _Storage_policy
 263     {
 264     public:
 265       typedef typename _Storage_policy::element_type element_type;
 266
 267       // These are needed for iterator_traits
 268       typedef std::random_access_iterator_tag                iterator_category;
 269       typedef typename _Unqualified_type<element_type>::type value_type;
 270       typedef std::ptrdiff_t                                 difference_type;
 271       typedef _Pointer_adapter                               pointer;
 272       typedef typename _Reference_type<element_type>::reference  reference;
 273
 274       // Reminder: 'const' methods mean that the method is valid when the
 275       // pointer is immutable, and has nothing to do with whether the
 276       // 'pointee' is const.
 277
 278       // Default Constructor (Convert from element_type*)
 279       _Pointer_adapter(element_type* __arg = 0)
 280       { _Storage_policy::set(__arg); }
 281
 282       // Copy constructor from _Pointer_adapter of same type.
 283       _Pointer_adapter(const _Pointer_adapter& __arg)
 284       { _Storage_policy::set(__arg.get()); }
 285
 286       // Convert from _Up* if conversion to element_type* is valid.
 287       template<typename _Up>
 288         _Pointer_adapter(_Up* __arg)
 289         { _Storage_policy::set(__arg); }
 290
 291       // Conversion from another _Pointer_adapter if _Up if static cast is
 292       // valid.
 293       template<typename _Up>
 294         _Pointer_adapter(const _Pointer_adapter<_Up>& __arg)
 295         { _Storage_policy::set(__arg.get()); }
 296
 297       // Destructor
 298       ~_Pointer_adapter() { }
 299
 300       // Assignment operator
 301       _Pointer_adapter&
 302       operator=(const _Pointer_adapter& __arg)
 303       {
 304         _Storage_policy::set(__arg.get());
 305         return *this;
 306       }
 307
 308       template<typename _Up>
 309         _Pointer_adapter&
 310         operator=(const _Pointer_adapter<_Up>& __arg)
 311         {
 312           _Storage_policy::set(__arg.get());
 313           return *this;
 314         }
 315
 316       template<typename _Up>
 317         _Pointer_adapter&
 318         operator=(_Up* __arg)
 319         {
 320           _Storage_policy::set(__arg);
 321           return *this;
 322         }
 323
 324       // Operator*, returns element_type&
 325       inline reference
 326       operator*() const
 327       { return *(_Storage_policy::get()); }
 328
 329       // Operator->, returns element_type*
 330       inline element_type*
 331       operator->() const
 332       { return _Storage_policy::get(); }
 333
 334       // Operator[], returns a element_type& to the item at that loc.
 335       inline reference
 336       operator[](std::ptrdiff_t __index) const
 337       { return _Storage_policy::get()[__index]; }
 338
 339       // To allow implicit conversion to "bool", for "if (ptr)..."
 340     private:
 341       typedef element_type*(_Pointer_adapter::*__unspecified_bool_type)() const;
 342
 343     public:
 344       operator __unspecified_bool_type() const
 345       {
 346         return _Storage_policy::get() == 0 ? 0 :
 347                          &_Pointer_adapter::operator->;
 348       }
 349
 350       // ! operator (for: if (!ptr)...)
 351       inline bool
 352       operator!() const
 353       { return (_Storage_policy::get() == 0); }
 354
 355       // Pointer differences
 356       inline friend std::ptrdiff_t
 357       operator-(const _Pointer_adapter& __lhs, element_type* __rhs)
 358       { return (__lhs.get() - __rhs); }
 359
 360       inline friend std::ptrdiff_t
 361       operator-(element_type* __lhs, const _Pointer_adapter& __rhs)
 362       { return (__lhs - __rhs.get()); }
 363
 364       template<typename _Up>
 365         inline friend std::ptrdiff_t
 366         operator-(const _Pointer_adapter& __lhs, _Up* __rhs)
 367         { return (__lhs.get() - __rhs); }
 368
 369       template<typename _Up>
 370         inline friend std::ptrdiff_t
 371         operator-(_Up* __lhs, const _Pointer_adapter& __rhs)
 372         { return (__lhs - __rhs.get()); }
 373
 374       template<typename _Up>
 375         inline std::ptrdiff_t
 376         operator-(const _Pointer_adapter<_Up>& __rhs) const
 377         { return (_Storage_policy::get() - __rhs.get()); }
 378
 379       // Pointer math
 380       // Note: There is a reason for all this overloading based on different
 381       // integer types.  In some libstdc++-v3 test cases, a templated
 382       // operator+ is declared which can match any types.  This operator
 383       // tends to "steal" the recognition of _Pointer_adapter's own operator+
 384       // unless the integer type matches perfectly.
 385
 386 #define _CXX_POINTER_ARITH_OPERATOR_SET(INT_TYPE) \
 387       inline friend _Pointer_adapter \
 388       operator+(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
 389       { return _Pointer_adapter(__lhs.get() + __offset); } \
 390 \
 391       inline friend _Pointer_adapter \
 392       operator+(INT_TYPE __offset, const _Pointer_adapter& __rhs) \
 393       { return _Pointer_adapter(__rhs.get() + __offset); } \
 394 \
 395       inline friend _Pointer_adapter \
 396       operator-(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
 397       { return _Pointer_adapter(__lhs.get() - __offset); } \
 398 \
 399       inline _Pointer_adapter& \
 400       operator+=(INT_TYPE __offset) \
 401       { \
 402         _Storage_policy::set(_Storage_policy::get() + __offset); \
 403         return *this; \
 404       } \
 405 \
 406       inline _Pointer_adapter& \
 407       operator-=(INT_TYPE __offset) \
 408       { \
 409         _Storage_policy::set(_Storage_policy::get() - __offset); \
 410         return *this; \
 411       } \
 412 // END of _CXX_POINTER_ARITH_OPERATOR_SET macro
 413
 414       // Expand into the various pointer arithmatic operators needed.
 415       _CXX_POINTER_ARITH_OPERATOR_SET(short);
 416       _CXX_POINTER_ARITH_OPERATOR_SET(unsigned short);
 417       _CXX_POINTER_ARITH_OPERATOR_SET(int);
 418       _CXX_POINTER_ARITH_OPERATOR_SET(unsigned int);
 419       _CXX_POINTER_ARITH_OPERATOR_SET(long);
 420       _CXX_POINTER_ARITH_OPERATOR_SET(unsigned long);
 421
 422       // Mathematical Manipulators
 423       inline _Pointer_adapter&
 424       operator++()
 425       {
 426         _Storage_policy::set(_Storage_policy::get() + 1);
 427         return *this;
 428       }
 429
 430       inline _Pointer_adapter
 431       operator++(int __unused)
 432       {
 433         _Pointer_adapter tmp(*this);
 434         _Storage_policy::set(_Storage_policy::get() + 1);
 435         return tmp;
 436       }
 437
 438       inline _Pointer_adapter&
 439       operator--()
 440       {
 441         _Storage_policy::set(_Storage_policy::get() - 1);
 442         return *this;
 443       }
 444
 445       inline _Pointer_adapter
 446       operator--(int)
 447       {
 448         _Pointer_adapter tmp(*this);
 449         _Storage_policy::set(_Storage_policy::get() - 1);
 450         return tmp;
 451       }
 452
 453     }; // class _Pointer_adapter
 454
 455
 456 #define _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(OPERATOR,BLANK) \
 457   template<typename _Tp1, typename _Tp2> \
 458     inline bool \
 459     operator OPERATOR##BLANK (const _Pointer_adapter<_Tp1>& __lhs, _Tp2 __rhs) \
 460     { return __lhs.get() OPERATOR##BLANK __rhs; } \
 461 \
 462   template<typename _Tp1, typename _Tp2> \
 463     inline bool \
 464     operator OPERATOR##BLANK (_Tp1 __lhs, const _Pointer_adapter<_Tp2>& __rhs) \
 465     { return __lhs OPERATOR##BLANK __rhs.get(); } \
 466 \
 467   template<typename _Tp1, typename _Tp2> \
 468     inline bool \
 469     operator OPERATOR##BLANK (const _Pointer_adapter<_Tp1>& __lhs, \
 470                               const _Pointer_adapter<_Tp2>& __rhs) \
 471     { return __lhs.get() OPERATOR##BLANK __rhs.get(); } \
 472 \
 473 // End GCC_CXX_POINTER_COMPARISON_OPERATION_SET Macro
 474
 475   // Expand into the various comparison operators needed.
 476   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(==,);
 477   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(!=,);
 478   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<,);
 479   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<=,);
 480   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>,);
 481   _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>=,);
 482
 483   // These are here for expressions like "ptr == 0", "ptr != 0"
 484   template<typename _Tp>
 485     inline bool
 486     operator==(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
 487     { return __lhs.get() == reinterpret_cast<void*>(__rhs); }
 488
 489   template<typename _Tp>
 490     inline bool
 491     operator==(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
 492     { return __rhs.get() == reinterpret_cast<void*>(__lhs); }
 493
 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   /**
 505    * Comparison operators for _Pointer_adapter defer to the base class'es
 506    * comparison operators, when possible.
 507    */
 508   template<typename _Tp>
 509     inline bool
 510     operator==(const _Pointer_adapter<_Tp>& __lhs,
 511                const _Pointer_adapter<_Tp>& __rhs)
 512     { return __lhs._Tp::operator==(__rhs); }
 513
 514   template<typename _Tp>
 515     inline bool
 516     operator<=(const _Pointer_adapter<_Tp>& __lhs,
 517                const _Pointer_adapter<_Tp>& __rhs)
 518     { return __lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs); }
 519
 520   template<typename _Tp>
 521     inline bool
 522     operator!=(const _Pointer_adapter<_Tp>& __lhs,
 523                const _Pointer_adapter<_Tp>& __rhs)
 524     { return !(__lhs._Tp::operator==(__rhs)); }
 525
 526   template<typename _Tp>
 527     inline bool
 528     operator>(const _Pointer_adapter<_Tp>& __lhs,
 529               const _Pointer_adapter<_Tp>& __rhs)
 530     { return !(__lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs)); }
 531
 532   template<typename _Tp>
 533     inline bool
 534     operator>=(const _Pointer_adapter<_Tp>& __lhs,
 535                const _Pointer_adapter<_Tp>& __rhs)
 536     { return !(__lhs._Tp::operator<(__rhs)); }
 537
 538   template<typename _CharT, typename _Traits, typename _StoreT>
 539     inline std::basic_ostream<_CharT, _Traits>&
 540     operator<<(std::basic_ostream<_CharT, _Traits>& __os,
 541                const _Pointer_adapter<_StoreT>& __p)
 542     { return (__os << __p.get()); }
 543
 544 _GLIBCXX_END_NAMESPACE
 545
 546 #endif // _POINTER_H