pointer.h File Reference

This file is a GNU extension to the Standard C++ Library. More...

#include <iosfwd>
#include <bits/stl_iterator_base_types.h>
#include <ext/cast.h>
#include <ext/type_traits.h>

Include dependency graph for pointer.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	_CXX_POINTER_ARITH_OPERATOR_SET(INT_TYPE)
#define	_GCC_CXX_POINTER_COMPARISON_OPERATION_SET(OPERATOR)

Functions
namespace __gnu_cxx	_GLIBCXX_VISIBILITY (default)

Detailed Description

This file is a GNU extension to the Standard C++ Library.

Author

Bob Walters

Provides reusable _Pointer_adapter for assisting in the development of custom pointer types that can be used with the standard containers via the allocator::pointer and allocator::const_pointer typedefs.

Macro Definition Documentation

#define _CXX_POINTER_ARITH_OPERATOR_SET

(

INT_TYPE

)

Value:

inline friend _Pointer_adapter \
      operator+(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
      { return _Pointer_adapter(__lhs.get() + __offset); } \
\
      inline friend _Pointer_adapter \
      operator+(INT_TYPE __offset, const _Pointer_adapter& __rhs) \
      { return _Pointer_adapter(__rhs.get() + __offset); } \
\
      inline friend _Pointer_adapter \
      operator-(const _Pointer_adapter& __lhs, INT_TYPE __offset) \
      { return _Pointer_adapter(__lhs.get() - __offset); } \
\
      inline _Pointer_adapter& \
      operator+=(INT_TYPE __offset) \
      { \
        _Storage_policy::set(_Storage_policy::get() + __offset); \
        return *this; \
      } \
\
      inline _Pointer_adapter& \
      operator-=(INT_TYPE __offset) \
      { \
        _Storage_policy::set(_Storage_policy::get() - __offset); \
        return *this; \
      } \

Referenced by _GLIBCXX_VISIBILITY().

#define _GCC_CXX_POINTER_COMPARISON_OPERATION_SET

(

OPERATOR

)

Value:

template<typename _Tp1, typename _Tp2> \
    inline bool \
    operator OPERATOR(const _Pointer_adapter<_Tp1>& __lhs, _Tp2 __rhs) \
    { return __lhs.get() OPERATOR __rhs; } \
\
  template<typename _Tp1, typename _Tp2> \
    inline bool \
    operator OPERATOR(_Tp1 __lhs, const _Pointer_adapter<_Tp2>& __rhs) \
    { return __lhs OPERATOR __rhs.get(); } \
\
  template<typename _Tp1, typename _Tp2> \
    inline bool \
    operator OPERATOR(const _Pointer_adapter<_Tp1>& __lhs, \
                              const _Pointer_adapter<_Tp2>& __rhs) \
    { return __lhs.get() OPERATOR __rhs.get(); } \
\

Referenced by _GLIBCXX_VISIBILITY().

Function Documentation

namespace __gnu_cxx _GLIBCXX_VISIBILITY

(

default

)

A storage policy for use with _Pointer_adapter<> which yields a standard pointer.

A _Storage_policy is required to provide 4 things: 1) A get() API for returning the stored pointer value. 2) An set() API for storing a pointer value. 3) An element_type typedef to define the type this points to. 4) An operator<() to support pointer comparison. 5) An operator==() to support pointer comparison.

A storage policy for use with _Pointer_adapter<> which stores the pointer's address as an offset value which is relative to its own address.

This is intended for pointers within shared memory regions which might be mapped at different addresses by different processes. For null pointers, a value of 1 is used. (0 is legitimate sometimes for nodes in circularly linked lists) This value was chosen as the least likely to generate an incorrect null, As there is no reason why any normal pointer would point 1 byte into its own pointer address.

Relative_pointer_impl needs a specialization for const T because of the casting done during pointer arithmetic.

The specialization on this type helps resolve the problem of reference to void, and eliminates the need to specialize _Pointer_adapter for cases of void*, const void*, and so on.

This structure accommodates the way in which std::iterator_traits<> is normally specialized for const T*, so that value_type is still T.

The following provides an 'alternative pointer' that works with the containers when specified as the pointer typedef of the allocator.

The pointer type used with the containers doesn't have to be this class, but it must support the implicit conversions, pointer arithmetic, comparison operators, etc. that are supported by this class, and avoid raising compile-time ambiguities. Because creating a working pointer can be challenging, this pointer template was designed to wrapper an easier storage policy type, so that it becomes reusable for creating other pointer types.

A key point of this class is also that it allows container writers to 'assume' Allocator::pointer is a typedef for a normal pointer. This class supports most of the conventions of a true pointer, and can, for instance handle implicit conversion to const and base class pointer types. The only impositions on container writers to support extended pointers are: 1) use the Allocator::pointer typedef appropriately for pointer types. 2) if you need pointer casting, use the __pointer_cast<> functions from ext/cast.h. This allows pointer cast operations to be overloaded as necessary by custom pointers.

Note: The const qualifier works with this pointer adapter as follows:

_Tp* == _Pointer_adapter<_Std_pointer_impl<_Tp> >; const _Tp* == _Pointer_adapter<_Std_pointer_impl<const _Tp> >; _Tp* const == const _Pointer_adapter<_Std_pointer_impl<_Tp> >; const _Tp* const == const _Pointer_adapter<_Std_pointer_impl<const _Tp> >;

Comparison operators for _Pointer_adapter defer to the base class' comparison operators, when possible.

References _CXX_POINTER_ARITH_OPERATOR_SET, _GCC_CXX_POINTER_COMPARISON_OPERATION_SET, std::__exception_ptr::operator!=(), __gnu_debug::operator-(), __gnu_debug::operator<(), std::__exception_ptr::operator==(), __gnu_debug::operator>(), and __gnu_debug::operator>=().

Here is the call graph for this function: