1 // Custom pointer adapter and sample storage policies
3 // Copyright (C) 2008, 2009, 2010 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/>.
27 * This file is a GNU extension to the Standard C++ Library.
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.
39 #pragma GCC system_header
42 #include <bits/stl_iterator_base_types.h>
44 #include <ext/type_traits.h>
46 namespace __gnu_cxx
_GLIBCXX_VISIBILITY(default)
48 _GLIBCXX_BEGIN_NAMESPACE_VERSION
51 * @brief A storage policy for use with _Pointer_adapter<> which yields a
54 * A _Storage_policy is required to provide 4 things:
55 * 1) A get() API for returning the stored pointer value.
56 * 2) An set() API for storing a pointer value.
57 * 3) An element_type typedef to define the type this points to.
58 * 4) An operator<() to support pointer comparison.
59 * 5) An operator==() to support pointer comparison.
61 template<typename _Tp
>
62 class _Std_pointer_impl
65 // the type this pointer points to.
66 typedef _Tp element_type
;
68 // A method to fetch the pointer value as a standard T* value;
73 // A method to set the pointer value, from a standard T* value;
75 set(element_type
* __arg
)
78 // Comparison of pointers
80 operator<(const _Std_pointer_impl
& __rarg
) const
81 { return (_M_value
< __rarg
._M_value
); }
84 operator==(const _Std_pointer_impl
& __rarg
) const
85 { return (_M_value
== __rarg
._M_value
); }
88 element_type
* _M_value
;
92 * @brief A storage policy for use with _Pointer_adapter<> which stores
93 * the pointer's address as an offset value which is relative to
96 * This is intended for pointers within shared memory regions which
97 * might be mapped at different addresses by different processes.
98 * For null pointers, a value of 1 is used. (0 is legitimate
99 * sometimes for nodes in circularly linked lists) This value was
100 * chosen as the least likely to generate an incorrect null, As
101 * there is no reason why any normal pointer would point 1 byte into
102 * its own pointer address.
104 template<typename _Tp
>
105 class _Relative_pointer_impl
108 typedef _Tp element_type
;
116 return reinterpret_cast<_Tp
*>(reinterpret_cast<_UIntPtrType
>(this)
126 _M_diff
= reinterpret_cast<_UIntPtrType
>(__arg
)
127 - reinterpret_cast<_UIntPtrType
>(this);
130 // Comparison of pointers
132 operator<(const _Relative_pointer_impl
& __rarg
) const
133 { return (reinterpret_cast<_UIntPtrType
>(this->get())
134 < reinterpret_cast<_UIntPtrType
>(__rarg
.get())); }
137 operator==(const _Relative_pointer_impl
& __rarg
) const
138 { return (reinterpret_cast<_UIntPtrType
>(this->get())
139 == reinterpret_cast<_UIntPtrType
>(__rarg
.get())); }
142 #ifdef _GLIBCXX_USE_LONG_LONG
143 typedef __gnu_cxx::__conditional_type
<
144 (sizeof(unsigned long) >= sizeof(void*)),
145 unsigned long, unsigned long long>::__type _UIntPtrType
;
147 typedef unsigned long _UIntPtrType
;
149 _UIntPtrType _M_diff
;
153 * Relative_pointer_impl needs a specialization for const T because of
154 * the casting done during pointer arithmetic.
156 template<typename _Tp
>
157 class _Relative_pointer_impl
<const _Tp
>
160 typedef const _Tp element_type
;
168 return reinterpret_cast<const _Tp
*>
169 (reinterpret_cast<_UIntPtrType
>(this) + _M_diff
);
173 set(const _Tp
* __arg
)
178 _M_diff
= reinterpret_cast<_UIntPtrType
>(__arg
)
179 - reinterpret_cast<_UIntPtrType
>(this);
182 // Comparison of pointers
184 operator<(const _Relative_pointer_impl
& __rarg
) const
185 { return (reinterpret_cast<_UIntPtrType
>(this->get())
186 < reinterpret_cast<_UIntPtrType
>(__rarg
.get())); }
189 operator==(const _Relative_pointer_impl
& __rarg
) const
190 { return (reinterpret_cast<_UIntPtrType
>(this->get())
191 == reinterpret_cast<_UIntPtrType
>(__rarg
.get())); }
194 #ifdef _GLIBCXX_USE_LONG_LONG
195 typedef __gnu_cxx::__conditional_type
<
196 (sizeof(unsigned long) >= sizeof(void*)),
197 unsigned long, unsigned long long>::__type _UIntPtrType
;
199 typedef unsigned long _UIntPtrType
;
201 _UIntPtrType _M_diff
;
205 * The specialization on this type helps resolve the problem of
206 * reference to void, and eliminates the need to specialize
207 * _Pointer_adapter for cases of void*, const void*, and so on.
209 struct _Invalid_type
{ };
211 template<typename _Tp
>
212 struct _Reference_type
213 { typedef _Tp
& reference
; };
216 struct _Reference_type
<void>
217 { typedef _Invalid_type
& reference
; };
220 struct _Reference_type
<const void>
221 { typedef const _Invalid_type
& reference
; };
224 struct _Reference_type
<volatile void>
225 { typedef volatile _Invalid_type
& reference
; };
228 struct _Reference_type
<volatile const void>
229 { typedef const volatile _Invalid_type
& reference
; };
232 * This structure accomodates the way in which
233 * std::iterator_traits<> is normally specialized for const T*, so
234 * that value_type is still T.
236 template<typename _Tp
>
237 struct _Unqualified_type
238 { typedef _Tp type
; };
240 template<typename _Tp
>
241 struct _Unqualified_type
<const _Tp
>
242 { typedef _Tp type
; };
244 template<typename _Tp
>
245 struct _Unqualified_type
<volatile _Tp
>
246 { typedef volatile _Tp type
; };
248 template<typename _Tp
>
249 struct _Unqualified_type
<volatile const _Tp
>
250 { typedef volatile _Tp type
; };
253 * The following provides an 'alternative pointer' that works with
254 * the containers when specified as the pointer typedef of the
257 * The pointer type used with the containers doesn't have to be this
258 * class, but it must support the implicit conversions, pointer
259 * arithmetic, comparison operators, etc. that are supported by this
260 * class, and avoid raising compile-time ambiguities. Because
261 * creating a working pointer can be challenging, this pointer
262 * template was designed to wrapper an easier storage policy type,
263 * so that it becomes reusable for creating other pointer types.
265 * A key point of this class is also that it allows container
266 * writers to 'assume' Alocator::pointer is a typedef for a normal
267 * pointer. This class supports most of the conventions of a true
268 * pointer, and can, for instance handle implicit conversion to
269 * const and base class pointer types. The only impositions on
270 * container writers to support extended pointers are: 1) use the
271 * Allocator::pointer typedef appropriately for pointer types. 2)
272 * if you need pointer casting, use the __pointer_cast<> functions
273 * from ext/cast.h. This allows pointer cast operations to be
274 * overloaded is necessary by custom pointers.
276 * Note: The const qualifier works with this pointer adapter as
279 * _Tp* == _Pointer_adapter<_Std_pointer_impl<_Tp> >;
280 * const _Tp* == _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
281 * _Tp* const == const _Pointer_adapter<_Std_pointer_impl<_Tp> >;
282 * const _Tp* const == const _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
284 template<typename _Storage_policy
>
285 class _Pointer_adapter
: public _Storage_policy
288 typedef typename
_Storage_policy::element_type element_type
;
290 // These are needed for iterator_traits
291 typedef std::random_access_iterator_tag iterator_category
;
292 typedef typename _Unqualified_type
<element_type
>::type value_type
;
293 typedef std::ptrdiff_t difference_type
;
294 typedef _Pointer_adapter pointer
;
295 typedef typename _Reference_type
<element_type
>::reference reference
;
297 // Reminder: 'const' methods mean that the method is valid when the
298 // pointer is immutable, and has nothing to do with whether the
299 // 'pointee' is const.
301 // Default Constructor (Convert from element_type*)
302 _Pointer_adapter(element_type
* __arg
= 0)
303 { _Storage_policy::set(__arg
); }
305 // Copy constructor from _Pointer_adapter of same type.
306 _Pointer_adapter(const _Pointer_adapter
& __arg
)
307 { _Storage_policy::set(__arg
.get()); }
309 // Convert from _Up* if conversion to element_type* is valid.
310 template<typename _Up
>
311 _Pointer_adapter(_Up
* __arg
)
312 { _Storage_policy::set(__arg
); }
314 // Conversion from another _Pointer_adapter if _Up if static cast is
316 template<typename _Up
>
317 _Pointer_adapter(const _Pointer_adapter
<_Up
>& __arg
)
318 { _Storage_policy::set(__arg
.get()); }
321 ~_Pointer_adapter() { }
323 // Assignment operator
325 operator=(const _Pointer_adapter
& __arg
)
327 _Storage_policy::set(__arg
.get());
331 template<typename _Up
>
333 operator=(const _Pointer_adapter
<_Up
>& __arg
)
335 _Storage_policy::set(__arg
.get());
339 template<typename _Up
>
341 operator=(_Up
* __arg
)
343 _Storage_policy::set(__arg
);
347 // Operator*, returns element_type&
350 { return *(_Storage_policy::get()); }
352 // Operator->, returns element_type*
355 { return _Storage_policy::get(); }
357 // Operator[], returns a element_type& to the item at that loc.
359 operator[](std::ptrdiff_t __index
) const
360 { return _Storage_policy::get()[__index
]; }
362 // To allow implicit conversion to "bool", for "if (ptr)..."
364 typedef element_type
*(_Pointer_adapter::*__unspecified_bool_type
)() const;
367 operator __unspecified_bool_type() const
369 return _Storage_policy::get() == 0 ? 0 :
370 &_Pointer_adapter::operator->;
373 // ! operator (for: if (!ptr)...)
376 { return (_Storage_policy::get() == 0); }
378 // Pointer differences
379 inline friend std::ptrdiff_t
380 operator-(const _Pointer_adapter
& __lhs
, element_type
* __rhs
)
381 { return (__lhs
.get() - __rhs
); }
383 inline friend std::ptrdiff_t
384 operator-(element_type
* __lhs
, const _Pointer_adapter
& __rhs
)
385 { return (__lhs
- __rhs
.get()); }
387 template<typename _Up
>
388 inline friend std::ptrdiff_t
389 operator-(const _Pointer_adapter
& __lhs
, _Up
* __rhs
)
390 { return (__lhs
.get() - __rhs
); }
392 template<typename _Up
>
393 inline friend std::ptrdiff_t
394 operator-(_Up
* __lhs
, const _Pointer_adapter
& __rhs
)
395 { return (__lhs
- __rhs
.get()); }
397 template<typename _Up
>
398 inline std::ptrdiff_t
399 operator-(const _Pointer_adapter
<_Up
>& __rhs
) const
400 { return (_Storage_policy::get() - __rhs
.get()); }
403 // Note: There is a reason for all this overloading based on different
404 // integer types. In some libstdc++-v3 test cases, a templated
405 // operator+ is declared which can match any types. This operator
406 // tends to "steal" the recognition of _Pointer_adapter's own operator+
407 // unless the integer type matches perfectly.
409 #define _CXX_POINTER_ARITH_OPERATOR_SET(INT_TYPE) \
410 inline friend _Pointer_adapter \
411 operator+(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
412 { return _Pointer_adapter(__lhs.get() + __offset); } \
414 inline friend _Pointer_adapter \
415 operator+(INT_TYPE __offset, const _Pointer_adapter& __rhs) \
416 { return _Pointer_adapter(__rhs.get() + __offset); } \
418 inline friend _Pointer_adapter \
419 operator-(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
420 { return _Pointer_adapter(__lhs.get() - __offset); } \
422 inline _Pointer_adapter& \
423 operator+=(INT_TYPE __offset) \
425 _Storage_policy::set(_Storage_policy::get() + __offset); \
429 inline _Pointer_adapter& \
430 operator-=(INT_TYPE __offset) \
432 _Storage_policy::set(_Storage_policy::get() - __offset); \
435 // END of _CXX_POINTER_ARITH_OPERATOR_SET macro
437 // Expand into the various pointer arithmatic operators needed.
438 _CXX_POINTER_ARITH_OPERATOR_SET(short);
439 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned short);
440 _CXX_POINTER_ARITH_OPERATOR_SET(int);
441 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned int);
442 _CXX_POINTER_ARITH_OPERATOR_SET(long);
443 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned long);
445 // Mathematical Manipulators
446 inline _Pointer_adapter
&
449 _Storage_policy::set(_Storage_policy::get() + 1);
453 inline _Pointer_adapter
456 _Pointer_adapter
tmp(*this);
457 _Storage_policy::set(_Storage_policy::get() + 1);
461 inline _Pointer_adapter
&
464 _Storage_policy::set(_Storage_policy::get() - 1);
468 inline _Pointer_adapter
471 _Pointer_adapter
tmp(*this);
472 _Storage_policy::set(_Storage_policy::get() - 1);
476 }; // class _Pointer_adapter
479 #define _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(OPERATOR) \
480 template<typename _Tp1, typename _Tp2> \
482 operator OPERATOR(const _Pointer_adapter<_Tp1>& __lhs, _Tp2 __rhs) \
483 { return __lhs.get() OPERATOR __rhs; } \
485 template<typename _Tp1, typename _Tp2> \
487 operator OPERATOR(_Tp1 __lhs, const _Pointer_adapter<_Tp2>& __rhs) \
488 { return __lhs OPERATOR __rhs.get(); } \
490 template<typename _Tp1, typename _Tp2> \
492 operator OPERATOR(const _Pointer_adapter<_Tp1>& __lhs, \
493 const _Pointer_adapter<_Tp2>& __rhs) \
494 { return __lhs.get() OPERATOR __rhs.get(); } \
496 // End GCC_CXX_POINTER_COMPARISON_OPERATION_SET Macro
498 // Expand into the various comparison operators needed.
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 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>)
504 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>=)
506 // These are here for expressions like "ptr == 0", "ptr != 0"
507 template<typename _Tp
>
509 operator==(const _Pointer_adapter
<_Tp
>& __lhs
, int __rhs
)
510 { return __lhs
.get() == reinterpret_cast<void*>(__rhs
); }
512 template<typename _Tp
>
514 operator==(int __lhs
, const _Pointer_adapter
<_Tp
>& __rhs
)
515 { return __rhs
.get() == reinterpret_cast<void*>(__lhs
); }
517 template<typename _Tp
>
519 operator!=(const _Pointer_adapter
<_Tp
>& __lhs
, int __rhs
)
520 { return __lhs
.get() != reinterpret_cast<void*>(__rhs
); }
522 template<typename _Tp
>
524 operator!=(int __lhs
, const _Pointer_adapter
<_Tp
>& __rhs
)
525 { return __rhs
.get() != reinterpret_cast<void*>(__lhs
); }
528 * Comparison operators for _Pointer_adapter defer to the base class'es
529 * comparison operators, when possible.
531 template<typename _Tp
>
533 operator==(const _Pointer_adapter
<_Tp
>& __lhs
,
534 const _Pointer_adapter
<_Tp
>& __rhs
)
535 { return __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
) || __lhs
._Tp::operator==(__rhs
); }
543 template<typename _Tp
>
545 operator!=(const _Pointer_adapter
<_Tp
>& __lhs
,
546 const _Pointer_adapter
<_Tp
>& __rhs
)
547 { return !(__lhs
._Tp::operator==(__rhs
)); }
549 template<typename _Tp
>
551 operator>(const _Pointer_adapter
<_Tp
>& __lhs
,
552 const _Pointer_adapter
<_Tp
>& __rhs
)
553 { return !(__lhs
._Tp::operator<(__rhs
) || __lhs
._Tp::operator==(__rhs
)); }
555 template<typename _Tp
>
557 operator>=(const _Pointer_adapter
<_Tp
>& __lhs
,
558 const _Pointer_adapter
<_Tp
>& __rhs
)
559 { return !(__lhs
._Tp::operator<(__rhs
)); }
561 template<typename _CharT
, typename _Traits
, typename _StoreT
>
562 inline std::basic_ostream
<_CharT
, _Traits
>&
563 operator<<(std::basic_ostream
<_CharT
, _Traits
>& __os
,
564 const _Pointer_adapter
<_StoreT
>& __p
)
565 { return (__os
<< __p
.get()); }
567 _GLIBCXX_END_NAMESPACE_VERSION