Difference between revisions of "cpp/named req/AllocatorAwareContainer"

Revision as of 18:10, 20 March 2014

An Template:concept is a Template:concept that holds an instance of an Template:concept 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 Template:concepts 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 Template:concept.

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.

expression	return type	pre/requirements	post/effects	complexity
allocator_type	`A`	allocator_type::value_type must be the same as X::value_type		constant
get_allocator()	`A`			constant
X u;		`A` is Template:concept	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 Template:concept 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 Template:concept 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 Template:concept into `X` and Template:concept	a == t	linear
a = rv	X&	If the allocator will not be replaced by move-assignment (see above), then `T` is Template:concept into `X` and Template:concept	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

All standard library containers except std::array are Template:concepts:

@@ Line 6: / Line 6: @@
 The following rules apply to object construction
-* Copy constructors of {{concept|AllocatorAwareContainer}}s obtain their instances of the allocator by calling {{c|std::allocator_traits<allocator_type>::select_on_container_copy_construction}}.
+* Copy constructors of {{concept|AllocatorAwareContainer}}s obtain their instances of the allocator by calling {{c|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.

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