This technical specification describes extensions to the C++ Standard Library (1.2). These extensions are classes and functions that are likely to be used widely within a program and/or on the interface boundaries between libraries written by different organizations.

This technical specification is non-normative. Some of the library components in this technical specification may be considered for standardization in a future version of C++, but they are not currently part of any C++ standard. Some of the components in this technical specification may never be standardized, and others may be standardized in a substantially changed form.

The goal of this technical specification is to build more widespread existing practice for an expanded C++ standard library. It gives advice on extensions to those vendors who wish to provide them.

The following referenced document is indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

• ISO/IEC 14882:—, Programming Languages — C++

ISO/IEC 14882:— is herein called the C++ Standard. References to clauses within the C++ Standard are written as "C++20 §3.2". The library described in ISO/IEC 14882:— clauses 16–32 is herein called the C++ Standard Library.

Unless otherwise specified, the whole of the C++ Standard's Library introduction (C++20 §16) is included into this Technical Specification by reference.

Since the extensions described in this technical specification are experimental and not part of the C++ standard library, they should not be declared directly within namespace std. Unless otherwise specified, all components described in this technical specification either:

• modify an existing interface in the C++ Standard Library in-place,
• are declared in a namespace whose name appends ::experimental::fundamentals_v3 to a namespace defined in the C++ Standard Library, such as std or std::chrono, or
• are declared in a subnamespace of a namespace described in the previous bullet, whose name is not the same as an existing subnamespace of namespace std.

Each header described in this technical specification shall import the contents of std::experimental::fundamentals_v3 into std::experimental as if by

namespace std::experimental::inline fundamentals_v3 {}

This technical specification also describes some experimental modifications to existing interfaces in the C++ Standard Library. These modifications are described by quoting the affected parts of the standard and using underlining to represent added text and strike-through to represent deleted text.

Unless otherwise specified, references to other entities described in this technical specification are assumed to be qualified with std::experimental::fundamentals_v3::, and references to entities described in the standard are assumed to be qualified with std::.

Extensions that are expected to eventually be added to an existing header <meow> are provided inside the <experimental/meow> header, which shall include the standard contents of <meow> as if by

#include <meow>

New headers are also provided in the <experimental/> directory, but without such an #include.

This section describes tentative plans for future versions of this technical specification and plans for moving content into future versions of the C++ Standard.

The C++ committee intends to release new versions of this technical specification periodically, containing the library extensions we hope to add to a near-future version of the C++ Standard. Future versions will define their contents in std::experimental::fundamentals_v4, std::experimental::fundamentals_v5, etc., with the most recent implemented version inlined into std::experimental.

When an extension defined in this or a future version of this technical specification represents enough existing practice, it will be moved into the next version of the C++ Standard by removing the experimental::fundamentals_vN segment of its namespace and by removing the experimental/ prefix from its header's path.

