std::allocator (3) - Linux Man Pages

std::allocator: std::allocator

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 default allocator is stateless, that is, all instances of the given allocator are interchangeable, 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 specialization declares no member functions. (until C++20)


All custom allocators also must be stateless. (until C++11)
Custom allocators may contain state. Each container or another allocator-aware object stores an instance of the supplied allocator and controls allocator replacement through std::allocator_traits. (since C++11)
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++14) std::true_type
rebind (deprecated in C++17)(removed in C++20) template< class U > struct rebind { typedef allocator<U> other; };
is_always_equal(C++17) std::true_type

Member functions


                      creates a new allocator instance
constructor (public member function)
                      destructs an allocator instance
destructor (public member function)


address obtains the address of an object, even if operator& is overloaded
                      (public member function)
(deprecated in C++17)
(removed in C++20)
                      allocates uninitialized storage
allocate (public member function)
                      deallocates storage
deallocate (public member function)


max_size returns the largest supported allocation size
                      (public member function)
(deprecated in C++17)
(removed in C++20)


construct constructs an object in allocated storage
                      (public member function)
(deprecated in C++17)
(removed in C++20)


destroy destructs an object in allocated storage
                      (public member function)
(deprecated in C++17)
(removed in C++20)

Non-member functions


           compares two allocator instances
operator== (public member function)
operator!=

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 internal type Node<T>, using the allocator A::rebind<Node<T>>::other (until C++11)
std::list<T, A> allocates nodes of some internal type Node<T>, using the allocator 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)

Example


// Run this code


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


  int main()
  {
      std::allocator<int> a1; // default allocator for ints
      int* a = a1.allocate(1); // space for one int
      a1.construct(a, 7); // construct the int
      std::cout << a[0] << '\n';
      a1.deallocate(a, 1); // deallocate space for one int


      // default allocator for strings
      std::allocator<std::string> a2;


      // same, but obtained by rebinding from the type of a1
      decltype(a1)::rebind<std::string>::other a2_1;


      // same, but obtained by rebinding from the type of a1 via allocator_traits
      std::allocator_traits<decltype(a1)>::rebind_alloc<std::string> a2_2;


      std::string* s = a2.allocate(2); // space for 2 strings


      a2.construct(s, "foo");
      a2.construct(s + 1, "bar");


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


      a2.destroy(s);
      a2.destroy(s + 1);
      a2.deallocate(s, 2);
  }

Output:


  7
  foo bar

See also


allocator_traits provides information about allocator types
                         (class template)
(C++11)


scoped_allocator_adaptor implements multi-level allocator for multi-level containers
                         (class template)
(C++11)


uses_allocator checks if the specified type supports uses-allocator construction
                         (class template)
(C++11)