cppdraft_translate/cppdraft/container/alloc/reqmts.md

[container.alloc.reqmts]

23 Containers library [containers]

23.2 Requirements [container.requirements]

23.2.2 General containers [container.requirements.general]

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

1

#

Except for array and inplace_vector, all of the containers defined in [containers],[stacktrace.basic], [basic.string], and [re.results] 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​::​rebind_alloc and given an lvalue m of type A, a pointer p of type T*, an expression v that denotes an lvalue of type T or const T or an rvalue of type 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 wereallocator — no allocator object needs to be created and user specializations of allocator are not instantiated:

• (2.1)

T is Cpp17DefaultInsertable into X means that the following expression is well-formed:allocator_traits::construct(m, p)

• (2.2)

An element of X is default-inserted if it is initialized by evaluation of the expressionallocator_traits::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::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 intoX, the following expression is well-formed:allocator_traits::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 isCpp17EmplaceConstructible into X from args, for zero or more arguments args, means that the following expression is well-formed:allocator_traits::construct(m, p, args)

• (2.6)

T isCpp17Erasable from X means that the following expression is well-formed:allocator_traits::destroy(m, p)

[Note 2:

A container calls allocator_traits​::​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 andCpp17CopyAssignable.

23

#

Postconditions: a == t is true.

24

#

Complexity: Linear.

🔗

a = rv

25

#

Result: X&.

26

#

Preconditions: Ifallocator_traits<allocator_type>​::​propagate_on_container_move_assignment​::​value is false,T is Cpp17MoveInsertable into X andCpp17MoveAssignable.

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.