1 // Custom pointer adapter and sample storage policies
3 // Copyright (C) 2008 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 2, 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 // 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,
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.
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.
43 #include <bits/stl_iterator_base_types.h>
45 #include <ext/type_traits.h>
47 _GLIBCXX_BEGIN_NAMESPACE(__gnu_cxx
)
50 * @brief A storage policy for use with _Pointer_adapter<> which yields a
53 * A _Storage_policy is required to provide 4 things:
54 * 1) A get() API for returning the stored pointer value.
55 * 2) An set() API for storing a pointer value.
56 * 3) An element_type typedef to define the type this points to.
57 * 4) An operator<() to support pointer comparison.
58 * 5) An operator==() to support pointer comparison.
60 template<typename _Tp
>
61 class _Std_pointer_impl
64 // the type this pointer points to.
65 typedef _Tp element_type
;
67 // A method to fetch the pointer value as a standard T* value;
72 // A method to set the pointer value, from a standard T* value;
74 set(element_type
* __arg
)
77 // Comparison of pointers
79 operator<(const _Std_pointer_impl
& __rarg
) const
80 { return (_M_value
< __rarg
._M_value
); }
83 operator==(const _Std_pointer_impl
& __rarg
) const
84 { return (_M_value
== __rarg
._M_value
); }
87 element_type
* _M_value
;
91 * @brief A storage policy for use with _Pointer_adapter<> which stores
92 * the pointer's address as an offset value which is relative to
95 * This is intended for pointers
96 * within shared memory regions which might be mapped at different
97 * addresses by different processes. For null pointers, a value of 1 is
98 * used. (0 is legitimate sometimes for nodes in circularly linked lists)
99 * This value was chosen as the least likely to generate an incorrect null,
100 * As there is no reason why any normal pointer would point 1 byte into
101 * its own pointer address.
103 template<typename _Tp
>
104 class _Relative_pointer_impl
107 typedef _Tp element_type
;
115 return reinterpret_cast<_Tp
*>(reinterpret_cast<_UIntPtrType
>(this)
125 _M_diff
= reinterpret_cast<_UIntPtrType
>(__arg
)
126 - reinterpret_cast<_UIntPtrType
>(this);
129 // Comparison of pointers
131 operator<(const _Relative_pointer_impl
& __rarg
) const
132 { return (reinterpret_cast<_UIntPtrType
>(this->get())
133 < reinterpret_cast<_UIntPtrType
>(__rarg
.get())); }
136 operator==(const _Relative_pointer_impl
& __rarg
) const
137 { return (reinterpret_cast<_UIntPtrType
>(this->get())
138 == reinterpret_cast<_UIntPtrType
>(__rarg
.get())); }
141 typedef __gnu_cxx::__conditional_type
<
142 (sizeof(unsigned long) >= sizeof(void*)),
143 unsigned long, unsigned long long>::__type _UIntPtrType
;
144 _UIntPtrType _M_diff
;
148 * Relative_pointer_impl needs a specialization for const T because of
149 * the casting done during pointer arithmetic.
151 template<typename _Tp
>
152 class _Relative_pointer_impl
<const _Tp
>
155 typedef const _Tp element_type
;
163 return reinterpret_cast<const _Tp
*>
164 (reinterpret_cast<_UIntPtrType
>(this) + _M_diff
);
168 set(const _Tp
* __arg
)
173 _M_diff
= reinterpret_cast<_UIntPtrType
>(__arg
)
174 - reinterpret_cast<_UIntPtrType
>(this);
177 // Comparison of pointers
179 operator<(const _Relative_pointer_impl
& __rarg
) const
180 { return (reinterpret_cast<_UIntPtrType
>(this->get())
181 < reinterpret_cast<_UIntPtrType
>(__rarg
.get())); }
184 operator==(const _Relative_pointer_impl
& __rarg
) const
185 { return (reinterpret_cast<_UIntPtrType
>(this->get())
186 == reinterpret_cast<_UIntPtrType
>(__rarg
.get())); }
189 typedef __gnu_cxx::__conditional_type
190 <(sizeof(unsigned long) >= sizeof(void*)),
191 unsigned long, unsigned long long>::__type _UIntPtrType
;
192 _UIntPtrType _M_diff
;
196 * The specialization on this type helps resolve the problem of
197 * reference to void, and eliminates the need to specialize _Pointer_adapter
198 * for cases of void*, const void*, and so on.
200 struct _Invalid_type
{ };
202 template<typename _Tp
>
203 struct _Reference_type
204 { typedef _Tp
& reference
; };
207 struct _Reference_type
<void>
208 { typedef _Invalid_type
& reference
; };
211 struct _Reference_type
<const void>
212 { typedef const _Invalid_type
& reference
; };
215 struct _Reference_type
<volatile void>
216 { typedef volatile _Invalid_type
& reference
; };
219 struct _Reference_type
<volatile const void>
220 { typedef const volatile _Invalid_type
& reference
; };
223 * This structure accomodates the way in which std::iterator_traits<>
224 * is normally specialized for const T*, so that value_type is still T.
226 template<typename _Tp
>
227 struct _Unqualified_type
228 { typedef _Tp type
; };
230 template<typename _Tp
>
231 struct _Unqualified_type
<const _Tp
>
232 { typedef _Tp type
; };
234 template<typename _Tp
>
235 struct _Unqualified_type
<volatile _Tp
>
236 { typedef volatile _Tp type
; };
238 template<typename _Tp
>
239 struct _Unqualified_type
<volatile const _Tp
>
240 { typedef volatile _Tp type
; };
243 * The following provides an 'alternative pointer' that works with the
244 * containers when specified as the pointer typedef of the allocator.
246 * The pointer type used with the containers doesn't have to be this class,
247 * but it must support the implicit conversions, pointer arithmetic,
248 * comparison operators, etc. that are supported by this class, and avoid
249 * raising compile-time ambiguities. Because creating a working pointer can
250 * be challenging, this pointer template was designed to wrapper an
251 * easier storage policy type, so that it becomes reusable for creating
252 * other pointer types.
254 * A key point of this class is also that it allows container writers to
255 * 'assume' Alocator::pointer is a typedef for a normal pointer. This class
256 * supports most of the conventions of a true pointer, and can, for instance
257 * handle implicit conversion to const and base class pointer types. The
258 * only impositions on container writers to support extended pointers are:
259 * 1) use the Allocator::pointer typedef appropriately for pointer types.
260 * 2) if you need pointer casting, use the __pointer_cast<> functions
261 * from ext/cast.h. This allows pointer cast operations to be overloaded
262 * is necessary by custom pointers.
264 * Note: The const qualifier works with this pointer adapter as follows:
266 * _Tp* == _Pointer_adapter<_Std_pointer_impl<_Tp> >;
267 * const _Tp* == _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
268 * _Tp* const == const _Pointer_adapter<_Std_pointer_impl<_Tp> >;
269 * const _Tp* const == const _Pointer_adapter<_Std_pointer_impl<const _Tp> >;
271 template<typename _Storage_policy
>
272 class _Pointer_adapter
: public _Storage_policy
275 typedef typename
_Storage_policy::element_type element_type
;
277 // These are needed for iterator_traits
278 typedef std::random_access_iterator_tag iterator_category
;
279 typedef typename _Unqualified_type
<element_type
>::type value_type
;
280 typedef std::ptrdiff_t difference_type
;
281 typedef _Pointer_adapter pointer
;
282 typedef typename _Reference_type
<element_type
>::reference reference
;
284 // Reminder: 'const' methods mean that the method is valid when the
285 // pointer is immutable, and has nothing to do with whether the
286 // 'pointee' is const.
288 // Default Constructor (Convert from element_type*)
289 _Pointer_adapter(element_type
* __arg
= 0)
290 { _Storage_policy::set(__arg
); }
292 // Copy constructor from _Pointer_adapter of same type.
293 _Pointer_adapter(const _Pointer_adapter
& __arg
)
294 { _Storage_policy::set(__arg
.get()); }
296 // Convert from _Up* if conversion to element_type* is valid.
297 template<typename _Up
>
298 _Pointer_adapter(_Up
* __arg
)
299 { _Storage_policy::set(__arg
); }
301 // Conversion from another _Pointer_adapter if _Up if static cast is
303 template<typename _Up
>
304 _Pointer_adapter(const _Pointer_adapter
<_Up
>& __arg
)
305 { _Storage_policy::set(__arg
.get()); }
308 ~_Pointer_adapter() { }
310 // Assignment operator
312 operator=(const _Pointer_adapter
& __arg
)
314 _Storage_policy::set(__arg
.get());
318 template<typename _Up
>
320 operator=(const _Pointer_adapter
<_Up
>& __arg
)
322 _Storage_policy::set(__arg
.get());
326 template<typename _Up
>
328 operator=(_Up
* __arg
)
330 _Storage_policy::set(__arg
);
334 // Operator*, returns element_type&
337 { return *(_Storage_policy::get()); }
339 // Operator->, returns element_type*
342 { return _Storage_policy::get(); }
344 // Operator[], returns a element_type& to the item at that loc.
346 operator[](std::ptrdiff_t __index
) const
347 { return _Storage_policy::get()[__index
]; }
349 // To allow implicit conversion to "bool", for "if (ptr)..."
351 typedef element_type
*(_Pointer_adapter::*__unspecified_bool_type
)() const;
354 operator __unspecified_bool_type() const
356 return _Storage_policy::get() == 0 ? 0 :
357 &_Pointer_adapter::operator->;
360 // ! operator (for: if (!ptr)...)
363 { return (_Storage_policy::get() == 0); }
365 // Pointer differences
366 inline friend std::ptrdiff_t
367 operator-(const _Pointer_adapter
& __lhs
, element_type
* __rhs
)
368 { return (__lhs
.get() - __rhs
); }
370 inline friend std::ptrdiff_t
371 operator-(element_type
* __lhs
, const _Pointer_adapter
& __rhs
)
372 { return (__lhs
- __rhs
.get()); }
374 template<typename _Up
>
375 inline friend std::ptrdiff_t
376 operator-(const _Pointer_adapter
& __lhs
, _Up
* __rhs
)
377 { return (__lhs
.get() - __rhs
); }
379 template<typename _Up
>
380 inline friend std::ptrdiff_t
381 operator-(_Up
* __lhs
, const _Pointer_adapter
& __rhs
)
382 { return (__lhs
- __rhs
.get()); }
384 template<typename _Up
>
385 inline std::ptrdiff_t
386 operator-(const _Pointer_adapter
<_Up
>& __rhs
) const
387 { return (_Storage_policy::get() - __rhs
.get()); }
390 // Note: There is a reason for all this overloading based on different
391 // integer types. In some libstdc++-v3 test cases, a templated
392 // operator+ is declared which can match any types. This operator
393 // tends to "steal" the recognition of _Pointer_adapter's own operator+
394 // unless the integer type matches perfectly.
396 #define _CXX_POINTER_ARITH_OPERATOR_SET(INT_TYPE) \
397 inline friend _Pointer_adapter \
398 operator+(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
399 { return _Pointer_adapter(__lhs.get() + __offset); } \
401 inline friend _Pointer_adapter \
402 operator+(INT_TYPE __offset, const _Pointer_adapter& __rhs) \
403 { return _Pointer_adapter(__rhs.get() + __offset); } \
405 inline friend _Pointer_adapter \
406 operator-(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
407 { return _Pointer_adapter(__lhs.get() - __offset); } \
409 inline _Pointer_adapter& \
410 operator+=(INT_TYPE __offset) \
412 _Storage_policy::set(_Storage_policy::get() + __offset); \
416 inline _Pointer_adapter& \
417 operator-=(INT_TYPE __offset) \
419 _Storage_policy::set(_Storage_policy::get() - __offset); \
422 // END of _CXX_POINTER_ARITH_OPERATOR_SET macro
424 // Expand into the various pointer arithmatic operators needed.
425 _CXX_POINTER_ARITH_OPERATOR_SET(short);
426 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned short);
427 _CXX_POINTER_ARITH_OPERATOR_SET(int);
428 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned int);
429 _CXX_POINTER_ARITH_OPERATOR_SET(long);
430 _CXX_POINTER_ARITH_OPERATOR_SET(unsigned long);
432 // Mathematical Manipulators
433 inline _Pointer_adapter
&
436 _Storage_policy::set(_Storage_policy::get() + 1);
440 inline _Pointer_adapter
441 operator++(int __unused
)
443 _Pointer_adapter
tmp(*this);
444 _Storage_policy::set(_Storage_policy::get() + 1);
448 inline _Pointer_adapter
&
451 _Storage_policy::set(_Storage_policy::get() - 1);
455 inline _Pointer_adapter
458 _Pointer_adapter
tmp(*this);
459 _Storage_policy::set(_Storage_policy::get() - 1);
463 }; // class _Pointer_adapter
466 #define _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(OPERATOR,BLANK) \
467 template<typename _Tp1, typename _Tp2> \
469 operator OPERATOR##BLANK (const _Pointer_adapter<_Tp1>& __lhs, _Tp2 __rhs) \
470 { return __lhs.get() OPERATOR##BLANK __rhs; } \
472 template<typename _Tp1, typename _Tp2> \
474 operator OPERATOR##BLANK (_Tp1 __lhs, const _Pointer_adapter<_Tp2>& __rhs) \
475 { return __lhs OPERATOR##BLANK __rhs.get(); } \
477 template<typename _Tp1, typename _Tp2> \
479 operator OPERATOR##BLANK (const _Pointer_adapter<_Tp1>& __lhs, \
480 const _Pointer_adapter<_Tp2>& __rhs) \
481 { return __lhs.get() OPERATOR##BLANK __rhs.get(); } \
483 // End GCC_CXX_POINTER_COMPARISON_OPERATION_SET Macro
485 // Expand into the various comparison operators needed.
486 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(==,);
487 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(!=,);
488 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<,);
489 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<=,);
490 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>,);
491 _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>=,);
493 // These are here for expressions like "ptr == 0", "ptr != 0"
494 template<typename _Tp
>
496 operator==(const _Pointer_adapter
<_Tp
>& __lhs
, int __rhs
)
497 { return __lhs
.get() == reinterpret_cast<void*>(__rhs
); }
499 template<typename _Tp
>
501 operator==(int __lhs
, const _Pointer_adapter
<_Tp
>& __rhs
)
502 { return __rhs
.get() == reinterpret_cast<void*>(__lhs
); }
504 template<typename _Tp
>
506 operator!=(const _Pointer_adapter
<_Tp
>& __lhs
, int __rhs
)
507 { return __lhs
.get() != reinterpret_cast<void*>(__rhs
); }
509 template<typename _Tp
>
511 operator!=(int __lhs
, const _Pointer_adapter
<_Tp
>& __rhs
)
512 { return __rhs
.get() != reinterpret_cast<void*>(__lhs
); }
515 * Comparison operators for _Pointer_adapter defer to the base class'es
516 * comparison operators, when possible.
518 template<typename _Tp
>
520 operator==(const _Pointer_adapter
<_Tp
>& __lhs
,
521 const _Pointer_adapter
<_Tp
>& __rhs
)
522 { return __lhs
._Tp::operator==(__rhs
); }
524 template<typename _Tp
>
526 operator<=(const _Pointer_adapter
<_Tp
>& __lhs
,
527 const _Pointer_adapter
<_Tp
>& __rhs
)
528 { return __lhs
._Tp::operator<(__rhs
) || __lhs
._Tp::operator==(__rhs
); }
530 template<typename _Tp
>
532 operator!=(const _Pointer_adapter
<_Tp
>& __lhs
,
533 const _Pointer_adapter
<_Tp
>& __rhs
)
534 { return !(__lhs
._Tp::operator==(__rhs
)); }
536 template<typename _Tp
>
538 operator>(const _Pointer_adapter
<_Tp
>& __lhs
,
539 const _Pointer_adapter
<_Tp
>& __rhs
)
540 { return !(__lhs
._Tp::operator<(__rhs
) || __lhs
._Tp::operator==(__rhs
)); }
542 template<typename _Tp
>
544 operator>=(const _Pointer_adapter
<_Tp
>& __lhs
,
545 const _Pointer_adapter
<_Tp
>& __rhs
)
546 { return !(__lhs
._Tp::operator<(__rhs
)); }
548 template<typename _CharT
, typename _Traits
, typename _StoreT
>
549 inline std::basic_ostream
<_CharT
, _Traits
>&
550 operator<<(std::basic_ostream
<_CharT
, _Traits
>& __os
,
551 const _Pointer_adapter
<_StoreT
>& __p
)
552 { return (__os
<< __p
.get()); }
554 _GLIBCXX_END_NAMESPACE