home | help 
std::pointer_traits(3)	       C++ Standard Libary	  std::pointer_traits(3)

NAME
     std::pointer_traits - std::pointer_traits

Synopsis
	Defined in header <memory>
	template< class Ptr >	   (1) (since C++11)
	struct pointer_traits;
	template< class T >	   (2) (since C++11)
	struct pointer_traits<T*>;

	The  pointer_traits  class template provides the standardized way to ac-
     cess certain
	properties of pointer-like types (fancy pointers, such as
	boost::interprocess::offset_ptr).  The	standard  template  std::alloca-
     tor_traits relies
	on  pointer_traits  to	determine  the defaults for various typedefs re-
     quired by
	Allocator.

	1) The non-specialized pointer_traits conditionally declares the follow-
     ing members:

	Let /*element-type-of*/<Ptr> be

	  * Ptr::element_type if present;
	  * otherwise, T if Ptr is a class template  specialization  Template<T,
     Args...>,
	    where Args... is zero or more type arguments;
	  * otherwise, not defined.

	If  /*element-type-of*/<Ptr> is not defined, the primary template has no
     members
	specified in this page.

Member types
	Type		Definition
	pointer 	Ptr
	element_type	/*element-type-of*/<Ptr>
	difference_type    Ptr::difference_type    if	  present,     otherwise
     std::ptrdiff_t

Member alias templates
	Template		  Definition
	template<  class  U  >	using  Ptr::rebind<U>  if exists, otherwise Tem-
     plate<U, Args...>
	rebind			  if  Ptr  is  a  template  specialization  Tem-
     plate<T, Args...>

Member functions
	pointer_to obtains a dereferenceable pointer to its argument
	[static]   (public static member function)

	2)  A  specialization  is provided for pointer types, T*, which declares
     the following
	members:

Member types
	Type		Definition
	pointer 	T*
	element_type	T
	difference_type std::ptrdiff_t

Member alias templates
	Template			 Definition
	template< class U > using rebind U*

Member functions
	pointer_to obtains a dereferenceable pointer to its argument
	[static]   (public static member function)

	Optional member functions of program-defined specializations

	to_address		   obtains a raw pointer from  a  fancy  pointer
     (inverse of
	[static] (C++20)(optional) pointer_to)
				   (public static member function)

Notes
	The rebind member template alias makes it possible, given a pointer-like
     type that
	points	to T, to obtain the same pointer-like type that points to U. For
     example,

      using  another_pointer  =   std::pointer_traits<std::shared_ptr<int>>::re-
     bind<double>;
      static_assert(std::is_same<another_pointer,	    std::shared_ptr<dou-
     ble>>::value);

	A specialization for user-defined fancy pointer types may provide an
	additional static member function to_address to customize  the	behavior
     (since C++20)
	of std::to_address.

	    Feature-test macro	    Value    Std	       Feature
	__cpp_lib_constexpr_memory	201811L     (C++20)	constexpr     in
     std::pointer_traits

Example
     // Run this code

      #include <iostream>
      #include <memory>

      template<class Ptr>
      struct BlockList
      {
	  // Predefine a memory block
	  struct block;

	  // Define a pointer to a memory block from the kind of pointer Ptr s
	  // If Ptr is any kind of T*, block_ptr_t is block*
	  // If Ptr is smart_ptr<T>, block_ptr_t is smart_ptr<block>
	  using block_ptr_t =  typename  std::pointer_traits<Ptr>::template  re-
     bind<block>;

	  struct block
	  {
	      std::size_t size{};
	      block_ptr_t next_block{};
	  };

	  block_ptr_t free_blocks;
      };

      int main()
      {
	  [[maybe_unused]]
	  BlockList<int*> bl1;
	  // The type of bl1.free_blocks is BlockList<int*>:: block*

	  BlockList<std::shared_ptr<char>> bl2;
	  // The type of bl2.free_blocks is
	  // std::shared_ptr<BlockList<std::shared_ptr<char>>::block>
	  std::cout << bl2.free_blocks.use_count() << '\n';
      }

Output:
      0

	Defect reports

	The  following	behavior-changing  defect  reports were applied retroac-
     tively to
	previously published C++ standards.

	   DR	 Applied to	       Behavior as  published		    Cor-
     rect behavior
	LWG  3545  C++11       primary	template caused hard error when     made
     SFINAE-friendly
			    element_type is invalid

See also
	allocator_traits provides information about allocator types
	(C++11) 	 (class template)
	addressof	 obtains actual address of an object, even if the &  op-
     erator is
	(C++11) 	 overloaded
			 (function template)

http://cppreference.com 	   2024.06.10		  std::pointer_traits(3)
home | help