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.
37 #pragma GCC system_header
40 #include <bits/stl_iterator_base_types.h>
42 #include <ext/type_traits.h>
44 _GLIBCXX_BEGIN_NAMESPACE(__gnu_cxx)
47 * @brief A storage policy for use with _Pointer_adapter<> which yields a
50 * A _Storage_policy is required to provide 4 things:
51 * 1) A get() API for returning the stored pointer value.
52 * 2) An set() API for storing a pointer value.
53 * 3) An element_type typedef to define the type this points to.
54 * 4) An operator<() to support pointer comparison.
55 * 5) An operator==() to support pointer comparison.
57 template<typename _Tp>
58 class _Std_pointer_impl
61 // the type this pointer points to.
62 typedef _Tp element_type;
64 // A method to fetch the pointer value as a standard T* value;
69 // A method to set the pointer value, from a standard T* value;
71 set(element_type* __arg)
74 // Comparison of pointers
76 operator<(const _Std_pointer_impl& __rarg) const
77 { return (_M_value < __rarg._M_value); }
80 operator==(const _Std_pointer_impl& __rarg) const
81 { return (_M_value == __rarg._M_value); }
84 element_type* _M_value;
88 * @brief A storage policy for use with _Pointer_adapter<> which stores
89 * the pointer's address as an offset value which is relative to
92 * This is intended for pointers within shared memory regions which
93 * might be mapped at different addresses by different processes.
94 * For null pointers, a value of 1 is used. (0 is legitimate
95 * sometimes for nodes in circularly linked lists) This value was
96 * chosen as the least likely to generate an incorrect null, As
97 * there is no reason why any normal pointer would point 1 byte into
98 * its own pointer address.
100 template<typename _Tp>
101 class _Relative_pointer_impl
104 typedef _Tp element_type;
112 return reinterpret_cast<_Tp*>(reinterpret_cast<_UIntPtrType>(this)
122 _M_diff = reinterpret_cast<_UIntPtrType>(__arg)
123 - reinterpret_cast<_UIntPtrType>(this);
126 // Comparison of pointers
128 operator<(const _Relative_pointer_impl& __rarg) const
129 { return (reinterpret_cast<_UIntPtrType>(this->get())
130 < reinterpret_cast<_UIntPtrType>(__rarg.get())); }
133 operator==(const _Relative_pointer_impl& __rarg) const
134 { return (reinterpret_cast<_UIntPtrType>(this->get())
135 == reinterpret_cast<_UIntPtrType>(__rarg.get())); }
138 #ifdef _GLIBCXX_USE_LONG_LONG
139 typedef __gnu_cxx::__conditional_type<
140 (sizeof(unsigned long) >= sizeof(void*)),
141 unsigned long, unsigned long long>::__type _UIntPtrType;
143 typedef unsigned long _UIntPtrType;
145 _UIntPtrType _M_diff;
149 * Relative_pointer_impl needs a specialization for const T because of
150 * the casting done during pointer arithmetic.
152 template<typename _Tp>
153 class _Relative_pointer_impl<const _Tp>
156 typedef const _Tp element_type;
164 return reinterpret_cast<const _Tp*>
165 (reinterpret_cast<_UIntPtrType>(this) + _M_diff);
169 set(const _Tp* __arg)
174 _M_diff = reinterpret_cast<_UIntPtrType>(__arg)
175 - reinterpret_cast<_UIntPtrType>(this);
178 // Comparison of pointers
180 operator<(const _Relative_pointer_impl& __rarg) const
181 { return (reinterpret_cast<_UIntPtrType>(this->get())
182 < reinterpret_cast<_UIntPtrType>(__rarg.get())); }
185 operator==(const _Relative_pointer_impl& __rarg) const
186 { return (reinterpret_cast<_UIntPtrType>(this->get())
187 == reinterpret_cast<_UIntPtrType>(__rarg.get())); }
190 #ifdef _GLIBCXX_USE_LONG_LONG
191 typedef __gnu_cxx::__conditional_type<
192 (sizeof(unsigned long) >= sizeof(void*)),
193 unsigned long, unsigned long long>::__type _UIntPtrType;
195 typedef unsigned long _UIntPtrType;
197 _UIntPtrType _M_diff;
201 * The specialization on this type helps resolve the problem of
202 * reference to void, and eliminates the need to specialize
203 * _Pointer_adapter for cases of void*, const void*, and so on.
205 struct _Invalid_type { };
207 template<typename _Tp>
208 struct _Reference_type
209 { typedef _Tp& reference; };
212 struct _Reference_type<void>
213 { typedef _Invalid_type& reference; };
216 struct _Reference_type<const void>
217 { typedef const _Invalid_type& reference; };
220 struct _Reference_type<volatile void>
221 { typedef volatile _Invalid_type& reference; };
224 struct _Reference_type<volatile const void>
225 { typedef const volatile _Invalid_type& reference; };
228 * This structure accomodates the way in which
229 * std::iterator_traits<> is normally specialized for const T*, so
230 * that value_type is still T.
232 template<typename _Tp>
233 struct _Unqualified_type
234 { typedef _Tp type; };
236 template<typename _Tp>
237 struct _Unqualified_type<const _Tp>
238 { typedef _Tp type; };
240 template<typename _Tp>
241 struct _Unqualified_type<volatile _Tp>
242 { typedef volatile _Tp type; };
244 template<typename _Tp>
245 struct _Unqualified_type<volatile const _Tp>
246 { typedef volatile _Tp type; };
249 * The following provides an 'alternative pointer' that works with
250 * the containers when specified as the pointer typedef of the
253 * The pointer type used with the containers doesn't have to be this
254 * class, but it must support the implicit conversions, pointer
255 * arithmetic, comparison operators, etc. that are supported by this
256 * class, and avoid raising compile-time ambiguities. Because
257 * creating a working pointer can be challenging, this pointer
258 * template was designed to wrapper an easier storage policy type,
259 * so that it becomes reusable for creating other pointer types.
261 * A key point of this class is also that it allows container
262 * writers to 'assume' Alocator::pointer is a typedef for a normal
263 * pointer. This class supports most of the conventions of a true
264 * pointer, and can, for instance handle implicit conversion to
265 * const and base class pointer types. The only impositions on
266 * container writers to support extended pointers are: 1) use the
267 * Allocator::pointer typedef appropriately for pointer types. 2)
268 * if you need pointer casting, use the __pointer_cast<> functions
269 * from ext/cast.h. This allows pointer cast operations to be
270 * overloaded is necessary by custom pointers.
272 * Note: The const qualifier works with this pointer adapter as
275 * _Tp* == _Pointer_adapter<_Std_pointer_impl<_Tp> >;
276 * const _Tp* == _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
277 * _Tp* const == const _Pointer_adapter<_Std_pointer_impl<_Tp> >;
278 * const _Tp* const == const _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
280 template<typename _Storage_policy>
281 class _Pointer_adapter : public _Storage_policy
284 typedef typename _Storage_policy::element_type element_type;
286 // These are needed for iterator_traits
287 typedef std::random_access_iterator_tag iterator_category;
288 typedef typename _Unqualified_type<element_type>::type value_type;
289 typedef std::ptrdiff_t difference_type;
290 typedef _Pointer_adapter pointer;
291 typedef typename _Reference_type<element_type>::reference reference;
293 // Reminder: 'const' methods mean that the method is valid when the
294 // pointer is immutable, and has nothing to do with whether the
295 // 'pointee' is const.
297 // Default Constructor (Convert from element_type*)
298 _Pointer_adapter(element_type* __arg = 0)
299 { _Storage_policy::set(__arg); }
301 // Copy constructor from _Pointer_adapter of same type.
302 _Pointer_adapter(const _Pointer_adapter& __arg)
303 { _Storage_policy::set(__arg.get()); }
305 // Convert from _Up* if conversion to element_type* is valid.
306 template<typename _Up>
307 _Pointer_adapter(_Up* __arg)
308 { _Storage_policy::set(__arg); }
310 // Conversion from another _Pointer_adapter if _Up if static cast is
312 template<typename _Up>
313 _Pointer_adapter(const _Pointer_adapter<_Up>& __arg)
314 { _Storage_policy::set(__arg.get()); }
317 ~_Pointer_adapter() { }
319 // Assignment operator
321 operator=(const _Pointer_adapter& __arg)
323 _Storage_policy::set(__arg.get());
327 template<typename _Up>
329 operator=(const _Pointer_adapter<_Up>& __arg)
331 _Storage_policy::set(__arg.get());
335 template<typename _Up>
337 operator=(_Up* __arg)
339 _Storage_policy::set(__arg);
343 // Operator*, returns element_type&
346 { return *(_Storage_policy::get()); }
348 // Operator->, returns element_type*
351 { return _Storage_policy::get(); }
353 // Operator[], returns a element_type& to the item at that loc.
355 operator[](std::ptrdiff_t __index) const
356 { return _Storage_policy::get()[__index]; }
358 // To allow implicit conversion to "bool", for "if (ptr)..."
360 typedef element_type*(_Pointer_adapter::*__unspecified_bool_type)() const;
363 operator __unspecified_bool_type() const
365 return _Storage_policy::get() == 0 ? 0 :
366 &_Pointer_adapter::operator->;
369 // ! operator (for: if (!ptr)...)
372 { return (_Storage_policy::get() == 0); }
374 // Pointer differences
375 inline friend std::ptrdiff_t
376 operator-(const _Pointer_adapter& __lhs, element_type* __rhs)
377 { return (__lhs.get() - __rhs); }
379 inline friend std::ptrdiff_t
380 operator-(element_type* __lhs, const _Pointer_adapter& __rhs)
381 { return (__lhs - __rhs.get()); }
383 template<typename _Up>
384 inline friend std::ptrdiff_t
385 operator-(const _Pointer_adapter& __lhs, _Up* __rhs)
386 { return (__lhs.get() - __rhs); }
388 template<typename _Up>
389 inline friend std::ptrdiff_t
390 operator-(_Up* __lhs, const _Pointer_adapter& __rhs)
391 { return (__lhs - __rhs.get()); }
393 template<typename _Up>
394 inline std::ptrdiff_t
395 operator-(const _Pointer_adapter<_Up>& __rhs) const
396 { return (_Storage_policy::get() - __rhs.get()); }
399 // Note: There is a reason for all this overloading based on different
400 // integer types. In some libstdc++-v3 test cases, a templated
401 // operator+ is declared which can match any types. This operator
402 // tends to "steal" the recognition of _Pointer_adapter's own operator+
403 // unless the integer type matches perfectly.
405 #define _CXX_POINTER_ARITH_OPERATOR_SET(INT_TYPE) \
406 inline friend _Pointer_adapter \
407 operator+(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
408 { return _Pointer_adapter(__lhs.get() + __offset); } \
410 inline friend _Pointer_adapter \
411 operator+(INT_TYPE __offset, const _Pointer_adapter& __rhs) \
412 { return _Pointer_adapter(__rhs.get() + __offset); } \
414 inline friend _Pointer_adapter \
415 operator-(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
416 { return _Pointer_adapter(__lhs.get() - __offset); } \
418 inline _Pointer_adapter& \
419 operator+=(INT_TYPE __offset) \
421 _Storage_policy::set(_Storage_policy::get() + __offset); \
425 inline _Pointer_adapter& \
426 operator-=(INT_TYPE __offset) \
428 _Storage_policy::set(_Storage_policy::get() - __offset); \
431 // END of _CXX_POINTER_ARITH_OPERATOR_SET macro
433 // Expand into the various pointer arithmatic operators needed.
434 _CXX_POINTER_ARITH_OPERATOR_SET(short);
435 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned short);
436 _CXX_POINTER_ARITH_OPERATOR_SET(int);
437 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned int);
438 _CXX_POINTER_ARITH_OPERATOR_SET(long);
439 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned long);
441 // Mathematical Manipulators
442 inline _Pointer_adapter&
445 _Storage_policy::set(_Storage_policy::get() + 1);
449 inline _Pointer_adapter
450 operator++(int __unused)
452 _Pointer_adapter tmp(*this);
453 _Storage_policy::set(_Storage_policy::get() + 1);
457 inline _Pointer_adapter&
460 _Storage_policy::set(_Storage_policy::get() - 1);
464 inline _Pointer_adapter
467 _Pointer_adapter tmp(*this);
468 _Storage_policy::set(_Storage_policy::get() - 1);
472 }; // class _Pointer_adapter
475 #define _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(OPERATOR) \
476 template<typename _Tp1, typename _Tp2> \
478 operator OPERATOR(const _Pointer_adapter<_Tp1>& __lhs, _Tp2 __rhs) \
479 { return __lhs.get() OPERATOR __rhs; } \
481 template<typename _Tp1, typename _Tp2> \
483 operator OPERATOR(_Tp1 __lhs, const _Pointer_adapter<_Tp2>& __rhs) \
484 { return __lhs OPERATOR __rhs.get(); } \
486 template<typename _Tp1, typename _Tp2> \
488 operator OPERATOR(const _Pointer_adapter<_Tp1>& __lhs, \
489 const _Pointer_adapter<_Tp2>& __rhs) \
490 { return __lhs.get() OPERATOR __rhs.get(); } \
492 // End GCC_CXX_POINTER_COMPARISON_OPERATION_SET Macro
494 // Expand into the various comparison operators needed.
495 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(==)
496 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(!=)
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(>=)
502 // These are here for expressions like "ptr == 0", "ptr != 0"
503 template<typename _Tp>
505 operator==(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
506 { return __lhs.get() == reinterpret_cast<void*>(__rhs); }
508 template<typename _Tp>
510 operator==(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
511 { return __rhs.get() == reinterpret_cast<void*>(__lhs); }
513 template<typename _Tp>
515 operator!=(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
516 { return __lhs.get() != reinterpret_cast<void*>(__rhs); }
518 template<typename _Tp>
520 operator!=(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
521 { return __rhs.get() != reinterpret_cast<void*>(__lhs); }
524 * Comparison operators for _Pointer_adapter defer to the base class'es
525 * comparison operators, when possible.
527 template<typename _Tp>
529 operator==(const _Pointer_adapter<_Tp>& __lhs,
530 const _Pointer_adapter<_Tp>& __rhs)
531 { return __lhs._Tp::operator==(__rhs); }
533 template<typename _Tp>
535 operator<=(const _Pointer_adapter<_Tp>& __lhs,
536 const _Pointer_adapter<_Tp>& __rhs)
537 { return __lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs); }
539 template<typename _Tp>
541 operator!=(const _Pointer_adapter<_Tp>& __lhs,
542 const _Pointer_adapter<_Tp>& __rhs)
543 { return !(__lhs._Tp::operator==(__rhs)); }
545 template<typename _Tp>
547 operator>(const _Pointer_adapter<_Tp>& __lhs,
548 const _Pointer_adapter<_Tp>& __rhs)
549 { return !(__lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs)); }
551 template<typename _Tp>
553 operator>=(const _Pointer_adapter<_Tp>& __lhs,
554 const _Pointer_adapter<_Tp>& __rhs)
555 { return !(__lhs._Tp::operator<(__rhs)); }
557 template<typename _CharT, typename _Traits, typename _StoreT>
558 inline std::basic_ostream<_CharT, _Traits>&
559 operator<<(std::basic_ostream<_CharT, _Traits>& __os,
560 const _Pointer_adapter<_StoreT>& __p)
561 { return (__os << __p.get()); }
563 _GLIBCXX_END_NAMESPACE