For the sake of improved portability between partial implementations of various C++ standards, WG21 (the ISO technical committee for the C++ programming language) recommends that implementers and programmers follow the guidelines in this section concerning feature-test macros. [ Note: WG21's SD-6 makes similar recommendations for the C++ Standard itself. — end note ]

Implementers who provide a new standard feature should define a macro with the recommended name, in the same circumstances under which the feature is available (for example, taking into account relevant command-line options), to indicate the presence of support for that feature. Implementers should define that macro with the value specified in the most recent version of this technical specification that they have implemented. The recommended macro name is "__cpp_lib_experimental_" followed by the string in the "Macro Name Suffix" column.

Programmers who wish to determine whether a feature is available in an implementation should base that determination on the presence of the header (determined with __has_include(<header/name>)) and the state of the macro with the recommended name. (The absence of a tested feature may result in a program with decreased functionality, or the relevant functionality may be provided in a different way. A program that strictly depends on support for a feature can just try to use the feature unconditionally; presumably, on an implementation lacking necessary support, translation will fail.)

The following changes to the library introduction allow the destructor of scope_success to throw exceptions.

20.5.4.8 Other functions [res.on.functions]

In certain cases […]

In particular, the effects are undefined in the following cases:

• […]
• if any replacement function or handler function or destructor operation exits via an exception, unless specifically allowed in the applicable Required behavior: or Throws: paragraph.
• if an incomplete type (6.9) is used as a template argument when instantiating a template component, unless specifically allowed for that component.

20.5.5.12 Restrictions on exception handling [res.on.exception.handling]

[…]

Functions from the C standard library shall not throw exceptions¹⁸³ except when such a function calls a program-supplied function that throws an exception.¹⁸⁴

Unless otherwise specified, destructorDestructor operations defined in the C++ standard library shall not throw exceptions. Every destructor without an exception specification in the C++ standard library shall behave as if it had a non-throwing exception specification.

Functions defined in the C++ standard library […]

The following changes to the uses_allocator trait and to the description of uses-allocator construction allow a memory_resource pointer act as an allocator in many circumstances. [ Note: Existing programs that use standard allocators would be unaffected by this change. — end note ]

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 (C++20 §20.15.1). The implementation shall provide a definition that is derived from true_type if a type T::allocator_type exists and either is_convertible_v<Alloc, T::allocator_type> != false or T::allocator_type is an alias for std::experimental::erased_type (3.1.2), otherwise it shall be derived from false_type. A program may specialize this template to derive from true_type for a user-defined type T that does not have a nested allocator_type but nonetheless can be constructed with an allocator where either:

• the first argument of a constructor has type allocator_arg_t and the second argument has type Alloc or
• 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 refers to the construction of an object obj of type T, using constructor arguments v1, v2, ..., vN of types V1, V2, ..., VN, respectively, and an allocator alloc of type Alloc, where Alloc either (1) meets the requirements of an allocator (C++20 §16.5.3.5), or (2) is a pointer type convertible to std::experimental::pmr::memory_resource* (), according to the following rules:

#include <functional>

namespace std {
  namespace experimental::inline fundamentals_v3 {

    // 4.2, Class template function
    template<class> class function; // undefined
    template<class R, class... ArgTypes> class function<R(ArgTypes...)>;

    template<class R, class... ArgTypes>
    void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&);

    template<class R, class... ArgTypes>
    bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
    template<class R, class... ArgTypes>
    bool operator==(nullptr_t, const function<R(ArgTypes...)>&) noexcept;
    template<class R, class... ArgTypes>
    bool operator!=(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
    template<class R, class... ArgTypes>
    bool operator!=(nullptr_t, const function<R(ArgTypes...)>&) noexcept;

  } // namespace experimental::inline fundamentals_v3

  template<class R, class... ArgTypes, class Alloc>
  struct uses_allocator<experimental::function<R(ArgTypes...)>, Alloc>;

} // namespace std

The specification of all declarations within this sub-clause 4.2 and its sub-clauses are the same as the corresponding declarations, as specified in C++20 §20.14.16.2, unless explicitly specified otherwise. [ Note: std::experimental::function uses std::bad_function_call, there is no additional type std::experimental::bad_function_call — end note ] .

namespace std {
  namespace experimental::inline fundamentals_v3 {

    template<class> class function; // undefined

    template<class R, class... ArgTypes>
    class function<R(ArgTypes...)> {
    public:
      using result_type = R;
      using argument_type = T1;
      using first_argument_type T1;
      using second_argument_type = T2;

      using allocator_type = erased_type;

      function() noexcept;
      function(nullptr_t) noexcept;
      function(const function&);
      function(function&&);
      template<class F> function(F);
      template<class A> function(allocator_arg_t, const A&) noexcept;
      template<class A> function(allocator_arg_t, const A&,
        nullptr_t) noexcept;
      template<class A> function(allocator_arg_t, const A&,
        const function&);
      template<class A> function(allocator_arg_t, const A&,
        function&&);
      template<class F, class A> function(allocator_arg_t, const A&, F);

      function& operator=(const function&);
      function& operator=(function&&);
      function& operator=(nullptr_t) noexcept;
      template<class F> function& operator=(F&&);
      template<class F> function& operator=(reference_wrapper<F>);

      ~function();

      void swap(function&);

      explicit operator bool() const noexcept;

      R operator()(ArgTypes...) const;

      const type_info& target_type() const noexcept;
      template<class T> T* target() noexcept;
      template<class T> const T* target() const noexcept;

      pmr::memory_resource* get_memory_resource() const noexcept;
    };

    template <class R, class... ArgTypes>
    bool operator==(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
    template <class R, class... ArgTypes>
    bool operator==(nullptr_t, const function<R(ArgTypes...)>&) noexcept;

    template <class R, class... ArgTypes>
    bool operator!=(const function<R(ArgTypes...)>&, nullptr_t) noexcept;
    template <class R, class... ArgTypes>
    bool operator!=(nullptr_t, const function<R(ArgTypes...)>&) noexcept;

    template <class R, class... ArgTypes>
    void swap(function<R(ArgTypes...)>&, function<R(ArgTypes...)>&);

  } // namespace experimental::inline fundamentals_v3

  template <class R, class... ArgTypes, class Alloc>
  struct uses_allocator<experimental::function<R(ArgTypes...)>, Alloc>
    : true_type { };

} // namespace std

function& operator=(const function& f);

function& operator=(function&& f);

function& operator=(nullptr_t) noexcept;

template<class F> function& operator=(F&& f);

template<class F> function& operator=(reference_wrapper<F> f);

void swap(function& other);

#include <memory>

namespace std {
  namespace experimental::inline fundamentals_v3 {

    // 5.2, Non-owning pointers
    template <class W> class observer_ptr;

    // 5.2.6, observer_ptr specialized algorithms
    template <class W>
    void swap(observer_ptr<W>&, observer_ptr<W>&) noexcept;
    template <class W>
    observer_ptr<W> make_observer(W*) noexcept;
    // (in)equality operators
    template <class W1, class W2>
    bool operator==(observer_ptr<W1>, observer_ptr<W2>);

    template <class W1, class W2>
    bool operator!=(observer_ptr<W1>, observer_ptr<W2>);
    template <class W>
    bool operator==(observer_ptr<W>, nullptr_t) noexcept;
    template <class W>
    bool operator!=(observer_ptr<W>, nullptr_t) noexcept;
    template <class W>
    bool operator==(nullptr_t, observer_ptr<W>) noexcept;
    template <class W>
    bool operator!=(nullptr_t, observer_ptr<W>) noexcept;
    // ordering operators
    template <class W1, class W2>
    bool operator<(observer_ptr<W1>, observer_ptr<W2>);
    template <class W1, class W2>
    bool operator>(observer_ptr<W1>, observer_ptr<W2>);
    template <class W1, class W2>
    bool operator<=(observer_ptr<W1>, observer_ptr<W2>);
    template <class W1, class W2>
    bool operator>=(observer_ptr<W1>, observer_ptr<W2>);

  } // namespace experimental::inline fundamentals_v3

  // 5.2.7, observer_ptr hash support
  template <class T> struct hash;
  template <class T> struct hash<experimental::observer_ptr<T>>;

} // namespace std

A non-owning pointer, known as an observer, is an object o that stores a pointer to a second object, w. In this context, w is known as a watched object. [ Note: There is no watched object when the stored pointer is nullptr. — end note ] An observer takes no responsibility or ownership of any kind for its watched object, if any; in particular, there is no inherent relationship between the lifetimes of o and w.

Specializations of observer_ptr shall meet the requirements of a Cpp17CopyConstructible and Cpp17CopyAssignable type. The template parameter W of an observer_ptr shall not be a reference type, but may be an incomplete type.

[ Note: The uses of observer_ptr include clarity of interface specification in new code, and interoperability with pointer-based legacy code. — end note ]

namespace std::experimental::inline fundamentals_v3 {

  template <class W> class observer_ptr {
    using pointer = add_pointer_t<W>;            // exposition-only
    using reference = add_lvalue_reference_t<W>; // exposition-only
  public:
    // publish our template parameter and variations thereof
    using element_type = W;

    // 5.2.2, observer_ptr constructors
    // default constructor
    constexpr observer_ptr() noexcept;

    // pointer-accepting constructors
    constexpr observer_ptr(nullptr_t) noexcept;
    constexpr explicit observer_ptr(pointer) noexcept;

    // copying constructors (in addition to the implicit copy constructor)
    template <class W2> constexpr observer_ptr(observer_ptr<W2>) noexcept;

    // 5.2.3, observer_ptr observers
    constexpr pointer get() const noexcept;
    constexpr reference operator*() const;
    constexpr pointer operator->() const noexcept;
    constexpr explicit operator bool() const noexcept;

    // 5.2.4, observer_ptr conversions
    constexpr explicit operator pointer() const noexcept;

    // 5.2.5, observer_ptr modifiers
    constexpr pointer release() noexcept;
    constexpr void reset(pointer = nullptr) noexcept;
    constexpr void swap(observer_ptr&) noexcept;
  }; // observer_ptr<>

} // namespace std::experimental::inline fundamentals_v3

constexpr observer_ptr() noexcept;constexpr observer_ptr(nullptr_t) noexcept;

constexpr explicit observer_ptr(pointer other) noexcept;

template <class W2> constexpr observer_ptr(observer_ptr<W2> other) noexcept;

constexpr pointer get() const noexcept;

constexpr reference operator*() const;

constexpr pointer operator->() const noexcept;

constexpr explicit operator bool() const noexcept;

constexpr explicit operator pointer() const noexcept;

constexpr pointer release() noexcept;

constexpr void reset(pointer p = nullptr) noexcept;

constexpr void swap(observer_ptr& other) noexcept;

template <class W>
void swap(observer_ptr<W>& p1, observer_ptr<W>& p2) noexcept;

template <class W> observer_ptr<W> make_observer(W* p) noexcept;

template <class W1, class W2>
bool operator==(observer_ptr<W1> p1, observer_ptr<W2> p2);

template <class W1, class W2>
bool operator!=(observer_ptr<W1> p1, observer_ptr<W2> p2);

template <class W>
bool operator==(observer_ptr<W> p, nullptr_t) noexcept;template <class W>
bool operator==(nullptr_t, observer_ptr<W> p) noexcept;

template <class W>
bool operator!=(observer_ptr<W> p, nullptr_t) noexcept;template <class W>
bool operator!=(nullptr_t, observer_ptr<W> p) noexcept;

template <class W1, class W2>
bool operator<(observer_ptr<W1> p1, observer_ptr<W2> p2);

template <class W1, class W2>
bool operator>(observer_ptr<W1> p1, observer_ptr<W2> p2);

template <class W1, class W2>
bool operator<=(observer_ptr<W1> p1, observer_ptr<W2> p2);

template <class W1, class W2>
bool operator>=(observer_ptr<W1> p1, observer_ptr<W2> p2);

template <class T> struct hash<experimental::observer_ptr<T>>;

A type-erased allocator is an allocator or memory resource, alloc, used to allocate internal data structures for an object X of type C, but where C is not dependent on the type of alloc. Once alloc has been supplied to X (typically as a constructor argument), alloc can be retrieved from X only as a pointer rptr of static type std::pmr::memory_resource* (C++20 §20.12.2). The process by which rptr is computed from alloc depends on the type of alloc as described in Table 5:

Additionally, class C meets the following requirements:

• C::allocator_type denotes std::experimental::erased_type.
• X.get_memory_resource() returns rptr.

namespace std::experimental::inline fundamentals_v3::pmr {

  // The name resource_adaptor_imp is for exposition only.
  template <class Allocator> class resource_adaptor_imp;

  template <class Allocator>
    using resource_adaptor = resource_adaptor_imp<
      typename allocator_traits<Allocator>::template rebind_alloc<char>>;

} // namespace std::experimental::inline fundamentals_v3::pmr

#include <iterator>

namespace std::experimental::inline fundamentals_v3 {

  // 6.2, Class template ostream_joiner
  template <class DelimT, class charT = char, class traits = char_traits<charT> >
      class ostream_joiner;
  template <class charT, class traits, class DelimT>
    ostream_joiner<decay_t<DelimT>, charT, traits>
    make_ostream_joiner(basic_ostream<charT, traits>& os, DelimT&& delimiter);

} // namespace std::experimental::inline fundamentals_v3

ostream_joiner writes (using operator<<) successive elements onto the output stream from which it was constructed. The delimiter that it was constructed with is written to the stream between every two Ts that are written. It is not possible to get a value out of the output iterator. Its only use is as an output iterator in situations like

while (first != last)
  *result++ = *first++;

ostream_joiner is defined as

namespace std::experimental::inline fundamentals_v3 {

  template <class DelimT, class charT = char, class traits = char_traits<charT> >
  class ostream_joiner {
  public:
    using char_type = charT;
    using traits_type = traits;
    using ostream_type = basic_ostream<charT, traits>;
    using iterator_category = output_iterator_tag;
    using value_type = void;
    using difference_type = void;
    using pointer = void;
    using reference = void;

    ostream_joiner(ostream_type& s, const DelimT& delimiter);
    ostream_joiner(ostream_type& s, DelimT&& delimiter);
    template<typename T>
    ostream_joiner& operator=(const T& value);
    ostream_joiner& operator*() noexcept;
    ostream_joiner& operator++() noexcept;
    ostream_joiner& operator++(int) noexcept;

  private:
    ostream_type* out_stream; // exposition only
    DelimT delim;             // exposition only
    bool first_element;       // exposition only
  };

} // namespace std::experimental::inline fundamentals_v3

ostream_joiner(ostream_type& s, const DelimT& delimiter);

ostream_joiner(ostream_type& s, DelimT&& delimiter);

template<typename T>
ostream_joiner& operator=(const T& value);

ostream_joiner& operator*() noexcept;

ostream_joiner& operator++() noexcept;ostream_joiner& operator++(int) noexcept;

template <class charT, class traits, class DelimT>
ostream_joiner<decay_t<DelimT>, charT, traits>
make_ostream_joiner(basic_ostream<charT, traits>& os, DelimT&& delimiter);

#include <future>

namespace std {
  namespace experimental::inline fundamentals_v3 {

    template <class R> class promise;
    template <class R> class promise<R&>;
    template <> class promise<void>;

    template <class R>
    void swap(promise<R>& x, promise<R>& y) noexcept;

    template <class> class packaged_task; // undefined
    template <class R, class... ArgTypes>
    class packaged_task<R(ArgTypes...)>;

    template <class R, class... ArgTypes>
    void swap(packaged_task<R(ArgTypes...)>&, packaged_task<R(ArgTypes...)>&) noexcept;

  } // namespace experimental::inline fundamentals_v3

  template <class R, class Alloc>
  struct uses_allocator<experimental::promise<R>, Alloc>;

  template <class R, class Alloc>
  struct uses_allocator<experimental::packaged_task<R>, Alloc>;

} // namespace std

The specification of all declarations within this sub-clause 7.2 and its sub-clauses are the same as the corresponding declarations, as specified in C++20 §32.9.6, unless explicitly specified otherwise.

namespace std {
  namespace experimental::inline fundamentals_v3 {

    template <class R>
    class promise {
    public:
      using allocator_type = erased_type;

      promise();
      template <class Allocator>
      promise(allocator_arg_t, const Allocator& a);
      promise(promise&& rhs) noexcept;
      promise(const promise& rhs) = delete;
      ~promise();

      promise& operator=(promise&& rhs) noexcept;
      promise& operator=(const promise& rhs) = delete;
      void swap(promise& other) noexcept;

      future<R> get_future();

      void set_value(see below);
      void set_exception(exception_ptr p);

      void set_value_at_thread_exit(const R& r);
      void set_value_at_thread_exit(see below);
      void set_exception_at_thread_exit(exception_ptr p);

      pmr::memory_resource* get_memory_resource() const noexcept;
    };

    template <class R>
    void swap(promise<R>& x, promise<R>& y) noexcept;

  } // namespace experimental::inline fundamentals_v3

  template <class R, class Alloc>
  struct uses_allocator<experimental::promise<R>, Alloc>;

} // namespace std

When a promise constructor that takes a first argument of type allocator_arg_t is invoked, the second argument is treated as a type-erased allocator (5.3).

The specification of all declarations within this sub-clause 7.3 and its sub-clauses are the same as the corresponding declarations, as specified in C++20 §32.9.10, unless explicitly specified otherwise.

namespace std {
  namespace experimental::inline fundamentals_v3 {

    template <class R, class... ArgTypes>
    class packaged_task<R(ArgTypes...)> {
    public:
      using allocator_type = erased_type;

      packaged_task() noexcept;
      template <class F>
      explicit packaged_task(F&& f);
      template <class F, class Allocator>
      explicit packaged_task(allocator_arg_t, const Allocator& a, F&& f);
      ~packaged_task();

      packaged_task(const packaged_task&) = delete;
      packaged_task& operator=(const packaged_task&) = delete;

      packaged_task(packaged_task&& rhs) noexcept;
      packaged_task& operator=(packaged_task&& rhs) noexcept;
      void swap(packaged_task& other) noexcept;

      bool valid() const noexcept;

      future<R> get_future();

      void operator()(ArgTypes... );
      void make_ready_at_thread_exit(ArgTypes...);

      void reset();

      pmr::memory_resource* get_memory_resource() const noexcept;
    };

    template <class R, class... ArgTypes>
    void swap(packaged_task<R(ArgTypes...)>&, packaged_task<R(ArgTypes...)>&) noexcept;

  } // namespace experimental::inline fundamentals_v3

  template <class R, class Alloc>
  struct uses_allocator<experimental::packaged_task<R>, Alloc>;

} // namespace std

When a packaged_task constructor that takes a first argument of type allocator_arg_t is invoked, the second argument is treated as a type-erased allocator (5.3).

#include <algorithm>

namespace std::experimental::inline fundamentals_v3 {

  // 8.2, Sampling
  template<class PopulationIterator, class SampleIterator, class Distance>
  SampleIterator sample(PopulationIterator first, PopulationIterator last,
                        SampleIterator out, Distance n);

  // 8.3, Shuffle
  template<class RandomAccessIterator>
  void shuffle(RandomAccessIterator first, RandomAccessIterator last);

} // namespace std::experimental::inline fundamentals_v3