std::allocator

 

C++

Language

Standard Library Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Technical Specifications

 

Dynamic memory management

Smart pointers unique_ptr (C++11) shared_ptr (C++11) weak_ptr (C++11) auto_ptr (until C++17) owner_less (C++11) enable_shared_from_this (C++11) bad_weak_ptr (C++11) default_delete (C++11) Allocators allocator allocator_traits (C++11) allocator_arg_t (C++11) allocator_arg (C++11) uses_allocator (C++11) uses_allocator_construction_args (C++20) make_obj_using_allocator (C++20) uninitialized_construct_using_allocator (C++20) scoped_allocator_adaptor (C++11) pmr::polymorphic_allocator (C++17) Memory resources pmr::memory_resource (C++17) pmr::get_default_resource (C++17) pmr::set_default_resource (C++17) pmr::new_delete_resource (C++17) pmr::null_memory_resource (C++17) pmr::synchronized_pool_resource (C++17) pmr::unsynchronized_pool_resource (C++17) pmr::monotonic_buffer_resource (C++17) pmr::pool_options (C++17) Uninitialized storage raw_storage_iterator (until C++20) get_temporary_buffer (until C++20) return_temporary_buffer (until C++20)

Uninitialized memory algorithms uninitialized_copy uninitialized_fill uninitialized_move (C++17) uninitialized_default_construct (C++17) uninitialized_value_construct (C++17) destroy (C++17) destroy_at (C++17) uninitialized_copy_n (C++11) uninitialized_fill_n uninitialized_move_n (C++17) uninitialized_default_construct_n (C++17) uninitialized_value_construct_n (C++17) destroy_n (C++17) construct_at (C++20) Constrained uninitialized memory algorithms ranges::uninitialized_copy (C++20) ranges::uninitialized_fill (C++20) ranges::uninitialized_move (C++20) ranges::uninitialized_default_construct (C++20) ranges::uninitialized_value_construct (C++20) ranges::destroy (C++20) ranges::destroy_at (C++20) ranges::uninitialized_copy_n (C++20) ranges::uninitialized_fill_n (C++20) ranges::uninitialized_move_n (C++20) ranges::uninitialized_default_construct_n (C++20) ranges::uninitialized_value_construct_n (C++20) ranges::destroy_n (C++20) ranges::construct_at (C++20) Garbage collection support declare_reachable (C++11) undeclare_reachable (C++11) declare_no_pointers (C++11) undeclare_no_pointers (C++11) pointer_safety (C++11) get_pointer_safety (C++11) Miscellaneous pointer_traits (C++11) to_address (C++20) addressof (C++11) align (C++11) assume_aligned (C++20) C Library malloc aligned_alloc (C++17) calloc realloc free Low level memory management

 

std::allocator

Member functions

allocator::allocator

allocator::~allocator

allocator::address (until C++20)

allocator::allocate

allocator::deallocate

allocator::max_size (until C++20)

allocator::construct (until C++20)

allocator::destroy (until C++20)

Non-member functions

operator==operator!= (until C++20)

 

Defined in header <memory>
template< class T > struct allocator;	(1)
template<> struct allocator<void>;	(2)	(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.

(until C++20)

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)(deprecated in C++20)	std::true_type

Member functions

(constructor)	creates a new allocator instance (public member function)
(destructor)	destructs an allocator instance (public member function)
address (deprecated in C++17)(removed in C++20)	obtains the address of an object, even if operator& is overloaded (public member function)
allocate	allocates uninitialized storage (public member function)
deallocate	deallocates storage (public member function)
max_size (deprecated in C++17)(removed in C++20)	returns the largest supported allocation size (public member function)
construct (deprecated in C++17)(removed in C++20)	constructs an object in allocated storage (public member function)
destroy (deprecated in C++17)(removed in C++20)	destructs an object in allocated storage (public member function)

Non-member functions

operator==operator!= (removed in C++20)

compares two allocator instances (public member function)

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::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 deprecated and its member constant value is true for any T.

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 (C++11)	provides information about allocator types (class template)
scoped_allocator_adaptor (C++11)	implements multi-level allocator for multi-level containers (class template)
uses_allocator (C++11)	checks if the specified type supports uses-allocator construction (class template)