24 Containers library [containers]

24.2 Requirements [container.requirements]

24.2.2 General containers [container.requirements.general]

24.2.2.5 Allocator-aware containers [container.alloc.reqmts]

1
#
All of the containers defined in [containers] and in [basic.string] except array meet the additional requirements of an allocator-aware container, as described below.
2
#
Given an allocator type A and given a container type X having a value_type identical to T and an allocator_type identical to allocator_traits<A>​::​rebind_alloc<T> and given an lvalue m of type A, a pointer p of type T*, an expression v of type T or const T, and an rvalue rv of type T, the following terms are defined.
If X is not allocator-aware or is a specialization of basic_string, the terms below are defined as if A were allocator<T> — no allocator object needs to be created and user specializations of allocator<T> are not instantiated:
  • (2.1)
    T is Cpp17DefaultInsertable into X means that the following expression is well-formed: allocator_traits<A>::construct(m, p)
  • (2.2)
    An element of X is default-inserted if it is initialized by evaluation of the expression allocator_traits<A>::construct(m, p) where p is the address of the uninitialized storage for the element allocated within X.
  • (2.3)
    T is Cpp17MoveInsertable into X means that the following expression is well-formed: allocator_traits<A>::construct(m, p, rv) and its evaluation causes the following postcondition to hold: The value of *p is equivalent to the value of rv before the evaluation.
    [Note 1: 
    rv remains a valid object.
    Its state is unspecified
    — end note]
  • (2.4)
    T is Cpp17CopyInsertable into X means that, in addition to T being Cpp17MoveInsertable into X, the following expression is well-formed: allocator_traits<A>::construct(m, p, v) and its evaluation causes the following postcondition to hold: The value of v is unchanged and is equivalent to *p.
  • (2.5)
    T is Cpp17EmplaceConstructible into X from args, for zero or more arguments args, means that the following expression is well-formed: allocator_traits<A>::construct(m, p, args)
  • (2.6)
    T is Cpp17Erasable from X means that the following expression is well-formed: allocator_traits<A>::destroy(m, p)
[Note 2: 
A container calls allocator_traits<A>​::​construct(m, p, args) to construct an element at p using args, with m == get_allocator().
The default construct in allocator will call ​::​new((void*)p) T(args), but specialized allocators can choose a different definition.
— end note]
3
#
In this subclause,
  • (3.1)
    X denotes an allocator-aware container class with a value_type of T using an allocator of type A,
  • (3.2)
    u denotes a variable,
  • (3.3)
    a and b denote non-const lvalues of type X,
  • (3.4)
    c denotes an lvalue of type const X,
  • (3.5)
    t denotes an lvalue or a const rvalue of type X,
  • (3.6)
    rv denotes a non-const rvalue of type X, and
  • (3.7)
    m is a value of type A.
A type X meets the allocator-aware container requirements if X meets the container requirements and the following types, statements, and expressions are well-formed and have the specified semantics.
🔗
typename X::allocator_type
4
#
Result: A
5
#
Mandates: allocator_type​::​value_type is the same as X​::​value_type.
🔗
c.get_allocator()
6
#
Result: A
7
#
Complexity: Constant.
🔗
X u; X u = X();
8
#
Preconditions: A meets the Cpp17DefaultConstructible requirements.
9
#
Postconditions: u.empty() returns true, u.get_allocator() == A().
10
#
Complexity: Constant.
🔗
X u(m);
11
#
Postconditions: u.empty() returns true, u.get_allocator() == m.
12
#
Complexity: Constant.
🔗
X u(t, m);
13
#
Preconditions: T is Cpp17CopyInsertable into X.
14
#
Postconditions: u == t, u.get_allocator() == m
15
#
Complexity: Linear.
🔗
X u(rv);
16
#
Postconditions: u has the same elements as rv had before this construction; the value of u.get_allocator() is the same as the value of rv.get_allocator() before this construction.
17
#
Complexity: Constant.
🔗
X u(rv, m);
18
#
Preconditions: T is Cpp17MoveInsertable into X.
19
#
Postconditions: u has the same elements, or copies of the elements, that rv had before this construction, u.get_allocator() == m.
20
#
Complexity: Constant if m == rv.get_allocator(), otherwise linear.
🔗
a = t
21
#
Result: X&.
22
#
Preconditions: T is Cpp17CopyInsertable into X and Cpp17CopyAssignable.
23
#
Postconditions: a == t is true.
24
#
Complexity: Linear.
🔗
a = rv
25
#
Result: X&.
26
#
Preconditions: If allocator_traits<allocator_type>​::​propagate_on_container_move_assignment​::​value is false, T is Cpp17MoveInsertable into X and Cpp17MoveAssignable.
27
#
Effects: All existing elements of a are either move assigned to or destroyed.
28
#
Postconditions: If a and rv do not refer to the same object, a is equal to the value that rv had before this assignment.
29
#
Complexity: Linear.
🔗
a.swap(b)
30
#
Result: void
31
#
Effects: Exchanges the contents of a and b.
32
#
Complexity: Constant.