Przejdź do głównej zawartości

std::allocator

Defined inmemory
// 1)
template< class T >
struct allocator;
// 2)
template<>
struct allocator<void>; // Deprecated in C++17, 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 (do C++20) The default allocator satisfies allocator completeness requirements (od C++17)

Member types

pubTypeDefinition
pubvalue_typeT
pubpointer (removed in C++20)T*
pubconst_pointer (removed in C++20)const T*
pubreference (removed in C++20)T&
pubconst_reference (removed in C++20)const T&
pubsize_typestd::ptrdiff_t
pubdifference_typestd::ptrdiff_t
pubpropagate_on_container_move_assignment (od C++11)std::true_type
pubrebind (removed in C++20)
template< class U >
struct rebind{
typedef allocator<U> other;
};
pubis_always_equal (od C++11)std::true_type

Member function

pub(constructor)creates a new allocator instance
pub(destructor)destructs an allocator instance
pubaddress (do C++20)obtains the address of an object, even if operator& is overloaded
puballocateallocates uninitialized storage
puballocate_at_least (od C++23)allocates uninitialized storage at least as large as requested size
pubdeallocatedeallocates storage
pubmax_size (do C++20)returns the largest supported allocation size
pubconstruct (do C++20)constructs an object in allocated storage
pubaddrdestroyess (do C++20)destructs an object in allocated storage

Non-member functions

puboperator==
operator!= (removed in C++20)
compares two allocator instances

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 (do C++11) std::allocator_traits<A>::rebind_alloc<Node<T>> , which is implemented in terms of A::rebind&lt;Node&lt;T>>::other if A is an std::allocator (od 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 deprecated and its member constant value is true for any T.

Example

#include <memory>
#include <iostream>
#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);
}
Result
7
foo bar

Defect reports

The following behavior-changing defect reports were applied retroactively to previously ished C++ standards.

pub DRApplied toBehavior as ishedCorrect behavior
pub LWG 2103C++11redundant comparison between allocator might be requiredpropagate_on_container_move_assignment provided
LWG 2108C++11there was no way to show allocator is statelessis_always_equal provided

std::allocator

Defined inmemory
// 1)
template< class T >
struct allocator;
// 2)
template<>
struct allocator<void>; // Deprecated in C++17, 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 (do C++20) The default allocator satisfies allocator completeness requirements (od C++17)

Member types

pubTypeDefinition
pubvalue_typeT
pubpointer (removed in C++20)T*
pubconst_pointer (removed in C++20)const T*
pubreference (removed in C++20)T&
pubconst_reference (removed in C++20)const T&
pubsize_typestd::ptrdiff_t
pubdifference_typestd::ptrdiff_t
pubpropagate_on_container_move_assignment (od C++11)std::true_type
pubrebind (removed in C++20)
template< class U >
struct rebind{
typedef allocator<U> other;
};
pubis_always_equal (od C++11)std::true_type

Member function

pub(constructor)creates a new allocator instance
pub(destructor)destructs an allocator instance
pubaddress (do C++20)obtains the address of an object, even if operator& is overloaded
puballocateallocates uninitialized storage
puballocate_at_least (od C++23)allocates uninitialized storage at least as large as requested size
pubdeallocatedeallocates storage
pubmax_size (do C++20)returns the largest supported allocation size
pubconstruct (do C++20)constructs an object in allocated storage
pubaddrdestroyess (do C++20)destructs an object in allocated storage

Non-member functions

puboperator==
operator!= (removed in C++20)
compares two allocator instances

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 (do C++11) std::allocator_traits<A>::rebind_alloc<Node<T>> , which is implemented in terms of A::rebind&lt;Node&lt;T>>::other if A is an std::allocator (od 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 deprecated and its member constant value is true for any T.

Example

#include <memory>
#include <iostream>
#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);
}
Result
7
foo bar

Defect reports

The following behavior-changing defect reports were applied retroactively to previously ished C++ standards.

pub DRApplied toBehavior as ishedCorrect behavior
pub LWG 2103C++11redundant comparison between allocator might be requiredpropagate_on_container_move_assignment provided
LWG 2108C++11there was no way to show allocator is statelessis_always_equal provided