17 Library introduction [library]

The template definitions in the C++ standard library refer to various named requirements whose details are set out in tables [equalitycomparable]–[destructible]. In these tables, T is an object or reference type to be supplied by a C++ program instantiating a template; a, b, and c are values of type (possibly const) T; s and t are modifiable lvalues of type T; u denotes an identifier; rv is an rvalue of type T; and v is an lvalue of type (possibly const) T or an rvalue of type const T.

In general, a default constructor is not required. Certain container class member function signatures specify T() as a default argument. T() shall be a well-defined expression ([dcl.init]) if one of those signatures is called using the default argument ([dcl.fct.default]).

This subclause provides definitions for swappable types and expressions. In these definitions, let t denote an expression of type T, and let u denote an expression of type U.

An object t is swappable with an object u if and only if:

• (2.1)

  the expressions swap(t, u) and swap(u, t) are valid when evaluated in the context described below, and

• (2.2)

  these expressions have the following effects:

  • (2.2.1)

    the object referred to by t has the value originally held by u and

  • (2.2.2)

    the object referred to by u has the value originally held by t.

The context in which swap(t, u) and swap(u, t) are evaluated shall ensure that a binary non-member function named “swap” is selected via overload resolution ([over.match]) on a candidate set that includes:

• (3.1)

  the two swap function templates defined in <utility> ([utility]) and

• (3.2)

  the lookup set produced by argument-dependent lookup ([basic.lookup.argdep]).

[ Note: If T and U are both fundamental types or arrays of fundamental types and the declarations from the header <utility> are in scope, the overall lookup set described above is equivalent to that of the qualified name lookup applied to the expression std::swap(t, u) or std::swap(u, t) as appropriate.  — end note ]

[ Note: It is unspecified whether a library component that has a swappable requirement includes the header <utility> to ensure an appropriate evaluation context.  — end note ]

An rvalue or lvalue t is swappable if and only if t is swappable with any rvalue or lvalue, respectively, of type T.

A type X satisfying any of the iterator requirements ([iterator.requirements]) satisfies the requirements of ValueSwappable if, for any dereferenceable object x of type X, *x is swappable.

[ Example: User code can ensure that the evaluation of swap calls is performed in an appropriate context under the various conditions as follows:

#include <utility>

// Requires: std::forward<T>(t) shall be swappable with std::forward<U>(u).
template <class T, class U>
void value_swap(T&& t, U&& u) {
  using std::swap;
  swap(std::forward<T>(t), std::forward<U>(u)); // OK: uses “swappable with” conditions
                                                // for rvalues and lvalues
}

// Requires: lvalues of T shall be swappable.
template <class T>
void lv_swap(T& t1 T& t2) {
  using std::swap;
  swap(t1, t2);                                 // OK: uses swappable conditions for
}                                               // lvalues of type T

namespace N {
  struct A { int m; };
  struct Proxy { A* a; };
  Proxy proxy(A& a) { return Proxy{ &a }; }

  void swap(A& x, Proxy p) {
    std::swap(x.m, p.a->m);                     // OK: uses context equivalent to swappable
                                                // conditions for fundamental types
  }
  void swap(Proxy p, A& x) { swap(x, p); }      // satisfy symmetry constraint
}

int main() {
  int i = 1, j = 2;
  lv_swap(i, j);
  assert(i == 2 && j == 1);

  N::A a1 = { 5 }, a2 = { -5 };
  value_swap(a1, proxy(a2));
  assert(a1.m == -5 && a2.m == 5);
}

 — end example ]

A NullablePointer type is a pointer-like type that supports null values. A type P meets the requirements of NullablePointer if:

• (1.1)

  P satisfies the requirements of EqualityComparable, DefaultConstructible, CopyConstructible, CopyAssignable, and Destructible,

• (1.2)

  lvalues of type P are swappable ([swappable.requirements]),

• (1.3)

  the expressions shown in Table [nullablepointer] are valid and have the indicated semantics, and

• (1.4)

  P satisfies all the other requirements of this subclause.

