20 General utilities library [utilities]

The class template pointer_traits supplies a uniform interface to certain attributes of pointer-like types.

namespace std { template<class Ptr> struct pointer_traits { using pointer = Ptr; using element_type = see below; using difference_type = see below; template<class U> using rebind = see below; static pointer pointer_to(see below r); }; template<class T> struct pointer_traits<T*> { using pointer = T*; using element_type = T; using difference_type = ptrdiff_t; template<class U> using rebind = U*; static constexpr pointer pointer_to(see below r) noexcept; }; }

20.10.3.2 Member types [pointer.traits.types]

using element_type = see below;

Type: Ptr::element_type if the qualified-id Ptr::element_type is valid and denotes a type ([temp.deduct]); otherwise, T if Ptr is a class template instantiation of the form SomePointer<T, Args>, where Args is zero or more type arguments; otherwise, the specialization is ill-formed.

using difference_type = see below;

Type: Ptr::difference_type if the qualified-id Ptr::difference_type is valid and denotes a type ([temp.deduct]); otherwise, ptrdiff_t.

template<class U> using rebind = see below;

Alias template: Ptr::rebind if the qualified-id Ptr::rebind is valid and denotes a type ([temp.deduct]); otherwise, SomePointer<U, Args> if Ptr is a class template instantiation of the form SomePointer<T, Args>, where Args is zero or more type arguments; otherwise, the instantiation of rebind is ill-formed.

20.10.3.3 Member functions [pointer.traits.functions]

static pointer pointer_traits::pointer_to(see below r);
static constexpr pointer pointer_traits<T*>::pointer_to(see below r) noexcept;

Mandates: For the first member function, Ptr::pointer_to(r) is well-formed.

Preconditions: For the first member function, Ptr::pointer_to(r) returns a pointer to r through which indirection is valid.

Returns: The first member function returns Ptr::pointer_to(r).

The second member function returns addressof(r).

Remarks: If element_type is cv void, the type of r is unspecified; otherwise, it is element_type&.

20.10.3.4 Optional members [pointer.traits.optmem]

Specializations of pointer_traits may define the member declared in this subclause to customize the behavior of the standard library.

static element_type* to_address(pointer p) noexcept;

Returns: A pointer of type element_type* that references the same location as the argument p.

[Note 1:

This function is intended to be the inverse of pointer_to.

If defined, it customizes the behavior of the non-member function to_address ([pointer.conversion]).

— end note]

20.10.4 Pointer conversion [pointer.conversion]

template<class T> constexpr T* to_address(T* p) noexcept;

Mandates: T is not a function type.

Returns: p.

template<class Ptr> constexpr auto to_address(const Ptr& p) noexcept;

Returns: pointer_traits<Ptr>::to_address(p) if that expression is well-formed (see [pointer.traits.optmem]), otherwise to_address(p.operator->()).

20.10.5 Pointer safety [util.dynamic.safety]

A complete object is declared reachable while the number of calls to declare_reachable with an argument referencing the object exceeds the number of calls to undeclare_reachable with an argument referencing the object.

void declare_reachable(void* p);

Preconditions: p is a safely-derived pointer ([basic.stc.dynamic.safety]) or a null pointer value.

Effects: If p is not null, the complete object referenced by p is subsequently declared reachable ([basic.stc.dynamic.safety]).

Throws: May throw bad_alloc if the system cannot allocate additional memory that may be required to track objects declared reachable.

template<class T> T* undeclare_reachable(T* p);

Preconditions: If p is not null, the complete object referenced by p has been previously declared reachable, and is live ([basic.life]) from the time of the call until the last undeclare_reachable(p) call on the object.

Returns: A safely derived copy of p which compares equal to p.

Throws: Nothing.

[Note 1:

It is expected that calls to declare_reachable(p) consume a small amount of memory in addition to that occupied by the referenced object until the matching call to undeclare_reachable(p) is encountered.

Thus, long-running programs where calls are not matched can exhibit a memory leak.

— end note]

void declare_no_pointers(char* p, size_t n);

9

Preconditions: No bytes in the specified range are currently registered with declare_no_pointers().

If the specified range is in an allocated object, then it is entirely within a single allocated object.

The object is live until the corresponding undeclare_no_pointers() call.

[Note 2:

In a garbage-collecting implementation, the fact that a region in an object is registered with declare_no_pointers() does not prevent the object from being collected.

— end note]

10

Effects: The n bytes starting at p no longer contain traceable pointer locations, independent of their type.

Hence indirection through a pointer located there is undefined if the object it points to was created by global operator new and not previously declared reachable.

[Note 3:

This can be used to inform a garbage collector or leak detector that this region of memory need not be traced.

— end note]

Throws: Nothing.

[Note 4:

The request can be ignored if a memory allocation needed by the implementation fails.

— end note]

void undeclare_no_pointers(char* p, size_t n);

13

Preconditions: The same range has previously been passed to declare_no_pointers().

14

Effects: Unregisters a range registered with declare_no_pointers() for destruction.

It shall be called before the lifetime of the object ends.

15

Throws: Nothing.

pointer_safety get_pointer_safety() noexcept;

16

Returns: pointer_safety::strict if the implementation has strict pointer safety .

It is implementation-defined whether get_pointer_safety returns pointer_safety::relaxed or pointer_safety::preferred if the implementation has relaxed pointer safety.224

224)

pointer_safety::preferred might be returned to indicate that a leak detector is running so that the program can avoid spurious leak reports.

⮥

20.10.6 Pointer alignment [ptr.align]

void* align(size_t alignment, size_t size, void*& ptr, size_t& space);

Preconditions:

(1.1)
alignment is a power of two
(1.2)
ptr represents the address of contiguous storage of at least space bytes

Effects: If it is possible to fit size bytes of storage aligned by alignment into the buffer pointed to by ptr with length space, the function updates ptr to represent the first possible address of such storage and decreases space by the number of bytes used for alignment.

Otherwise, the function does nothing.

Returns: A null pointer if the requested aligned buffer would not fit into the available space, otherwise the adjusted value of ptr.

[Note 1:

The function updates its ptr and space arguments so that it can be called repeatedly with possibly different alignment and size arguments for the same buffer.

— end note]

template<size_t N, class T>
  [[nodiscard]] constexpr T* assume_aligned(T* ptr);

Mandates: N is a power of two.

Preconditions: ptr points to an object X of a type similar ([conv.qual]) to T, where X has alignment N ([basic.align]).

Returns: ptr.

Throws: Nothing.

[Note 2:

The alignment assumption on an object X expressed by a call to assume_aligned might result in generation of more efficient code.

It is up to the program to ensure that the assumption actually holds.

The call does not cause the compiler to verify or enforce this.

An implementation might only make the assumption for those operations on X that access X through the pointer returned by assume_aligned.

— end note]

20.10.7 Allocator argument tag [allocator.tag]

namespace std {
  struct allocator_arg_t { explicit allocator_arg_t() = default; };
  inline constexpr allocator_arg_t allocator_arg{};
}

The allocator_arg_t struct is an empty class type used as a unique type to disambiguate constructor and function overloading.

Specifically, several types (see tuple [tuple]) have constructors with allocator_arg_t as the first argument, immediately followed by an argument of a type that meets the Cpp17Allocator requirements (Table 36).

20.10.8 uses_allocator [allocator.uses]

20.10.8.1 uses_allocator trait [allocator.uses.trait]

template<class T, class Alloc> struct uses_allocator;

Remarks: Automatically detects whether T has a nested allocator_type that is convertible from Alloc.

Meets the Cpp17BinaryTypeTrait requirements ([meta.rqmts]).

The implementation shall provide a definition that is derived from true_type if the qualified-id T::allocator_type is valid and denotes a type ([temp.deduct]) and is_convertible_v<Alloc, T::allocator_type> != false, otherwise it shall be derived from false_type.

A program may specialize this template to derive from true_type for a program-defined type T that does not have a nested allocator_type but nonetheless can be constructed with an allocator where either:

(1.1)
the first argument of a constructor has type allocator_arg_t and the second argument has type Alloc or
(1.2)
the last argument of a constructor has type Alloc.

20.10.8.2 Uses-allocator construction [allocator.uses.construction]

Uses-allocator construction with allocator alloc and constructor arguments args... refers to the construction of an object of type T such that alloc is passed to the constructor of T if T uses an allocator type compatible with alloc.

When applied to the construction of an object of type T, it is equivalent to initializing it with the value of the expression make_obj_using_allocator<T>(alloc, args...), described below.

The following utility functions support three conventions for passing alloc to a constructor:

(2.1)
If T does not use an allocator compatible with alloc, then alloc is ignored.
(2.2)
Otherwise, if T has a constructor invocable as T(allocator_arg, alloc, args...) (leading-allocator convention), then uses-allocator construction chooses this constructor form.
(2.3)
Otherwise, if T has a constructor invocable as T(args..., alloc) (trailing-allocator convention), then uses-allocator construction chooses this constructor form.

The uses_allocator_construction_args function template takes an allocator and argument list and produces (as a tuple) a new argument list matching one of the above conventions.

Additionally, overloads are provided that treat specializations of pair such that uses-allocator construction is applied individually to the first and second data members.

The make_obj_using_allocator and uninitialized_construct_using_allocator function templates apply the modified constructor arguments to construct an object of type T as a return value or in-place, respectively.

[Note 1:

For uses_allocator_construction_args and make_obj_using_allocator, type T is not deduced and must therefore be specified explicitly by the caller.

— end note]

template<class T, class Alloc, class... Args>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                  Args&&... args) noexcept -> see below;

Constraints: T is not a specialization of pair.

Returns: A tuple value determined as follows:

(5.1)
If uses_allocator_v<T, Alloc> is false and is_constructible_v<T, Args...> is true, return forward_as_tuple(std::forward<Args>(args)...).
(5.2)
Otherwise, if uses_allocator_v<T, Alloc> is true and is_constructible_v<T, allocator_arg_t, const Alloc&, Args...> is true, return tuple<allocator_arg_t, const Alloc&, Args&&...>( allocator_arg, alloc, std::forward<Args>(args)...)
(5.3)
Otherwise, if uses_allocator_v<T, Alloc> is true and is_constructible_v<T, Args..., const Alloc&> is true, return forward_as_tuple(std::forward<Args>(args)..., alloc).
(5.4)
Otherwise, the program is ill-formed.

[Note 2:

This definition prevents a silent failure to pass the allocator to a constructor of a type for which uses_allocator_v<T, Alloc> is true.

— end note]

template<class T, class Alloc, class Tuple1, class Tuple2>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc, piecewise_construct_t,
                                                  Tuple1&& x, Tuple2&& y)
                                                  noexcept -> see below;

Constraints: T is a specialization of pair.

Effects: For T specified as pair<T1, T2>, equivalent to: return make_tuple( piecewise_construct, apply([&alloc](auto&&... args1) { return uses_allocator_construction_args<T1>( alloc, std::forward<decltype(args1)>(args1)...); }, std::forward<Tuple1>(x)), apply([&alloc](auto&&... args2) { return uses_allocator_construction_args<T2>( alloc, std::forward<decltype(args2)>(args2)...); }, std::forward<Tuple2>(y)));

template<class T, class Alloc>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc) noexcept -> see below;

Constraints: T is a specialization of pair.

9

Effects: Equivalent to: return uses_allocator_construction_args<T>(alloc, piecewise_construct, tuple<>{}, tuple<>{});

template<class T, class Alloc, class U, class V>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                  U&& u, V&& v) noexcept -> see below;

10

Constraints: T is a specialization of pair.

11

Effects: Equivalent to: return uses_allocator_construction_args<T>(alloc, piecewise_construct, forward_as_tuple(std::forward(u)), forward_as_tuple(std::forward<V>(v)));

template<class T, class Alloc, class U, class V>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                  const pair<U,V>& pr) noexcept -> see below;

12

Constraints: T is a specialization of pair.

13

Effects: Equivalent to: return uses_allocator_construction_args<T>(alloc, piecewise_construct, forward_as_tuple(pr.first), forward_as_tuple(pr.second));

template<class T, class Alloc, class U, class V>
  constexpr auto uses_allocator_construction_args(const Alloc& alloc,
                                                  pair<U,V>&& pr) noexcept -> see below;

14

Constraints: T is a specialization of pair.

15

Effects: Equivalent to: return uses_allocator_construction_args<T>(alloc, piecewise_construct, forward_as_tuple(std::move(pr).first), forward_as_tuple(std::move(pr).second));

template<class T, class Alloc, class... Args>
  constexpr T make_obj_using_allocator(const Alloc& alloc, Args&&... args);

16

Effects: Equivalent to: return make_from_tuple<T>(uses_allocator_construction_args<T>( alloc, std::forward<Args>(args)...));

template<class T, class Alloc, class... Args>
  constexpr T* uninitialized_construct_using_allocator(T* p, const Alloc& alloc, Args&&... args);

17

