Difference between revisions of "cpp/named req/AllocatorAwareContainer"
(Translation goes to the wrong place.) |
m (→Standard library: P0843) |
||
| (One intermediate revision by one user not shown) | |||
| Line 70: | Line 70: | ||
|- | |- | ||
|Postcondition | |Postcondition | ||
| − | |{{c|1=u == t}} and {{c|1=u.get_allocator() == | + | |{{c|1=u == t}} and {{c|1=u.get_allocator() == m}} are both {{c|true}}. |
|- | |- | ||
|{{c|X u(rv);}} | |{{c|X u(rv);}} | ||
| Line 136: | Line 136: | ||
===Standard library=== | ===Standard library=== | ||
| − | All standard library containers except {{lc|std::array}} are {{named req/core|AllocatorAwareContainer}}s: | + | All standard library string types and containers (except {{lc|std::array}} and {{lc|std::inplace_vector}}) are {{named req/core|AllocatorAwareContainer}}s: |
* {{lc|std::basic_string}} | * {{lc|std::basic_string}} | ||
* {{lc|std::deque}} | * {{lc|std::deque}} | ||
Latest revision as of 22:18, 3 August 2024
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), except that std::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 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: The behavior of swapping two containers with unequal allocators if propagate_on_container_swap is false is undefined.
- 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.
Contents |
[edit] Requirements
A type satisfies AllocatorAwareContainer if it satisfies Container and, given the following types and values, the semantic and complexity requirements in the tables below are satisfied:
| Type | Definition |
X
|
an AllocatorAwareContainer type |
T
|
the value_type of X
|
A
|
the allocator type used by X
|
| Value | Definition |
| a, b | non-const lvalues of type X
|
| c | an lvalue of type const X |
| t | an lvalue or a const rvalue of type X
|
| rv | a non-const rvalue of type X
|
| m | a value of type A
|
[edit] Types
| Name | Type | Requirement |
|---|---|---|
| typename X::allocator_type | A
|
X::allocator_type::value_type and X::value_type are the same.
|
[edit] Statements
| Statement | Semantics | Complexity | |
|---|---|---|---|
| X u; X u = X(); |
Precondition | A is DefaultConstructible.
|
Constant |
| Postcondition | u.empty() and u.get_allocator() == A() are both true. | ||
| X u(m); | Postcondition | u.empty() and u.get_allocator() == m are both true. | Constant |
| X u(t, m); | Precondition | T is CopyInsertable into X.
|
Linear |
| Postcondition | u == t and u.get_allocator() == m are both true. | ||
| X u(rv); | Postcondition |
|
Constant |
| X u(rv, m); | Precondition | T is MoveInsertable into X.
|
|
| Postcondition |
| ||
[edit] Expressions
| Expression | Type | Semantics | Complexity | |
|---|---|---|---|---|
| c.get_allocator() | A
|
No direct semantic requirement. | Constant | |
| a = t | X&
|
Precondition | T is CopyInsertable into X and CopyAssignable.
|
Linear |
| Postcondition | a == t is true. | |||
| a = rv | X&
|
Precondition | If the allocator will not be replaced by move-assignment (see above), then T is MoveInsertable into X and MoveAssignable.
|
Linear |
| Effect | All existing elements of a are either move assigned to or destroyed. | |||
| Postcondition | If a and rv do not refer the same object, a is equal to the value that rv had before the assignment. | |||
| a.swap(b) | void | Effect | Exchanges the contents of a and b. | Constant |
[edit] 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)(until C++20)std::allocator has no construct member and std::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 (except std::array and std::inplace_vector) 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
[edit] 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 unspecified |
