C++ concepts: AllocatorAwareContainer

An AllocatorAwareContainer is a Container that holds an instance of an Allocator and uses that instance to allocate and deallocate memory in all of its member functions.

The following rules apply to object construction.

• Copy constructors of AllocatorAwareContainers obtain their instances of the allocator by calling std::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 an allocator parameter.

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

• Copy-assignment will replace the allocator only if std::allocator_traits<allocator_type>::propagate_on_container_copy_assignment::value is true
• Move-assignment will replace the allocator only if std::allocator_traits<allocator_type>::propagate_on_container_move_assignment::value is true
• Swap will replace the allocator only if std::allocator_traits<allocator_type>::propagate_on_container_swap::value is true. Specifically, it will exchange the allocator instances through an unqualified call to the non-member function swap, see Swappable.

Note: swapping two containers with unequal allocators if propagate_on_container_swap is false is undefined behavior.

• The accessor get_allocator() obtains a copy of the allocator that was used to construct the container or installed by the most recent allocator replacement operation.

Requirements

Legend
X	Container type
T	Element type
A	Allocator for T
a, b	Objects of type X (non-const lvalue)
t	Object of type X (lvalue or const rvalue)
rv	Object of type X (non-const rvalue)
m	Object of type A
Q	Allocator type

expression	return type	pre/requirements	post/effects	complexity
allocator_type	A	allocator_type::value_type must be the same as X::value_type		compile-time
get_allocator()	A			constant
X u;		A is DefaultConstructible	u.empty() == true && u.get_allocator() == A()	constant
X u(m);			u.empty() == true && u.get_allocator() == m	constant
X u(t,m);		T is CopyInsertable into X	u == t && u.get_allocator() == m	linear
X u(rv);		Move constructor of A must not throw exceptions	u has the same elements and an equal allocator as rv had before the construction	constant
X u(rv,m);		T is MoveInsertable into X	The elements of u are the same or copies of those of rv and u.get_allocator() == m	constant if m == rv.get_allocator(), otherwise linear
a = t	X&	T is CopyInsertable into X and CopyAssignable	a == t	linear
a = rv	X&	If the allocator will not be replaced by move-assignment (see above), then T is MoveInsertable into X and MoveAssignable	All existing elements of a are either move assigned to or destroyed; a is equal to the value that rv had before the assignment	linear
a.swap(b)	void		Exchanges the contents of a and b	constant

Concept requirements

A

• DefaultConstructible

T

• CopyInsertable

X

• CopyAssignable

Standard library

All standard library containers except std::array are AllocatorAwareContainers:

• std::basic_string
• std::deque
• std::forward_list
• std::list
• std::vector
• std::map
• std::multimap
• std::set
• std::multiset
• std::unordered_map
• std::unordered_multimap
• std::unordered_set
• std::unordered_multiset