1 // Custom pointer adapter and sample storage policies
3 // Copyright (C) 2008, 2009 Free Software Foundation, Inc.
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)
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.
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.
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/>.
29 * Provides reusable _Pointer_adapter for assisting in the development of
30 * custom pointer types that can be used with the standard containers via
31 * the allocator::pointer and allocator::const_pointer typedefs.
38 #include <bits/stl_iterator_base_types.h>
40 #include <ext/type_traits.h>
42 _GLIBCXX_BEGIN_NAMESPACE(__gnu_cxx)
45 * @brief A storage policy for use with _Pointer_adapter<> which yields a
48 * A _Storage_policy is required to provide 4 things:
49 * 1) A get() API for returning the stored pointer value.
50 * 2) An set() API for storing a pointer value.
51 * 3) An element_type typedef to define the type this points to.
52 * 4) An operator<() to support pointer comparison.
53 * 5) An operator==() to support pointer comparison.
55 template<typename _Tp>
56 class _Std_pointer_impl
59 // the type this pointer points to.
60 typedef _Tp element_type;
62 // A method to fetch the pointer value as a standard T* value;
67 // A method to set the pointer value, from a standard T* value;
69 set(element_type* __arg)
72 // Comparison of pointers
74 operator<(const _Std_pointer_impl& __rarg) const
75 { return (_M_value < __rarg._M_value); }
78 operator==(const _Std_pointer_impl& __rarg) const
79 { return (_M_value == __rarg._M_value); }
82 element_type* _M_value;
86 * @brief A storage policy for use with _Pointer_adapter<> which stores
87 * the pointer's address as an offset value which is relative to
90 * This is intended for pointers
91 * within shared memory regions which might be mapped at different
92 * addresses by different processes. For null pointers, a value of 1 is
93 * used. (0 is legitimate sometimes for nodes in circularly linked lists)
94 * This value was chosen as the least likely to generate an incorrect null,
95 * As there is no reason why any normal pointer would point 1 byte into
96 * its own pointer address.
98 template<typename _Tp>
99 class _Relative_pointer_impl
102 typedef _Tp element_type;
110 return reinterpret_cast<_Tp*>(reinterpret_cast<_UIntPtrType>(this)
120 _M_diff = reinterpret_cast<_UIntPtrType>(__arg)
121 - reinterpret_cast<_UIntPtrType>(this);
124 // Comparison of pointers
126 operator<(const _Relative_pointer_impl& __rarg) const
127 { return (reinterpret_cast<_UIntPtrType>(this->get())
128 < reinterpret_cast<_UIntPtrType>(__rarg.get())); }
131 operator==(const _Relative_pointer_impl& __rarg) const
132 { return (reinterpret_cast<_UIntPtrType>(this->get())
133 == reinterpret_cast<_UIntPtrType>(__rarg.get())); }
136 typedef __gnu_cxx::__conditional_type<
137 (sizeof(unsigned long) >= sizeof(void*)),
138 unsigned long, unsigned long long>::__type _UIntPtrType;
139 _UIntPtrType _M_diff;
143 * Relative_pointer_impl needs a specialization for const T because of
144 * the casting done during pointer arithmetic.
146 template<typename _Tp>
147 class _Relative_pointer_impl<const _Tp>
150 typedef const _Tp element_type;
158 return reinterpret_cast<const _Tp*>
159 (reinterpret_cast<_UIntPtrType>(this) + _M_diff);
163 set(const _Tp* __arg)
168 _M_diff = reinterpret_cast<_UIntPtrType>(__arg)
169 - reinterpret_cast<_UIntPtrType>(this);
172 // Comparison of pointers
174 operator<(const _Relative_pointer_impl& __rarg) const
175 { return (reinterpret_cast<_UIntPtrType>(this->get())
176 < reinterpret_cast<_UIntPtrType>(__rarg.get())); }
179 operator==(const _Relative_pointer_impl& __rarg) const
180 { return (reinterpret_cast<_UIntPtrType>(this->get())
181 == reinterpret_cast<_UIntPtrType>(__rarg.get())); }
184 typedef __gnu_cxx::__conditional_type
185 <(sizeof(unsigned long) >= sizeof(void*)),
186 unsigned long, unsigned long long>::__type _UIntPtrType;
187 _UIntPtrType _M_diff;
191 * The specialization on this type helps resolve the problem of
192 * reference to void, and eliminates the need to specialize _Pointer_adapter
193 * for cases of void*, const void*, and so on.
195 struct _Invalid_type { };
197 template<typename _Tp>
198 struct _Reference_type
199 { typedef _Tp& reference; };
202 struct _Reference_type<void>
203 { typedef _Invalid_type& reference; };
206 struct _Reference_type<const void>
207 { typedef const _Invalid_type& reference; };
210 struct _Reference_type<volatile void>
211 { typedef volatile _Invalid_type& reference; };
214 struct _Reference_type<volatile const void>
215 { typedef const volatile _Invalid_type& reference; };
218 * This structure accomodates the way in which std::iterator_traits<>
219 * is normally specialized for const T*, so that value_type is still T.
221 template<typename _Tp>
222 struct _Unqualified_type
223 { typedef _Tp type; };
225 template<typename _Tp>
226 struct _Unqualified_type<const _Tp>
227 { typedef _Tp type; };
229 template<typename _Tp>
230 struct _Unqualified_type<volatile _Tp>
231 { typedef volatile _Tp type; };
233 template<typename _Tp>
234 struct _Unqualified_type<volatile const _Tp>
235 { typedef volatile _Tp type; };
238 * The following provides an 'alternative pointer' that works with the
239 * containers when specified as the pointer typedef of the allocator.
241 * The pointer type used with the containers doesn't have to be this class,
242 * but it must support the implicit conversions, pointer arithmetic,
243 * comparison operators, etc. that are supported by this class, and avoid
244 * raising compile-time ambiguities. Because creating a working pointer can
245 * be challenging, this pointer template was designed to wrapper an
246 * easier storage policy type, so that it becomes reusable for creating
247 * other pointer types.
249 * A key point of this class is also that it allows container writers to
250 * 'assume' Alocator::pointer is a typedef for a normal pointer. This class
251 * supports most of the conventions of a true pointer, and can, for instance
252 * handle implicit conversion to const and base class pointer types. The
253 * only impositions on container writers to support extended pointers are:
254 * 1) use the Allocator::pointer typedef appropriately for pointer types.
255 * 2) if you need pointer casting, use the __pointer_cast<> functions
256 * from ext/cast.h. This allows pointer cast operations to be overloaded
257 * is necessary by custom pointers.
259 * Note: The const qualifier works with this pointer adapter as follows:
261 * _Tp* == _Pointer_adapter<_Std_pointer_impl<_Tp> >;
262 * const _Tp* == _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
263 * _Tp* const == const _Pointer_adapter<_Std_pointer_impl<_Tp> >;
264 * const _Tp* const == const _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
266 template<typename _Storage_policy>
267 class _Pointer_adapter : public _Storage_policy
270 typedef typename _Storage_policy::element_type element_type;
272 // These are needed for iterator_traits
273 typedef std::random_access_iterator_tag iterator_category;
274 typedef typename _Unqualified_type<element_type>::type value_type;
275 typedef std::ptrdiff_t difference_type;
276 typedef _Pointer_adapter pointer;
277 typedef typename _Reference_type<element_type>::reference reference;
279 // Reminder: 'const' methods mean that the method is valid when the
280 // pointer is immutable, and has nothing to do with whether the
281 // 'pointee' is const.
283 // Default Constructor (Convert from element_type*)
284 _Pointer_adapter(element_type* __arg = 0)
285 { _Storage_policy::set(__arg); }
287 // Copy constructor from _Pointer_adapter of same type.
288 _Pointer_adapter(const _Pointer_adapter& __arg)
289 { _Storage_policy::set(__arg.get()); }
291 // Convert from _Up* if conversion to element_type* is valid.
292 template<typename _Up>
293 _Pointer_adapter(_Up* __arg)
294 { _Storage_policy::set(__arg); }
296 // Conversion from another _Pointer_adapter if _Up if static cast is
298 template<typename _Up>
299 _Pointer_adapter(const _Pointer_adapter<_Up>& __arg)
300 { _Storage_policy::set(__arg.get()); }
303 ~_Pointer_adapter() { }
305 // Assignment operator
307 operator=(const _Pointer_adapter& __arg)
309 _Storage_policy::set(__arg.get());
313 template<typename _Up>
315 operator=(const _Pointer_adapter<_Up>& __arg)
317 _Storage_policy::set(__arg.get());
321 template<typename _Up>
323 operator=(_Up* __arg)
325 _Storage_policy::set(__arg);
329 // Operator*, returns element_type&
332 { return *(_Storage_policy::get()); }
334 // Operator->, returns element_type*
337 { return _Storage_policy::get(); }
339 // Operator[], returns a element_type& to the item at that loc.
341 operator[](std::ptrdiff_t __index) const
342 { return _Storage_policy::get()[__index]; }
344 // To allow implicit conversion to "bool", for "if (ptr)..."
346 typedef element_type*(_Pointer_adapter::*__unspecified_bool_type)() const;
349 operator __unspecified_bool_type() const
351 return _Storage_policy::get() == 0 ? 0 :
352 &_Pointer_adapter::operator->;
355 // ! operator (for: if (!ptr)...)
358 { return (_Storage_policy::get() == 0); }
360 // Pointer differences
361 inline friend std::ptrdiff_t
362 operator-(const _Pointer_adapter& __lhs, element_type* __rhs)
363 { return (__lhs.get() - __rhs); }
365 inline friend std::ptrdiff_t
366 operator-(element_type* __lhs, const _Pointer_adapter& __rhs)
367 { return (__lhs - __rhs.get()); }
369 template<typename _Up>
370 inline friend std::ptrdiff_t
371 operator-(const _Pointer_adapter& __lhs, _Up* __rhs)
372 { return (__lhs.get() - __rhs); }
374 template<typename _Up>
375 inline friend std::ptrdiff_t
376 operator-(_Up* __lhs, const _Pointer_adapter& __rhs)
377 { return (__lhs - __rhs.get()); }
379 template<typename _Up>
380 inline std::ptrdiff_t
381 operator-(const _Pointer_adapter<_Up>& __rhs) const
382 { return (_Storage_policy::get() - __rhs.get()); }
385 // Note: There is a reason for all this overloading based on different
386 // integer types. In some libstdc++-v3 test cases, a templated
387 // operator+ is declared which can match any types. This operator
388 // tends to "steal" the recognition of _Pointer_adapter's own operator+
389 // unless the integer type matches perfectly.
391 #define _CXX_POINTER_ARITH_OPERATOR_SET(INT_TYPE) \
392 inline friend _Pointer_adapter \
393 operator+(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
394 { return _Pointer_adapter(__lhs.get() + __offset); } \
396 inline friend _Pointer_adapter \
397 operator+(INT_TYPE __offset, const _Pointer_adapter& __rhs) \
398 { return _Pointer_adapter(__rhs.get() + __offset); } \
400 inline friend _Pointer_adapter \
401 operator-(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
402 { return _Pointer_adapter(__lhs.get() - __offset); } \
404 inline _Pointer_adapter& \
405 operator+=(INT_TYPE __offset) \
407 _Storage_policy::set(_Storage_policy::get() + __offset); \
411 inline _Pointer_adapter& \
412 operator-=(INT_TYPE __offset) \
414 _Storage_policy::set(_Storage_policy::get() - __offset); \
417 // END of _CXX_POINTER_ARITH_OPERATOR_SET macro
419 // Expand into the various pointer arithmatic operators needed.
420 _CXX_POINTER_ARITH_OPERATOR_SET(short);
421 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned short);
422 _CXX_POINTER_ARITH_OPERATOR_SET(int);
423 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned int);
424 _CXX_POINTER_ARITH_OPERATOR_SET(long);
425 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned long);
427 // Mathematical Manipulators
428 inline _Pointer_adapter&
431 _Storage_policy::set(_Storage_policy::get() + 1);
435 inline _Pointer_adapter
436 operator++(int __unused)
438 _Pointer_adapter tmp(*this);
439 _Storage_policy::set(_Storage_policy::get() + 1);
443 inline _Pointer_adapter&
446 _Storage_policy::set(_Storage_policy::get() - 1);
450 inline _Pointer_adapter
453 _Pointer_adapter tmp(*this);
454 _Storage_policy::set(_Storage_policy::get() - 1);
458 }; // class _Pointer_adapter
461 #define _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(OPERATOR,BLANK) \
462 template<typename _Tp1, typename _Tp2> \
464 operator OPERATOR##BLANK (const _Pointer_adapter<_Tp1>& __lhs, _Tp2 __rhs) \
465 { return __lhs.get() OPERATOR##BLANK __rhs; } \
467 template<typename _Tp1, typename _Tp2> \
469 operator OPERATOR##BLANK (_Tp1 __lhs, const _Pointer_adapter<_Tp2>& __rhs) \
470 { return __lhs OPERATOR##BLANK __rhs.get(); } \
472 template<typename _Tp1, typename _Tp2> \
474 operator OPERATOR##BLANK (const _Pointer_adapter<_Tp1>& __lhs, \
475 const _Pointer_adapter<_Tp2>& __rhs) \
476 { return __lhs.get() OPERATOR##BLANK __rhs.get(); } \
478 // End GCC_CXX_POINTER_COMPARISON_OPERATION_SET Macro
480 // Expand into the various comparison operators needed.
481 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(==,)
482 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(!=,)
483 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<,)
484 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<=,)
485 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>,)
486 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>=,)
488 // These are here for expressions like "ptr == 0", "ptr != 0"
489 template<typename _Tp>
491 operator==(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
492 { return __lhs.get() == reinterpret_cast<void*>(__rhs); }
494 template<typename _Tp>
496 operator==(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
497 { return __rhs.get() == reinterpret_cast<void*>(__lhs); }
499 template<typename _Tp>
501 operator!=(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
502 { return __lhs.get() != reinterpret_cast<void*>(__rhs); }
504 template<typename _Tp>
506 operator!=(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
507 { return __rhs.get() != reinterpret_cast<void*>(__lhs); }
510 * Comparison operators for _Pointer_adapter defer to the base class'es
511 * comparison operators, when possible.
513 template<typename _Tp>
515 operator==(const _Pointer_adapter<_Tp>& __lhs,
516 const _Pointer_adapter<_Tp>& __rhs)
517 { return __lhs._Tp::operator==(__rhs); }
519 template<typename _Tp>
521 operator<=(const _Pointer_adapter<_Tp>& __lhs,
522 const _Pointer_adapter<_Tp>& __rhs)
523 { return __lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs); }
525 template<typename _Tp>
527 operator!=(const _Pointer_adapter<_Tp>& __lhs,
528 const _Pointer_adapter<_Tp>& __rhs)
529 { return !(__lhs._Tp::operator==(__rhs)); }
531 template<typename _Tp>
533 operator>(const _Pointer_adapter<_Tp>& __lhs,
534 const _Pointer_adapter<_Tp>& __rhs)
535 { return !(__lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs)); }
537 template<typename _Tp>
539 operator>=(const _Pointer_adapter<_Tp>& __lhs,
540 const _Pointer_adapter<_Tp>& __rhs)
541 { return !(__lhs._Tp::operator<(__rhs)); }
543 template<typename _CharT, typename _Traits, typename _StoreT>
544 inline std::basic_ostream<_CharT, _Traits>&
545 operator<<(std::basic_ostream<_CharT, _Traits>& __os,
546 const _Pointer_adapter<_StoreT>& __p)
547 { return (__os << __p.get()); }
549 _GLIBCXX_END_NAMESPACE