// Custom pointer adapter and sample storage policies
// Copyright (C) 2008-2025 Free Software Foundation, Inc.
//
// This file is part of the GNU ISO C++ Library. This library is free
// software; you can redistribute it and/or modify it under the
// terms of the GNU General Public License as published by the
// Free Software Foundation; either version 3, or (at your option)
// any later version.
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// Under Section 7 of GPL version 3, you are granted additional
// permissions described in the GCC Runtime Library Exception, version
// 3.1, as published by the Free Software Foundation.
// You should have received a copy of the GNU General Public License and
// a copy of the GCC Runtime Library Exception along with this program;
// see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
// <http://www.gnu.org/licenses/>.
/**
* @file ext/pointer.h
* 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.
*/
#ifndef _POINTER_H
#define _POINTER_H 1
#ifdef _GLIBCXX_SYSHDR
#pragma GCC system_header
#endif
#if _GLIBCXX_HOSTED
# include <iosfwd>
#endif
#include <stdint.h> // uintptr_t
#include <bits/stl_iterator_base_types.h>
#include <ext/cast.h>
#include <ext/type_traits.h>
#if __cplusplus >= 201103L
# include <bits/move.h>
# include <bits/ptr_traits.h>
#endif
#if __cplusplus > 201703L
# include <iterator> // for indirectly_readable_traits
#endif
namespace __gnu_cxx _GLIBCXX_VISIBILITY(default)
{
_GLIBCXX_BEGIN_NAMESPACE_VERSION
/**
* @brief 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.
*/
template<typename _Tp>
class _Std_pointer_impl
{
public:
// the type this pointer points to.
typedef _Tp element_type;
// A method to fetch the pointer value as a standard T* value;
inline _Tp*
get() const
{ return _M_value; }
// A method to set the pointer value, from a standard T* value;
inline void
set(element_type* __arg)
{ _M_value = __arg; }
// Comparison of pointers
inline bool
operator<(const _Std_pointer_impl& __rarg) const
{ return (_M_value < __rarg._M_value); }
inline bool
operator==(const _Std_pointer_impl& __rarg) const
{ return (_M_value == __rarg._M_value); }
private:
element_type* _M_value;
};
/**
* @brief 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.
*/
template<typename _Tp>
class _Relative_pointer_impl
{
public:
typedef _Tp element_type;
_Tp*
get() const
{
if (_M_diff == 1)
return 0;
else
return reinterpret_cast<_Tp*>(reinterpret_cast<uintptr_t>(this)
+ _M_diff);
}
void
set(_Tp* __arg)
{
if (!__arg)
_M_diff = 1;
else
_M_diff = reinterpret_cast<uintptr_t>(__arg)
- reinterpret_cast<uintptr_t>(this);
}
// Comparison of pointers
inline bool
operator<(const _Relative_pointer_impl& __rarg) const
{ return (reinterpret_cast<uintptr_t>(this->get())
< reinterpret_cast<uintptr_t>(__rarg.get())); }
inline bool
operator==(const _Relative_pointer_impl& __rarg) const
{ return (reinterpret_cast<uintptr_t>(this->get())
== reinterpret_cast<uintptr_t>(__rarg.get())); }
private:
typedef __UINTPTR_TYPE__ uintptr_t;
uintptr_t _M_diff;
};
/**
* Relative_pointer_impl needs a specialization for const T because of
* the casting done during pointer arithmetic.
*/
template<typename _Tp>
class _Relative_pointer_impl<const _Tp>
{
public:
typedef const _Tp element_type;
const _Tp*
get() const
{
if (_M_diff == 1)
return 0;
else
return reinterpret_cast<const _Tp*>
(reinterpret_cast<uintptr_t>(this) + _M_diff);
}
void
set(const _Tp* __arg)
{
if (!__arg)
_M_diff = 1;
else
_M_diff = reinterpret_cast<uintptr_t>(__arg)
- reinterpret_cast<uintptr_t>(this);
}
// Comparison of pointers
inline bool
operator<(const _Relative_pointer_impl& __rarg) const
{ return (reinterpret_cast<uintptr_t>(this->get())
< reinterpret_cast<uintptr_t>(__rarg.get())); }
inline bool
operator==(const _Relative_pointer_impl& __rarg) const
{ return (reinterpret_cast<uintptr_t>(this->get())
== reinterpret_cast<uintptr_t>(__rarg.get())); }
private:
typedef __UINTPTR_TYPE__ uintptr_t;
uintptr_t _M_diff;
};
/**
* 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.
*/
struct _Invalid_type { };
template<typename _Tp>
struct _Reference_type
{ typedef _Tp& reference; };
template<>
struct _Reference_type<void>
{ typedef _Invalid_type& reference; };
template<>
struct _Reference_type<const void>
{ typedef const _Invalid_type& reference; };
template<>
struct _Reference_type<volatile void>
{ typedef volatile _Invalid_type& reference; };
template<>
struct _Reference_type<volatile const void>
{ typedef const volatile _Invalid_type& reference; };
/**
* This structure accommodates the way in which
* std::iterator_traits<> is normally specialized for const T*, so
* that value_type is still T.
*/
template<typename _Tp>
struct _Unqualified_type
{ typedef _Tp type; };
template<typename _Tp>
struct _Unqualified_type<const _Tp>
{ typedef _Tp type; };
/**
* 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> >;
*/
template<typename _Storage_policy>
class _Pointer_adapter : public _Storage_policy
{
public:
typedef typename _Storage_policy::element_type element_type;
// These are needed for iterator_traits
typedef std::random_access_iterator_tag iterator_category;
typedef typename _Unqualified_type<element_type>::type value_type;
typedef std::ptrdiff_t difference_type;
typedef _Pointer_adapter pointer;
typedef typename _Reference_type<element_type>::reference reference;
// Reminder: 'const' methods mean that the method is valid when the
// pointer is immutable, and has nothing to do with whether the
// 'pointee' is const.
// Default Constructor (Convert from element_type*)
_Pointer_adapter(element_type* __arg = 0)
{ _Storage_policy::set(__arg); }
// Copy constructor from _Pointer_adapter of same type.
_Pointer_adapter(const _Pointer_adapter& __arg)
{ _Storage_policy::set(__arg.get()); }
// Convert from _Up* if conversion to element_type* is valid.
template<typename _Up>
_Pointer_adapter(_Up* __arg)
{ _Storage_policy::set(__arg); }
// Conversion from another _Pointer_adapter if _Up if static cast is
// valid.
template<typename _Up>
_Pointer_adapter(const _Pointer_adapter<_Up>& __arg)
{ _Storage_policy::set(__arg.get()); }
// Destructor
~_Pointer_adapter() { }
// Assignment operator
_Pointer_adapter&
operator=(const _Pointer_adapter& __arg)
{
_Storage_policy::set(__arg.get());
return *this;
}
template<typename _Up>
_Pointer_adapter&
operator=(const _Pointer_adapter<_Up>& __arg)
{
_Storage_policy::set(__arg.get());
return *this;
}
template<typename _Up>
_Pointer_adapter&
operator=(_Up* __arg)
{
_Storage_policy::set(__arg);
return *this;
}
// Operator*, returns element_type&
inline reference
operator*() const
{ return *(_Storage_policy::get()); }
// Operator->, returns element_type*
inline element_type*
operator->() const
{ return _Storage_policy::get(); }
// Operator[], returns a element_type& to the item at that loc.
inline reference
operator[](std::ptrdiff_t __index) const
{ return _Storage_policy::get()[__index]; }
// To allow implicit conversion to "bool", for "if (ptr)..."
#if __cplusplus >= 201103L
explicit operator bool() const { return _Storage_policy::get() != 0; }
#else
private:
typedef element_type*(_Pointer_adapter::*__unspecified_bool_type)() const;
public:
operator __unspecified_bool_type() const
{
return _Storage_policy::get() == 0 ? 0 :
&_Pointer_adapter::operator->;
}
// ! operator (for: if (!ptr)...)
inline bool
operator!() const
{ return (_Storage_policy::get() == 0); }
#endif
// Pointer differences
inline friend std::ptrdiff_t
operator-(const _Pointer_adapter& __lhs, element_type* __rhs)
{ return (__lhs.get() - __rhs); }
inline friend std::ptrdiff_t
operator-(element_type* __lhs, const _Pointer_adapter& __rhs)
{ return (__lhs - __rhs.get()); }
template<typename _Up>
inline friend std::ptrdiff_t
operator-(const _Pointer_adapter& __lhs, _Up* __rhs)
{ return (__lhs.get() - __rhs); }
template<typename _Up>
inline friend std::ptrdiff_t
operator-(_Up* __lhs, const _Pointer_adapter& __rhs)
{ return (__lhs - __rhs.get()); }
template<typename _Up>
inline std::ptrdiff_t
operator-(const _Pointer_adapter<_Up>& __rhs) const
{ return (_Storage_policy::get() - __rhs.get()); }
// Pointer math
// Note: There is a reason for all this overloading based on different
// integer types. In some libstdc++-v3 test cases, a templated
// operator+ is declared which can match any types. This operator
// tends to "steal" the recognition of _Pointer_adapter's own operator+
// unless the integer type matches perfectly.
#define _CXX_POINTER_ARITH_OPERATOR_SET(INT_TYPE) \
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; \
} \
// END of _CXX_POINTER_ARITH_OPERATOR_SET macro
// Expand into the various pointer arithmetic operators needed.
_CXX_POINTER_ARITH_OPERATOR_SET(short);
_CXX_POINTER_ARITH_OPERATOR_SET(unsigned short);
_CXX_POINTER_ARITH_OPERATOR_SET(int);
_CXX_POINTER_ARITH_OPERATOR_SET(unsigned int);
_CXX_POINTER_ARITH_OPERATOR_SET(long);
_CXX_POINTER_ARITH_OPERATOR_SET(unsigned long);
#ifdef _GLIBCXX_USE_LONG_LONG
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wlong-long"
_CXX_POINTER_ARITH_OPERATOR_SET(long long);
_CXX_POINTER_ARITH_OPERATOR_SET(unsigned long long);
#pragma GCC diagnostic pop
#endif
// Mathematical Manipulators
inline _Pointer_adapter&
operator++()
{
_Storage_policy::set(_Storage_policy::get() + 1);
return *this;
}
inline _Pointer_adapter
operator++(int)
{
_Pointer_adapter __tmp(*this);
_Storage_policy::set(_Storage_policy::get() + 1);
return __tmp;
}
inline _Pointer_adapter&
operator--()
{
_Storage_policy::set(_Storage_policy::get() - 1);
return *this;
}
inline _Pointer_adapter
operator--(int)
{
_Pointer_adapter __tmp(*this);
_Storage_policy::set(_Storage_policy::get() - 1);
return __tmp;
}
#if __cpp_lib_three_way_comparison
friend std::strong_ordering
operator<=>(const _Pointer_adapter& __lhs, const _Pointer_adapter& __rhs)
noexcept
{ return __lhs.get() <=> __rhs.get(); }
#endif
}; // class _Pointer_adapter
#define _GCC_CXX_POINTER_COMPARISON_OPERATION_SET(OPERATOR) \
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(); } \
\
// End GCC_CXX_POINTER_COMPARISON_OPERATION_SET Macro
// Expand into the various comparison operators needed.
_GCC_CXX_POINTER_COMPARISON_OPERATION_SET(==)
_GCC_CXX_POINTER_COMPARISON_OPERATION_SET(!=)
_GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<)
_GCC_CXX_POINTER_COMPARISON_OPERATION_SET(<=)
_GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>)
_GCC_CXX_POINTER_COMPARISON_OPERATION_SET(>=)
// These are here for expressions like "ptr == 0", "ptr != 0"
template<typename _Tp>
inline bool
operator==(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
{ return __lhs.get() == reinterpret_cast<void*>(__rhs); }
template<typename _Tp>
inline bool
operator==(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
{ return __rhs.get() == reinterpret_cast<void*>(__lhs); }
template<typename _Tp>
inline bool
operator!=(const _Pointer_adapter<_Tp>& __lhs, int __rhs)
{ return __lhs.get() != reinterpret_cast<void*>(__rhs); }
template<typename _Tp>
inline bool
operator!=(int __lhs, const _Pointer_adapter<_Tp>& __rhs)
{ return __rhs.get() != reinterpret_cast<void*>(__lhs); }
/**
* Comparison operators for _Pointer_adapter defer to the base class'
* comparison operators, when possible.
*/
template<typename _Tp>
inline bool
operator==(const _Pointer_adapter<_Tp>& __lhs,
const _Pointer_adapter<_Tp>& __rhs)
{ return __lhs._Tp::operator==(__rhs); }
template<typename _Tp>
inline bool
operator<=(const _Pointer_adapter<_Tp>& __lhs,
const _Pointer_adapter<_Tp>& __rhs)
{ return __lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs); }
template<typename _Tp>
inline bool
operator!=(const _Pointer_adapter<_Tp>& __lhs,
const _Pointer_adapter<_Tp>& __rhs)
{ return !(__lhs._Tp::operator==(__rhs)); }
template<typename _Tp>
inline bool
operator>(const _Pointer_adapter<_Tp>& __lhs,
const _Pointer_adapter<_Tp>& __rhs)
{ return !(__lhs._Tp::operator<(__rhs) || __lhs._Tp::operator==(__rhs)); }
template<typename _Tp>
inline bool
operator>=(const _Pointer_adapter<_Tp>& __lhs,
const _Pointer_adapter<_Tp>& __rhs)
{ return !(__lhs._Tp::operator<(__rhs)); }
#if _GLIBCXX_HOSTED
template<typename _CharT, typename _Traits, typename _StoreT>
inline std::basic_ostream<_CharT, _Traits>&
operator<<(std::basic_ostream<_CharT, _Traits>& __os,
const _Pointer_adapter<_StoreT>& __p)
{ return (__os << __p.get()); }
#endif // HOSTED
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace
#if __cplusplus >= 201103L
namespace std _GLIBCXX_VISIBILITY(default)
{
_GLIBCXX_BEGIN_NAMESPACE_VERSION
template<typename _Storage_policy>
struct pointer_traits<__gnu_cxx::_Pointer_adapter<_Storage_policy>>
{
/// The pointer type
typedef __gnu_cxx::_Pointer_adapter<_Storage_policy> pointer;
/// The type pointed to
typedef typename pointer::element_type element_type;
/// Type used to represent the difference between two pointers
typedef typename pointer::difference_type difference_type;
template<typename _Up>
using rebind = typename __gnu_cxx::_Pointer_adapter<
typename pointer_traits<_Storage_policy>::template rebind<_Up>>;
static pointer pointer_to(typename pointer::reference __r) noexcept
{ return pointer(std::addressof(__r)); }
};
#if __cpp_lib_concepts
template<typename _Policy>
struct indirectly_readable_traits<__gnu_cxx::_Pointer_adapter<_Policy>>
{
using value_type
= typename __gnu_cxx::_Pointer_adapter<_Policy>::value_type;
};
#endif
_GLIBCXX_END_NAMESPACE_VERSION
} // namespace
#endif
#endif // _POINTER_H