libstdc++
|
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