A value-initialized object of type P produces the null value of the type. The null value shall be equivalent only to itself. A default-initialized object of type P may have an indeterminate value. [ Note: Operations involving indeterminate values may cause undefined behavior.  — end note ]

An object p of type P can be contextually converted to bool (Clause [conv]). The effect shall be as if p != nullptr had been evaluated in place of p.

No operation which is part of the NullablePointer requirements shall exit via an exception.

In Table [nullablepointer], u denotes an identifier, t denotes a non-const lvalue of type P, a and b denote values of type (possibly const) P, and np denotes a value of type (possibly const) std::nullptr_t.

A type H meets the Hash requirements if:

• (1.1)

  it is a function object type ([function.objects]),

• (1.2)

  it satisfies the requirements of CopyConstructible and Destructible ([utility.arg.requirements]), and

• (1.3)

  the expressions shown in Table [hash] are valid and have the indicated semantics.

Given Key is an argument type for function objects of type H, in Table [hash] h is a value of type (possibly const) H, u is an lvalue of type Key, and k is a value of a type convertible to (possibly const) Key.

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 (Clause [strings]), containers (Clause [containers]) (except array), string buffers and string streams (Clause [input.output]), and match_results (Clause [re]) are parameterized in terms of allocators.

The template struct allocator_traits ([allocator.traits]) supplies a uniform interface to all allocator types. Table [tab:desc.var.def] describes the types manipulated through allocators. Table [tab:utilities.allocator.requirements] describes the requirements on allocator types and thus on types used to instantiate allocator_traits. A requirement is optional if the last column of Table [tab:utilities.allocator.requirements] specifies a default for a given expression. Within the standard library allocator_traits template, an optional requirement that is not supplied by an allocator is replaced by the specified default expression. A user specialization of allocator_traits may provide different defaults and may provide defaults for different requirements than the primary template. Within Tables [tab:desc.var.def] and [tab:utilities.allocator.requirements], the use of move and forward always refers to std::move and std::forward, respectively.

Note A: The member class template rebind in the table above is effectively a typedef template. [ Note: 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 ] 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.

An allocator type X shall satisfy the requirements of CopyConstructible ([utility.arg.requirements]). The X::pointer, X::const_pointer, X::void_pointer, and X::const_void_pointer types shall satisfy the requirements of NullablePointer ([nullablepointer.requirements]). No constructor, comparison operator, copy operation, move operation, or swap operation on these types shall exit via an exception. X::pointer and X::const_pointer shall also satisfy the requirements for a random access iterator ([iterator.requirements]).

Let x1 and x2 denote objects of (possibly different) types X::void_pointer, X::const_void_pointer, X::pointer, or X::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 X::const_pointer, using a sequence of static_casts using only these four types, and the expression px1 == px2 evaluates to true.

Let w1 and w2 denote objects of type X::void_pointer. Then for the expressions

w1 == w2
w1 != w2

either or both objects may be replaced by an equivalently-valued object of type X::const_void_pointer with no change in semantics.

Let p1 and p2 denote objects of type X::pointer. Then for the expressions

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 X::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 member may be called. If a type cannot be used with a particular allocator, the allocator class or the call to construct may fail to instantiate.

[ Example: the following is an allocator class template supporting the minimal interface that satisfies the requirements of Table [tab:utilities.allocator.requirements]:

template <class Tp>
struct SimpleAllocator {
  typedef Tp value_type;
  SimpleAllocator(ctor args);

  template <class T> SimpleAllocator(const SimpleAllocator<T>& other);

  Tp* allocate(std::size_t n);
  void deallocate(Tp* p, std::size_t n);
};

template <class T, class U>
bool operator==(const SimpleAllocator<T>&, const SimpleAllocator<U>&);
template <class T, class U>
bool operator!=(const SimpleAllocator<T>&, const SimpleAllocator<U>&);

 — end example ]

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: Additionally, the member function allocate for that type may fail by throwing an object of type std::bad_alloc. — end note ]