C++ named requirements: AllocatorAwareContainer

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General 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)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

C++ named requirements

Basic DefaultConstructible MoveConstructible (C++11) CopyConstructible CopyAssignable MoveAssignable (C++11) Destructible Type properties ScalarType PODType TriviallyCopyable (C++11) TrivialType (C++11) StandardLayoutType (C++11)   ImplicitLifetimeType Library-wide BooleanTestable EqualityComparable LessThanComparable Swappable ValueSwappable (C++11) NullablePointer (C++11) Hash (C++11) Allocator FunctionObject Callable Predicate BinaryPredicate Compare

Container Container ReversibleContainer AllocatorAwareContainer SequenceContainer ContiguousContainer (C++17) AssociativeContainer UnorderedAssociativeContainer (C++11)   Container element DefaultInsertable (C++11) CopyInsertable (C++11) MoveInsertable (C++11) EmplaceConstructible (C++11) Erasable (C++11) Iterator LegacyIterator LegacyInputIterator LegacyOutputIterator LegacyForwardIterator LegacyBidirectionalIterator LegacyRandomAccessIterator LegacyContiguousIterator (C++17) ConstexprIterator (C++20) Stream I/O FormattedInputFunction UnformattedInputFunction FormattedOutputFunction UnformattedOutputFunction Formatters BasicFormatter (C++20) Formatter (C++20)

Random Numbers SeedSequence (C++11) RandomNumberEngine (C++11) RandomNumberDistribution (C++11) UniformRandomBitGenerator (C++11) RandomNumberEngineAdaptor (C++11) Concurrency BasicLockable (C++11) Lockable (C++11) TimedLockable (C++11) SharedLockable (C++14) SharedTimedLockable (C++14) Mutex (C++11) TimedMutex (C++11) SharedMutex (C++17) SharedTimedMutex (C++14) Ranges RangeAdaptorObject (C++20) RangeAdaptorClosureObject (C++20) Multidimensional View LayoutMapping (C++23) LayoutMappingPolicy (C++23) AccessorPolicy (C++23) Other CharTraits RegexTraits (C++11)   BitmaskType LiteralType (C++11) NumericType UnaryTypeTrait (C++11) BinaryTypeTrait (C++11) TransformationTrait (C++11) Clock (C++11) TrivialClock (C++11)

 

An AllocatorAwareContainer is a Container that holds an instance of an Allocator 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).

The following rules apply to container 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 a const allocator_type& 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; if a and rv do not refer the same object, 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

Notes

Allocator-aware containers always call std::allocator_traits<A>::construct(m, p, args) to construct an object of type T at p using args, with m == get_allocator(). The default construct in std::allocator calls ::new((void*)p) T(args), but specialized allocators may choose a different definition

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

Defect reports

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

DR	Applied to	Behavior as published	Correct behavior
LWG 2839	C++11	self move assignment of standard containers was not allowed	allowed but the result is unspecifed