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

NAME
     std::allocator - std::allocator

Synopsis
	Defined in header <memory>
	template< class T >	   (1)
	struct allocator;
	template<>		   (2) (deprecated in C++17)
	struct allocator<void>;        (removed in C++20)

	The  std::allocator  class template is the default Allocator used by all
     standard
	library containers if no user-specified allocator is provided.	The  de-
     fault allocator
	is  stateless,	that is, all instances of the given allocator are inter-
     changeable,
	compare equal and can deallocate memory allocated by any other	instance
     of the same
	allocator type.

	The explicit specialization for void lacks the member typedefs
	reference,   const_reference,	size_type   and   difference_type.  This
     (until C++20)
	specialization declares no member functions.

	The default allocator  satisfies  allocator  completeness  requirements.
     (since C++17)

Member types
	Type							    Definition
	value_type						    T
	pointer (deprecated in C++17)(removed in C++20) 	    T*
	const_pointer (deprecated in C++17)(removed in C++20)	    const T*
	reference (deprecated in C++17)(removed in C++20)	    T&
	const_reference (deprecated in C++17)(removed in C++20)     const T&
	size_type						    std::size_t
	difference_type
     std::ptrdiff_t
	propagate_on_container_move_assignment				 (C++11)
     std::true_type
								    template<
     class U >

								    struct   re-
     bind
	rebind (deprecated in C++17)(removed in C++20)		    {
									typedef
     allocator<U>
								    other;
								    };
	is_always_equal      (C++11)(deprecated     in	   C++23)(removed     in
     std::true_type
	C++26)

Member functions
	constructor	  creates a new allocator instance
			  (public member function)
	destructor	  destructs an allocator instance
			  (public member function)
	address 	  obtains the address of an object, even if operator& is
     overloaded
	(until C++20)	  (public member function)
	allocate	  allocates uninitialized storage
			  (public member function)
	allocate_at_least allocates uninitialized storage at least as  large  as
     requested
	(C++23) 	  size
			  (public member function)
	deallocate	  deallocates storage
			  (public member function)
	max_size	  returns the largest supported allocation size
	(until C++20)	  (public member function)
	construct	  constructs an object in allocated storage
	(until C++20)	  (public member function)
	destroy 	  destructs an object in allocated storage
	(until C++20)	  (public member function)

Non-member functions
	operator==	   compares two allocator instances
	operator!=	   (public member function)
	(removed in C++20)

Notes
	The  member  template class rebind provides a way to obtain an allocator
     for a
	different type. For example, std::list<T, A> allocates nodes of some in-
     ternal type
	Node<T>, using the allocator
	A::rebind<Node<T>>::other
	(until C++11)
	std::allocator_traits<A>::rebind_alloc<Node<T>>, which is implemented in
     terms of
	A::rebind<Node<T>>::other if A is an std::allocator
	(since C++11).

	Member type is_always_equal is deprecated via LWG issue 3170, because it
     makes
	custom allocators derived from std::allocator treated as always equal by
     default.
	std::allocator_traits<std::allocator<T>>::is_always_equal is not  depre-
     cated and its
	member constant value is true for any T.

Example
     // Run this code

      #include <iostream>
      #include <memory>
      #include <string>

      int main()
      {
	  // default allocator for ints
	  std::allocator<int> alloc1;

	  // demonstrating the few directly usable members
	  static_assert(std::is_same_v<int, decltype(alloc1)::value_type>);
	  int* p1 = alloc1.allocate(1); // space for one int
	  alloc1.deallocate(p1, 1);	// and it is gone

	  // Even those can be used through traits though, so no need
	  using  traits_t1  =  std::allocator_traits<decltype(alloc1)>;  //  The
     matching trait
	  p1 = traits_t1::allocate(alloc1, 1);
	  traits_t1::construct(alloc1, p1, 7);	// construct the int
	  std::cout << *p1 << '\n';
	  traits_t1::deallocate(alloc1, p1, 1); // deallocate space for one int

	  // default allocator for strings
	  std::allocator<std::string> alloc2;
	  // matching traits
	  using traits_t2 = std::allocator_traits<decltype(alloc2)>;

	  // Rebinding the allocator using the trait for strings gets  the  same
     type
	  traits_t2::rebind_alloc<std::string> alloc_ = alloc2;

	  std::string*	p2  =  traits_t2::allocate(alloc2,  2);  //  space for 2
     strings

	  traits_t2::construct(alloc2, p2, "foo");
	  traits_t2::construct(alloc2, p2 + 1, "bar");

	  std::cout << p2[0] << ' ' << p2[1] << '\n';

	  traits_t2::destroy(alloc2, p2 + 1);
	  traits_t2::destroy(alloc2, p2);
	  traits_t2::deallocate(alloc2, p2, 2);
      }

Output:
      7
      foo bar

	Defect reports

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

	   DR	  Applied to   Behavior as published		  Correct behav-
     ior
			    redundant	  comparison	       propagate_on_con-
     tainer_move_assignment
	LWG 2103 C++11	    between allocator might   provided
			    be required
	LWG 2108 C++11	    there was no way to show  is_always_equal provided
			    allocator is stateless

See also
	allocator_traits	 provides information about allocator types
	(C++11) 		 (class template)
	scoped_allocator_adaptor  implements  multi-level  allocator  for multi-
     level containers
	(C++11) 		 (class template)
	uses_allocator		 checks if the specified type supports	uses-al-
     locator
	(C++11) 		 construction
				 (class template)

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