Effects: Equivalent to: return apply([&]<class... U>(U&&... xs) { return construct_at(p, std::forward(xs)...); }, uses_allocator_construction_args<T>(alloc, std::forward<Args>(args)...));

20.10.9 Allocator traits [allocator.traits]

20.10.9.1 General [allocator.traits.general]

The class template allocator_traits supplies a uniform interface to all allocator types.

An allocator cannot be a non-class type, however, even if allocator_traits supplies the entire required interface.

[Note 1:

Thus, it is always possible to create a derived class from an allocator.

— end note]

namespace std { template<class Alloc> struct allocator_traits { using allocator_type = Alloc; using value_type = typename Alloc::value_type; using pointer = see below; using const_pointer = see below; using void_pointer = see below; using const_void_pointer = see below; using difference_type = see below; using size_type = see below; using propagate_on_container_copy_assignment = see below; using propagate_on_container_move_assignment = see below; using propagate_on_container_swap = see below; using is_always_equal = see below; template<class T> using rebind_alloc = see below; template<class T> using rebind_traits = allocator_traits<rebind_alloc<T>>; [[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n); [[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n, const_void_pointer hint); static constexpr void deallocate(Alloc& a, pointer p, size_type n); template<class T, class... Args> static constexpr void construct(Alloc& a, T* p, Args&&... args); template<class T> static constexpr void destroy(Alloc& a, T* p); static constexpr size_type max_size(const Alloc& a) noexcept; static constexpr Alloc select_on_container_copy_construction(const Alloc& rhs); }; }

20.10.9.2 Member types [allocator.traits.types]

using pointer = see below;

Type: Alloc::pointer if the qualified-id Alloc::pointer is valid and denotes a type ([temp.deduct]); otherwise, value_type*.

using const_pointer = see below;

Type: Alloc::const_pointer if the qualified-id Alloc::const_pointer is valid and denotes a type ([temp.deduct]); otherwise, pointer_traits<pointer>::rebind<const value_type>.

using void_pointer = see below;

Type: Alloc::void_pointer if the qualified-id Alloc::void_pointer is valid and denotes a type ([temp.deduct]); otherwise, pointer_traits<pointer>::rebind<void>.

using const_void_pointer = see below;

Type: Alloc::const_void_pointer if the qualified-id Alloc::const_void_pointer is valid and denotes a type ([temp.deduct]); otherwise, pointer_traits<pointer>::rebind<const void>.

using difference_type = see below;

Type: Alloc::difference_type if the qualified-id Alloc::difference_type is valid and denotes a type ([temp.deduct]); otherwise, pointer_traits<pointer>::difference_type.

using size_type = see below;

Type: Alloc::size_type if the qualified-id Alloc::size_type is valid and denotes a type ([temp.deduct]); otherwise, make_unsigned_t<difference_type>.

using propagate_on_container_copy_assignment = see below;

Type: Alloc::propagate_on_container_copy_assignment if the qualified-id Alloc::propagate_on_container_copy_assignment is valid and denotes a type ([temp.deduct]); otherwise false_type.

using propagate_on_container_move_assignment = see below;

Type: Alloc::propagate_on_container_move_assignment if the qualified-id Alloc::propagate_on_container_move_assignment is valid and denotes a type ([temp.deduct]); otherwise false_type.

using propagate_on_container_swap = see below;

9

Type: Alloc::propagate_on_container_swap if the qualified-id Alloc::propagate_on_container_swap is valid and denotes a type ([temp.deduct]); otherwise false_type.

using is_always_equal = see below;

10

Type: Alloc::is_always_equal if the qualified-id Alloc::is_always_equal is valid and denotes a type ([temp.deduct]); otherwise is_empty<Alloc>::type.

template<class T> using rebind_alloc = see below;

11

Alias template: Alloc::rebind<T>::other if the qualified-id Alloc::rebind<T>::other is valid and denotes a type ([temp.deduct]); otherwise, Alloc<T, Args> if Alloc is a class template instantiation of the form Alloc<U, Args>, where Args is zero or more type arguments; otherwise, the instantiation of rebind_alloc is ill-formed.

20.10.9.3 Static member functions [allocator.traits.members]

[[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n);

Returns: a.allocate(n).

[[nodiscard]] static constexpr pointer allocate(Alloc& a, size_type n, const_void_pointer hint);

Returns: a.allocate(n, hint) if that expression is well-formed; otherwise, a.allocate(n).

static constexpr void deallocate(Alloc& a, pointer p, size_type n);

Effects: Calls a.deallocate(p, n).

Throws: Nothing.

template<class T, class... Args>
  static constexpr void construct(Alloc& a, T* p, Args&&... args);

Effects: Calls a.construct(p, std::forward<Args>(args)...) if that call is well-formed; otherwise, invokes construct_at(p, std::forward<Args>(args)...).

template<class T>
  static constexpr void destroy(Alloc& a, T* p);

Effects: Calls a.destroy(p) if that call is well-formed; otherwise, invokes destroy_at(p).

static constexpr size_type max_size(const Alloc& a) noexcept;

Returns: a.max_size() if that expression is well-formed; otherwise, numeric_limits<size_type>::max()/sizeof(value_type).

static constexpr Alloc select_on_container_copy_construction(const Alloc& rhs);

Returns: rhs.select_on_container_copy_construction() if that expression is well-formed; otherwise, rhs.

20.10.10 The default allocator [default.allocator]

20.10.10.1 General [default.allocator.general]

All specializations of the default allocator meet the allocator completeness requirements ([allocator.requirements.completeness]).

namespace std { template<class T> class allocator { public: using value_type = T; using size_type = size_t; using difference_type = ptrdiff_t; using propagate_on_container_move_assignment = true_type; using is_always_equal = true_type; constexpr allocator() noexcept; constexpr allocator(const allocator&) noexcept; template<class U> constexpr allocator(const allocator&) noexcept; constexpr ~allocator(); constexpr allocator& operator=(const allocator&) = default; [[nodiscard]] constexpr T* allocate(size_t n); constexpr void deallocate(T* p, size_t n); }; }

20.10.10.2 Members [allocator.members]

Except for the destructor, member functions of the default allocator shall not introduce data races as a result of concurrent calls to those member functions from different threads.

Calls to these functions that allocate or deallocate a particular unit of storage shall occur in a single total order, and each such deallocation call shall happen before the next allocation (if any) in this order.

[[nodiscard]] constexpr T* allocate(size_t n);

Mandates: T is not an incomplete type ([basic.types]).

Returns: A pointer to the initial element of an array of n T.

Throws: bad_array_new_length if numeric_limits<size_t>::max() / sizeof(T) < n, or bad_alloc if the storage cannot be obtained.

Remarks: The storage for the array is obtained by calling ::operator new, but it is unspecified when or how often this function is called.

This function starts the lifetime of the array object, but not that of any of the array elements.

constexpr void deallocate(T* p, size_t n);

Preconditions: 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.

Effects: Deallocates the storage referenced by p.

Remarks: Uses ::operator delete, but it is unspecified when this function is called.

20.10.10.3 Operators [allocator.globals]

template<class T, class U>
  constexpr bool operator==(const allocator<T>&, const allocator<U>&) noexcept;

Returns: true.

20.10.11 addressof [specialized.addressof]

template<class T> constexpr T* addressof(T& r) noexcept;

Returns: The actual address of the object or function referenced by r, even in the presence of an overloaded operator&.

Remarks: An expression addressof(E) is a constant subexpression ([defns.const.subexpr]) if E is an lvalue constant subexpression.

20.10.12 C library memory allocation [c.malloc]

[Note 1:

The header <cstdlib> declares the functions described in this subclause.

— end note]

void* aligned_alloc(size_t alignment, size_t size);
void* calloc(size_t nmemb, size_t size);
void* malloc(size_t size);
void* realloc(void* ptr, size_t size);

Effects: These functions have the semantics specified in the C standard library.

Remarks: These functions do not attempt to allocate storage by calling ::operator new() ([new.delete]).

Storage allocated directly with these functions is implicitly declared reachable (see [basic.stc.dynamic.safety]) on allocation, ceases to be declared reachable on deallocation, and need not cease to be declared reachable as the result of an undeclare_reachable() call.

[Note 2:

This allows existing C libraries to remain unaffected by restrictions on pointers that are not safely derived, at the expense of providing far fewer garbage collection and leak detection options for malloc()-allocated objects.

It also allows malloc() to be implemented with a separate allocation arena, bypassing the normal declare_reachable() implementation.

— end note]

These functions implicitly create objects ([intro.object]) in the returned region of storage and return a pointer to a suitable created object.

In the case of calloc and realloc, the objects are created before the storage is zeroed or copied, respectively.

void free(void* ptr);

Effects: This function has the semantics specified in the C standard library.