[allocator.requirements.general]

Files changed (1) hide show

tmp/tmp83zx6ev4/{from.md → to.md} +512 -0

tmp/tmp83zx6ev4/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,512 @@

+##### General <a id="allocator.requirements.general">[[allocator.requirements.general]]</a>
+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`), string buffers and string streams
+[[input.output]], and `match_results` [[re]] are parameterized in terms
+of allocators.
+In subclause [[allocator.requirements]],
+- `T`, `U`, `C` denote any cv-unqualified object type
+  [[term.object.type]],
+- `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::pointer` obtained by calling
+  `a1.allocate`, where `a1 == a`,
+- `q` denotes a value of type `XX::const_pointer` obtained 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_pointer` obtained by conversion
+  from a value `p`,
+- `x` denotes a value of type `XX::const_void_pointer` obtained by
+  conversion from a value `q` or a value `w`,
+- `y` denotes a value of type `XX::const_void_pointer` obtained 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_traits` template, 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*]
+``` cpp
+typename X::pointer
+```
+*Remarks:* Default: `T*`
+``` cpp
+typename X::const_pointer
+```
+*Mandates:* `XX::pointer` is convertible to `XX::const_pointer`.
+*Remarks:* Default: `pointer_traits<XX::pointer>::rebind<const T>`
+``` cpp
+typename X::void_pointer
+typename 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>`
+``` cpp
+typename X::const_void_pointer
+typename Y::const_void_pointer
+```
+*Mandates:* `XX::pointer`, `XX::const_pointer`, and `XX::void_pointer`
+are convertible to `XX::const_void_pointer`. `XX::const_void_pointer`
+and `YY::const_void_pointer` are the same type.
+*Remarks:* Default: `pointer_traits<XX::pointer>::rebind<const void>`
+``` cpp
+typename X::value_type
+```
+*Result:* Identical to `T`.
+``` cpp
+typename X::size_type
+```
+*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>`
+``` cpp
+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`
+``` cpp
+typename X::template rebind<U>::other
+```
+*Result:* `Y`
+*Ensures:* For all `U` (including `T`), `YY::rebind_alloc<T>` is `X`.
+*Remarks:* If `Allocator` is a class template instantiation of the form
+`SomeAllocator<T, Args>`, where `Args` is zero or more type arguments,
+and `Allocator` does not supply a `rebind` member template, the standard
+`allocator_traits` template uses `SomeAllocator<U, Args>` in place of
+`Allocator::rebind<U>::other` by default. For allocator types that are
+not template instantiations of the above form, no default is provided.
+[*Note 1*: The member class template `rebind` of `X` is effectively a
+typedef template. In general, if the name `Allocator` is bound to
+`SomeAllocator<T>`, then `Allocator::rebind<U>::other` is the same type
+as `SomeAllocator<U>`, where `SomeAllocator<T>::value_type` is `T` and
+`SomeAllocator<U>::value_type` is `U`. — *end note*]
+``` cpp
+*p
+```
+*Result:* `T&`
+``` cpp
+*q
+```
+*Result:* `const T&`
+*Ensures:* `*q` refers to the same object as `*p`.
+``` cpp
+p->m
+```
+*Result:* Type of `T::m`.
+*Preconditions:* `(*p).m` is well-defined.
+*Effects:* Equivalent to `(*p).m`.
+``` cpp
+q->m
+```
+*Result:* Type of `T::m`.
+*Preconditions:* `(*q).m` is well-defined.
+*Effects:* Equivalent to `(*q).m`.
+``` cpp
+static_cast<XX::pointer>(w)
+```
+*Result:* `XX::pointer`
+*Ensures:* `static_cast<XX::pointer>(w) == p`.
+``` cpp
+static_cast<XX::const_pointer>(x)
+```
+*Result:* `XX::const_pointer`
+*Ensures:* `static_cast<XX::const_pointer>(x) == q`.
+``` cpp
+pointer_traits<XX::pointer>::pointer_to(r)
+```
+*Result:* `XX::pointer`
+*Ensures:* Same as `p`.
+``` cpp
+a.allocate(n)
+```
+*Result:* `XX::pointer`
+*Effects:* 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*]
+*Throws:* `allocate` may throw an appropriate exception.
+[*Note 2*: 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.
+``` cpp
+a.allocate(n, y)
+```
+*Result:* `XX::pointer`
+*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)`
+``` cpp
+a.allocate_at_least(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` `T` and 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}`.
+``` cpp
+a.deallocate(p, n)
+```
+*Result:* (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 `req` ≤ `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`.
+*Throws:* Nothing.
+``` cpp
+a.max_size()
+```
+*Result:* `XX::size_type`
+*Returns:* The largest value `n` that can meaningfully be passed to
+`a.allocate(n)`.
+*Remarks:* Default:
+`numeric_limits<size_type>::max() / sizeof(value_type)`
+``` cpp
+a1 == a2
+```
+*Result:* `bool`
+*Returns:* `true` only if storage allocated from each can be deallocated
+via the other.
+*Throws:* Nothing.
+*Remarks:* `operator==` shall be reflexive, symmetric, and transitive.
+``` cpp
+a1 != a2
+```
+*Result:* `bool`
+*Returns:* `!(a1 == a2)`.
+``` cpp
+a == b
+```
+*Result:* `bool`
+*Returns:* `a == YY::rebind_alloc<T>(b)`.
+``` cpp
+a != b
+```
+*Result:* `bool`
+*Returns:* `!(a == b)`.
+``` cpp
+X u(a);
+X u = a;
+```
+*Ensures:* `u == a`
+*Throws:* Nothing.
+``` cpp
+X u(b);
+```
+*Ensures:* `Y(u) == b` and `u == X(b)`.
+*Throws:* Nothing.
+``` cpp
+X u(std::move(a));
+X u = std::move(a);
+```
+*Ensures:* The value of `a` is unchanged and is equal to `u`.
+*Throws:* Nothing.
+``` cpp
+X u(std::move(b));
+```
+*Ensures:* `u` is equal to the prior value of `X(b)`.
+*Throws:* Nothing.
+``` cpp
+a.construct(c, args)
+```
+*Result:* (not used)
+*Effects:* Constructs an object of type `C` at `c`.
+*Remarks:* Default: `construct_at(c, std::forward<Args>(args)...)`
+``` cpp
+a.destroy(c)
+```
+*Result:* (not used)
+*Effects:* Destroys the object at `c`.
+*Remarks:* Default: `destroy_at(c)`
+``` cpp
+a.select_on_container_copy_construction()
+```
+*Result:* `X`
+*Returns:* Typically returns either `a` or `X()`.
+*Remarks:* Default: `return a;`
+``` cpp
+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 ([[cpp17.copyassignable]]) and the
+copy operation shall not throw exceptions.
+*Remarks:* Default: `false_type`
+``` cpp
+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 ([[cpp17.moveassignable]]) and the
+move operation shall not throw exceptions.
+*Remarks:* Default: `false_type`
+``` cpp
+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`
+``` cpp
+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) values `a1`, `a2` of type `X`.
+*Remarks:* Default: `is_empty<X>::type`
+An allocator type `X` shall meet the *Cpp17CopyConstructible*
+requirements ([[cpp17.copyconstructible]]). The `XX::pointer`,
+`XX::const_pointer`, `XX::void_pointer`, and `XX::const_void_pointer`
+types shall meet the *Cpp17NullablePointer* requirements (
+[[cpp17.nullablepointer]]). 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`,
+``` cpp
+addressof(*(p + n)) == addressof(*p) + n
+```
+is `true`.
+Let `x1` and `x2` denote objects of (possibly different) types
+`XX::void_pointer`, `XX::const_void_pointer`, `XX::pointer`, or
+`XX::const_pointer`. Then, `x1` and `x2` are *equivalently-valued*
+pointer values, if and only if both `x1` and `x2` can be explicitly
+converted to the two corresponding objects `px1` and `px2` of type
+`XX::const_pointer`, using a sequence of `static_cast`s using only these
+four types, and the expression `px1 == px2` evaluates to `true`.
+Let `w1` and `w2` denote objects of type `XX::void_pointer`. Then for
+the expressions
+``` cpp
+w1 == w2
+w1 != w2
+```
+either or both objects may be replaced by an equivalently-valued object
+of type `XX::const_void_pointer` with no change in semantics.
+Let `p1` and `p2` denote objects of type `XX::pointer`. Then for the
+expressions
+``` cpp
+p1 == p2
+p1 != p2
+p1 < p2
+p1 <= p2
+p1 >= p2
+p1 > p2
+p1 - p2
+```
+either or both objects may be replaced by an equivalently-valued object
+of type `XX::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 2*: Additionally, the member function `allocate` for that type
+can fail by throwing an object of type `bad_alloc`. — *end note*]
+[*Example 1*:
+The following is an allocator class template supporting the minimal
+interface that meets the requirements of
+[[allocator.requirements.general]]:
+``` cpp
+template<class T>
+struct SimpleAllocator {
+  using value_type = T;
+  SimpleAllocator(ctor args);
+  template<class U> SimpleAllocator(const SimpleAllocator<U>& other);
+  T* allocate(std::size_t n);
+  void deallocate(T* p, std::size_t n);
+  template<class U> bool operator==(const SimpleAllocator<U>& rhs) const;
+};
+```
+— *end example*]

Diff to HTML by rtfpessoa