16 Library introduction [library]

16.4 Library-wide requirements [requirements]

16.4.4 Requirements on types and expressions [utility.requirements]

16.4.4.6 Cpp17Allocator requirements [allocator.requirements]

16.4.4.6.1 General [allocator.requirements.general]

Table 38: Cpp17Allocator requirements [tab:cpp17.allocator]
Expression
Return type
Assertion/note
Default
pre-/post-condition
X​::​pointer
T*
X​::​const_­pointer
X​::​pointer is convertible to X​::​const_­pointer
pointer_­traits<X​::​​pointer>​::​​rebind<const T>
X​::​void_­pointer
Y​::​void_­pointer
X​::​pointer is convertible to X​::​void_­pointer.
X​::​void_­pointer and Y​::​void_­pointer are the same type.
pointer_­traits<X​::​​pointer>​::​​rebind<void>
X​::​const_­void_­pointer
Y​::​const_­void_­pointer
X​::​pointer, X​::​const_­pointer, and X​::​void_­pointer are convertible to X​::​const_­void_­pointer.
X​::​const_­void_­pointer and Y​::​const_­void_­pointer are the same type.
pointer_­traits<X​::​​pointer>​::​​rebind<const void>
X​::​value_­type
Identical to T
X​::​size_­type
unsigned integer type
a type that can represent the size of the largest object in the allocation model
make_­unsigned_­t<X​::​​difference_­type>
X​::​difference_­type
signed integer type
a type that can represent the difference between any two pointers in the allocation model
pointer_­traits<X​::​​pointer>​::​​difference_­type
typename X​::​template rebind<U>​::​other
Y
For all U (including T), Y​::​template rebind<T>​::​other is X.
See Note A, below.
*p
T&
*q
const T&
*q refers to the same object as *p.
p->m
type of T​::​m
Preconditions: (*p).m is well-defined.

equivalent to (*p).m
q->m
type of T​::​m
Preconditions: (*q).m is well-defined.

equivalent to (*q).m
static_­cast<​X​::​pointer​>(w)
X​::​pointer
static_­cast<X​::​pointer>(w) == p
static_­cast<​X​::​const_­pointer​>(x)
X​::​const_­pointer
static_­cast< X​::​const_­pointer​>(x) == q
pointer_­traits<​X​::​pointer​>​::​pointer_­to(r)
X​::​pointer
same as p
a.allocate(n)
X​::​pointer
Memory is allocated for an array of n T and such an object is created but array elements are not constructed.
[Example 1:
When reusing storage denoted by some pointer value p, launder(reinterpret_­cast<T*>(new (p) byte[n * sizeof(T)])) can be used to implicitly create a suitable array object and obtain a pointer to it.
— end example]
allocate may throw an appropriate exception.162
See Note C, below.
a.allocate(n, y)
X​::​pointer
Same as a.allocate(n).
The use of y is unspecified, but it is intended as an aid to locality.
a.allocate(n)
a.allocate_­at_­least(n)
allocation_­result<X​::​pointer>
Returns: allocation_­result<X​::​pointer>{ptr, count} where ptr is memory allocated for an array of count T and such an object is created but array elements are not constructed, such that .
allocate_­at_­least may throw an appropriate exception.
See Note C, below.
See Note D, below.
a.deallocate(p,n)
(not used)
Preconditions:
  • If p is memory that was obtained by a call to a.allocate_­at_­least, let ret be the value returned and req be the value passed as the first argument of that call.
    p is equal to ret.ptr and n is a value such that .
  • Otherwise, p is a pointer value obtained from allocate.
    n equals the value passed as the first argument to the invocation of allocate which returned p.
p has not been invalidated by an intervening call to deallocate.

Throws: Nothing.
a.max_­size()
X​::​size_­type
the largest value that can meaningfully be passed to X​::​allocate()
numeric_­limits<size_­type>​::​max() / sizeof(value_­type)
a1 == a2
bool
Returns true only if storage allocated from each can be deallocated via the other.
operator== shall be reflexive, symmetric, and transitive, and shall not exit via an exception.
a1 != a2
bool
same as !(a1 == a2)
a == b
bool
same as a == Y​::​rebind<T>​::​other(b)
a != b
bool
same as !(a == b)
X u(a);
X u = a;
Shall not exit via an exception.

Postconditions: u == a
X u(b);
Shall not exit via an exception.

Postconditions: Y(u) == b, u == X(b)
X u(std​::​move(a));
X u = std​::​move(a);
Shall not exit via an exception.

Postconditions: The value of a is unchanged and is equal to u.
X u(std​::​move(b));
Shall not exit via an exception.

Postconditions: u is equal to the prior value of X(b).
a.construct(c, args)
(not used)
Effects: Constructs an object of type C at c.
construct_­at(c, std​::​​forward<Args>(args)...)
a.destroy(c)
(not used)
Effects: Destroys the object at c
destroy_­at(c)
a.select_­on_­container_­copy_­construction()
X
Typically returns either a or X().
return a;
X​::​propagate_­on_­container_­copy_­assignment
Identical to or derived from true_­type or false_­type
true_­type only if an allocator of type X should be copied when the client container is copy-assigned.
See Note B, below.
false_­type
X​::​propagate_­on_­container_­move_­assignment
Identical to or derived from true_­type or false_­type
true_­type only if an allocator of type X should be moved when the client container is move-assigned.
See Note B, below.
false_­type
X​::​propagate_­on_­- container_­swap
Identical to or derived from true_­type or false_­type
true_­type only if an allocator of type X should be swapped when the client container is swapped.
See Note B, below.
false_­type
X​::​is_­always_­equal
Identical to or derived from true_­type or false_­type
true_­type only if the expression a1 == a2 is guaranteed to be true for any two (possibly const) values a1, a2 of type X.
is_­empty<X>​::​​type