AnAllocatorAwareContainer is aContainer that holds an instance of anAllocator and uses that instance in all its member functions to allocate and deallocate memory and to construct and destroy objects in that memory (such objects may be container elements, nodes, or, for unordered containers, bucket arrays), except thatstd::basic_string specializations do not use the allocators for construction/destruction of their elements(since C++23).

The following rules apply to container construction:

• Copy constructors ofAllocatorAwareContainers obtain their instances of the allocator by callingstd::allocator_traits<allocator_type>::select_on_container_copy_construction on the allocator of the container being copied.
• Move constructors obtain their instances of allocators by move-constructing from the allocator belonging to the old container.
• All other constructors take aconst allocator_type& parameter.

The only way to replace an allocator is copy-assignment, move-assignment, and swap:

• Copy-assignment will replace the allocator only ifstd::allocator_traits<allocator_type>::propagate_on_container_copy_assignment::value istrue.
• Move-assignment will replace the allocator only ifstd::allocator_traits<allocator_type>::propagate_on_container_move_assignment::value istrue.
• Swap will replace the allocator only ifstd::allocator_traits<allocator_type>::propagate_on_container_swap::value istrue. Specifically, it will exchange the allocator instances through an unqualified call to the non-member function swap, seeSwappable. If swap does not propagate the allocator, swapping two containers with unequal allocators is undefined behavior.
• The accessorget_allocator() obtains a copy of the allocator that was used to construct the container or installed by the most recent allocator replacement operation.

The only exception isstd::basic_string<CharT,Traits,Allocator>::assign, which may also propagate the allocator.

[edit]Requirements

A type satisfiesAllocatorAwareContainer if it satisfiesContainer and, given the following types and values, the semantic and complexity requirements in the tables below are satisfied:

[edit]Types

[edit]Statements

[edit]Expressions

[edit]Notes

AllocatorAwareContainers always callstd::allocator_traits<A>::construct(m, p, args) to construct an object of typeT atp usingargs, withm== get_allocator().The defaultconstruct instd::allocator calls::new((void*)p) T(args)(until C++20)std::allocator has noconstruct member andstd::construct_at(p, args) is called when constructing elements(since C++20), but specialized allocators may choose a different definition.

[edit]Standard library

All standard library string types and containers (exceptstd::array andstd::inplace_vector) areAllocatorAwareContainers:

[edit]Defect reports

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

• In other languages

• Deutsch
• Español
• 日本語
• Русский
• 中文