[allocator.requirements] (original) (raw)

16.4.4.6.1 General [allocator.requirements.general]

The library describes a standard set of requirements for allocators, which are class-type objects that encapsulate the information about an allocation model.

This information includes the knowledge of pointer types, the type of their difference, the type of the size of objects in this allocation model, as well as the memory allocation and deallocation primitives for it.

All of the string types ([strings]), containers ([containers]) (except array and inplace_vector), string buffers and string streams ([input.output]), andmatch_results are parameterized in terms of allocators.

In [allocator.requirements],

T, U, C denote any cv-unqualified object type ([basic.types.general]),
X denotes an allocator class for type T,
Y denotes the corresponding allocator class for type U,
XX denotes the type allocator_traits<X>,
YY denotes the type allocator_traits<Y>,
a, a1, a2 denote lvalues of type X,
u denotes the name of a variable being declared,
b denotes a value of type Y,
c denotes a pointer of type C*through which indirection is valid,
p denotes a value of type XX::pointerobtained by calling a1.allocate, where a1 == a,
q denotes a value of type XX::const_pointerobtained by conversion from a value p,
r denotes a value of type T&obtained by the expression *p,
w denotes a value of type XX::void_pointerobtained by conversion from a value p,
x denotes a value of type XX::const_void_pointerobtained by conversion from a value q or a value w,
y denotes a value of type XX::const_void_pointerobtained by conversion from a result value of YY::allocate, or else a value of type (possibly const) std::nullptr_t,
n denotes a value of type XX::size_type,
Args denotes a template parameter pack, and
args denotes a function parameter pack with the pattern Args&&.

The class template allocator_traits ([allocator.traits]) supplies a uniform interface to all allocator types.

This subclause describes the requirements on allocator types and thus on types used to instantiate allocator_traits.

A requirement is optional if a default for a given type or expression is specified.

Within the standard library allocator_traitstemplate, an optional requirement that is not supplied by an allocator is replaced by the specified default type or expression.

[Note 1:

There are no program-defined specializations of allocator_traits.

— _end note_]

typename X::const_pointer

Mandates: XX::pointer is convertible to XX::const_pointer.

Remarks: Default: pointer_traits<XX::pointer>::rebind<const T>

typename X::void_pointertypename Y::void_pointer

Mandates: XX::pointer is convertible to XX::void_pointer.

XX::void_pointer and YY::void_pointer are the same type.

Remarks: Default:pointer_traits<XX::pointer>::rebind<void>

typename X::const_void_pointertypename Y::const_void_pointer

Mandates: XX::pointer, XX::const_pointer, and XX::void_pointerare convertible to XX::const_void_pointer.

XX::const_void_pointer and YY::const_void_pointerare the same type.

Remarks: Default:pointer_traits<XX::pointer>::rebind<const void>

Result: An unsigned integer type that can represent the size of the largest object in the allocation model.

Remarks: Default:make_unsigned_t<XX::difference_type>

typename X::difference_type

Result: A signed integer type that can represent the difference between any two pointers in the allocation model.

Remarks: Default:pointer_traits<XX::pointer>::difference_type

typename X::rebind::other

Postconditions: For all U (including T),YY::rebind_alloc<T> is X.

Remarks: If Allocator is a class template instantiation of the formSomeAllocator<T, Args>, where Args is zero or more type arguments, and Allocator does not supply a rebind member template, the standard allocator_traits template usesSomeAllocator<U, Args> in place of Allocator::rebind::otherby default.

For allocator types that are not template instantiations of the above form, no default is provided.

[Note 2:

The member class template rebind of X is effectively a typedef template.

In general, if the name Allocator is bound to SomeAllocator<T>, thenAllocator::rebind::other is the same type asSomeAllocator, whereSomeAllocator<T>::value_type is T andSomeAllocator::value_type is U.

— _end note_]

Postconditions: *q refers to the same object as *p.

Preconditions: (*p).m is well-defined.

Effects: Equivalent to (*p).m.

Preconditions: (*q).m is well-defined.

Effects: Equivalent to (*q).m.

static_cast<XX::pointer>(w)

Postconditions: static_cast<XX::pointer>(w) == p.

static_cast<XX::const_pointer>(x)

Result: XX::const_pointer

Postconditions: static_cast<XX::const_pointer>(x) == q.

pointer_traits<XX::pointer>::pointer_to(r)

Postconditions: Same as p.

Effects: Memory is allocated for an array of n Tand 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_]

Throws: allocate may throw an appropriate exception.

[Note 3:

It is intended that a.allocate be an efficient means of allocating a single object of type T, even when sizeof(T)is small.

That is, there is no need for a container to maintain its own free list.

— _end note_]

Remarks: If n == 0, the return value is unspecified.

Effects: Same as a.allocate(n).

The use of y is unspecified, but it is intended as an aid to locality.

Remarks: Default: a.allocate(n)

Result: allocation_result<XX::pointer, XX::size_type>

Returns: allocation_result<XX::pointer, XX::size_type>{ptr, count}where ptr is memory allocated for an array of count Tand such an object is created but array elements are not constructed, such that count ≥ n.

If n == 0, the return value is unspecified.

Throws: allocate_at_least may throw an appropriate exception.

Remarks: Default: {a.allocate(n), n}.

Preconditions:

If p is memory that was obtained by a call to a.allocate_at_least, let ret be the value returned andreq be the value passed as the first argument of that call.
p is equal to ret.ptr andn is a value such thatreq ≤ n ≤ ret.count.
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.

Returns: The largest value n that can meaningfully be passed to a.allocate(n).

Remarks: Default:numeric_limits<size_type>::max() / sizeof(value_type)

Returns: true only if storage allocated from each can be deallocated via the other.

Remarks: operator== shall be reflexive, symmetric, and transitive.

Returns: a == YY::rebind_alloc<T>(b).

Postconditions: Y(u) == b and u == X(b).

X u(std::move(a)); X u = std::move(a);

Postconditions: The value of a is unchanged and is equal to u.

Postconditions: u is equal to the prior value of X(b).

Effects: Constructs an object of type C at c.

Remarks: Default:construct_at(c, std::forward<Args>(args)...)

Effects: Destroys the object at c.

Remarks: Default: destroy_at(c)

a.select_on_container_copy_construction()

Returns: Typically returns either a or X().

Remarks: Default: return a;

typename X::propagate_on_container_copy_assignment

Result: Identical to or derived from true_type or false_type.

Returns: true_type only if an allocator of type X should be copied when the client container is copy-assigned; if so, X shall meet the Cpp17CopyAssignable requirements (Table 34) and the copy operation shall not throw exceptions.

Remarks: Default: false_type

typename X::propagate_on_container_move_assignment

Result: Identical to or derived from true_type or false_type.

Returns: true_type only if an allocator of type X should be moved when the client container is move-assigned; if so, X shall meet the Cpp17MoveAssignable requirements (Table 33) and the move operation shall not throw exceptions.

Remarks: Default: false_type

typename X::propagate_on_container_swap

Result: Identical to or derived from true_type or false_type.

Returns: true_type only if an allocator of type X should be swapped when the client container is swapped; if so,X shall meet the Cpp17Swappable requirements ([swappable.requirements]) and the swap operation shall not throw exceptions.

Remarks: Default: false_type

typename X::is_always_equal

Result: Identical to or derived from true_type or false_type.

Returns: true_type only if the expression a1 == a2 is guaranteed to be true for any two (possibly const) valuesa1, a2 of type X.

Remarks: Default: is_empty<X>::type

The XX::pointer, XX::const_pointer, XX::void_pointer, andXX::const_void_pointer types shall meet the_Cpp17NullablePointer_ requirements (Table 36).

No constructor, comparison operator function, copy operation, move operation, or swap operation on these pointer types shall exit via an exception.

XX::pointer and XX::const_pointer shall also meet the requirements for a Cpp17RandomAccessIterator ([random.access.iterators]) and the additional requirement that, when p and (p + n) are dereferenceable pointer values for some integral value n,addressof(*(p + n)) == addressof(*p) + nis true.

Let x1 and x2 denote objects of (possibly different) typesXX::void_pointer, XX::const_void_pointer, XX::pointer, or XX::const_pointer.

Then, x1 and x2 areequivalently-valued pointer values, if and only if both x1 and x2can be explicitly converted to the two corresponding objects px1 and px2of type XX::const_pointer, using a sequence of static_casts using only these four types, and the expression px1 == px2evaluates to true.

Let w1 and w2 denote objects of type XX::void_pointer.

Then for the expressionsw1 == w2 w1 != w2either or both objects may be replaced by an equivalently-valued object of typeXX::const_void_pointer with no change in semantics.

Let p1 and p2 denote objects of type XX::pointer.

Then for the expressionsp1 == p2 p1 != p2 p1 < p2 p1 <= p2 p1 >= p2 p1 > p2 p1 - p2either or both objects may be replaced by an equivalently-valued object of typeXX::const_pointer with no change in semantics.

An allocator may constrain the types on which it can be instantiated and the arguments for which its construct or destroy members may be called.

If a type cannot be used with a particular allocator, the allocator class or the call to construct or destroy may fail to instantiate.

If the alignment associated with a specific over-aligned type is not supported by an allocator, instantiation of the allocator for that type may fail.

The allocator also may silently ignore the requested alignment.

[Note 4:

Additionally, the member function allocatefor that type can fail by throwing an object of typebad_alloc.

— _end note_]

[Example 2:

The following is an allocator class template supporting the minimal interface that meets the requirements of [allocator.requirements.general]:template<class T> struct SimpleAllocator { using value_type = T; SimpleAllocator(ctor args);template<class U> SimpleAllocator(const SimpleAllocator& other); T* allocate(std::size_t n);void deallocate(T* p, std::size_t n);template<class U> bool operator==(const SimpleAllocator& rhs) const;};

— _end example_]

The following exposition-only concept defines the minimal requirements on an Allocator type.

template<class Alloc> concept simple-allocator = requires(Alloc alloc, size_t n) { { *alloc.allocate(n) } -> same_as<typename Alloc::value_type&>;{ alloc.deallocate(alloc.allocate(n), n) };} && copy_constructible<Alloc> && equality_comparable<Alloc>;

A type Alloc models simple-allocatorif it meets the requirements of [allocator.requirements.general].

16.4.4.6.2 Allocator completeness requirements [allocator.requirements.completeness]

If X is an allocator class for type T,X additionally meets the allocator completeness requirements if, whether or not T is a complete type:

X is a complete type, and
all the member types of allocator_traits other than value_type are complete types.