Document Number:N4758
Date:
Revises:N4617
Editor: Thomas Köppe
Google DeepMind
tkoeppe@google.com

Working Draft, C++ Extensions for Library Fundamentals, Version 3

Note: this is an early draft. It’s known to be incomplet and incorrekt, and it has lots of bad formatting.

1

General

[general]
1.1

Scope

[general.scope]

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.

1.2

Normative references

[general.references]

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:2017, Programming Languages — C++

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

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

1.3

Namespaces, headers, and modifications to standard classes

[general.namespaces]

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.
[ Example: This TS does not define std::experimental::fundamentals_v3::pmr because the C++ Standard Library defines std::pmr. end example ]

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 namespace 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.

1.4

Future plans (Informative)

[general.plans]

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 a new version of this technical specification approximately every year, 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.

1.5

Feature-testing recommendations (Informative)

[general.feature.test]

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.)

Table 2 — Significant features in this technical specification
Doc. No. Title Primary Section Macro Name Suffix Value Header
N3866 Invocation type traits 3.3.2 invocation_type 201406 <experimental/type_traits>
N4502 The C++ Detection Idiom 3.3.3 detect 201505 <experimental/type_traits>
N4388 A Proposal to Add a Const-Propagating Wrapper to the Standard Library 3.2 propagate_const 201505 <experimental/propagate_const>
N3916 Type-erased allocator for std::function 4.2 function_erased_allocator 201406 <experimental/functional>
N4282 The World’s Dumbest Smart Pointer 5.2 observer_ptr 201411 <experimental/memory>
N4273 Uniform Container Erasure 6.1 erase_if 201411 <experimental/vector>, <experimental/deque>, <experimental/forward_list>, <experimental/list>, <experimental/map>, <experimental/set>, <experimental/unordered_map>, <experimental/unordered_set>
N4391 make_array 6.2.2 make_array 201505 <experimental/array>
N4257 Delimited iterators 7.2 ostream_joiner 201411 <experimental/iterator>
N3916 Type-erased allocator for std::promise 8.2 promise_erased_allocator 201406 <experimental/future>
N3916 Type-erased allocator for std::packaged_task 8.3 packaged_task_erased_allocator 201406 <experimental/future>
N3925 A sample Proposal 9.2 sample 201402 <experimental/algorithm>
N4531 std::rand replacement 10.1.2.1 randint 201511 <experimental/random>
N4519 Source-Code Information Capture 11.2 source_location 201505 <experimental/source_location>
2

Modifications to the C++ Standard Library

[mods]

Implementations that conform to this technical specification shall behave as if the modifications contained in this section are made to the C++ Standard.

2.1

Uses-allocator construction

[mods.allocator.uses]

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.7.7 uses_allocator [allocator.uses]

20.7.7.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 BinaryTypeTrait requirements (C++17 §23.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.7.7.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++17 §20.5.3.5), or (2) is a pointer type convertible to std::experimental::pmr::memory_resource* (), according to the following rules:

3

General utilities library

[utilities]
3.1

Utility components

[utility]
3.1.1

Header <experimental/utility> synopsis

[utility.synop]
#include <utility>

namespace std::experimental {
inline namespace fundamentals_v3 {

  // 3.1.2, Class erased_type
  struct erased_type { };

} // namespace fundamentals_v3
} // namespace std::experimental
3.1.2

Class erased_type

[utility.erased.type]
struct erased_type { };

The erased_type struct is an empty struct that serves as a placeholder for a type T in situations where the actual type T is determined at runtime. For example, the nested type, allocator_type, is an alias for erased_type in classes that use type-erased allocators (see 5.3).

3.2

Constness propagation

[propagate_const]
3.2.1

Header <experimental/propagate_const> synopsis

[propagate_const.synopsis]
namespace std {
  namespace experimental {
  inline namespace fundamentals_v3 {
    // 3.2.2.1, Class template propagate_const overview
    template <class T> class propagate_const;

    // 3.2.2.8, propagate_const relational operators
    template <class T>
      constexpr bool operator==(const propagate_const<T>& pt, nullptr_t);
    template <class T>
      constexpr bool operator==(nullptr_t, const propagate_const<T>& pu);

    template <class T>
      constexpr bool operator!=(const propagate_const<T>& pt, nullptr_t);
    template <class T>
      constexpr bool operator!=(nullptr_t, const propagate_const<T>& pu);

    template <class T, class U>
      constexpr bool operator==(const propagate_const<T>& pt, const propagate_const<U>& pu);
    template <class T, class U>
      constexpr bool operator!=(const propagate_const<T>& pt, const propagate_const<U>& pu);
    template <class T, class U>
      constexpr bool operator<(const propagate_const<T>& pt, const propagate_const<U>& pu);
    template <class T, class U>
      constexpr bool operator>(const propagate_const<T>& pt, const propagate_const<U>& pu);
    template <class T, class U>
      constexpr bool operator<=(const propagate_const<T>& pt, const propagate_const<U>& pu);
    template <class T, class U>
      constexpr bool operator>=(const propagate_const<T>& pt, const propagate_const<U>& pu);

    template <class T, class U>
      constexpr bool operator==(const propagate_const<T>& pt, const U& u);
    template <class T, class U>
      constexpr bool operator!=(const propagate_const<T>& pt, const U& u);
    template <class T, class U>
      constexpr bool operator<(const propagate_const<T>& pt, const U& u);
    template <class T, class U>
      constexpr bool operator>(const propagate_const<T>& pt, const U& u);
    template <class T, class U>
      constexpr bool operator<=(const propagate_const<T>& pt, const U& u);
    template <class T, class U>
      constexpr bool operator>=(const propagate_const<T>& pt, const U& u);

    template <class T, class U>
      constexpr bool operator==(const T& t, const propagate_const<U>& pu);
    template <class T, class U>
      constexpr bool operator!=(const T& t, const propagate_const<U>& pu);
    template <class T, class U>
      constexpr bool operator<(const T& t, const propagate_const<U>& pu);
    template <class T, class U>
      constexpr bool operator>(const T& t, const propagate_const<U>& pu);
    template <class T, class U>
      constexpr bool operator<=(const T& t, const propagate_const<U>& pu);
    template <class T, class U>
      constexpr bool operator>=(const T& t, const propagate_const<U>& pu);

    // 3.2.2.9, propagate_const specialized algorithms
    template <class T>
      constexpr void swap(propagate_const<T>& pt, propagate_const<T>& pt2) noexcept(see below);

    // 3.2.2.10, propagate_const underlying pointer access
    template <class T>
      constexpr const T& get_underlying(const propagate_const<T>& pt) noexcept;
    template <class T>
      constexpr T& get_underlying(propagate_const<T>& pt) noexcept;

  } // inline namespace fundamentals_v3
  } // namespace experimental

  // 3.2.2.11, propagate_const hash support
  template <class T> struct hash;
  template <class T>
    struct hash<experimental::fundamentals_v3::propagate_const<T>>;

  // 3.2.2.12, propagate_const comparison function objects
  template <class T> struct equal_to;
  template <class T>
    struct equal_to<experimental::fundamentals_v3::propagate_const<T>>;
  template <class T> struct not_equal_to;
  template <class T>
    struct not_equal_to<experimental::fundamentals_v3::propagate_const<T>>;
  template <class T> struct less;
  template <class T>
    struct less<experimental::fundamentals_v3::propagate_const<T>>;
  template <class T> struct greater;
  template <class T>
    struct greater<experimental::fundamentals_v3::propagate_const<T>>;
  template <class T> struct less_equal;
  template <class T>
    struct less_equal<experimental::fundamentals_v3::propagate_const<T>>;
  template <class T> struct greater_equal;
  template <class T>
    struct greater_equal<experimental::fundamentals_v3::propagate_const<T>>;

} // namespace std
3.2.2

Class template propagate_const

[propagate_const]
3.2.2.1

Class template propagate_const overview

[propagate_const.overview]
namespace std::experimental {
inline namespace fundamentals_v3 {
  template <class T> class propagate_const {
  public:
    using element_type = remove_reference_t<decltype(*declval<T&>())>;

    // 3.2.2.3, propagate_const constructors
    constexpr propagate_const() = default;
    propagate_const(const propagate_const& p) = delete;
    constexpr propagate_const(propagate_const&& p) = default;
    template <class U>
      see below constexpr propagate_const(propagate_const<U>&& pu);
    template <class U>
      see below constexpr propagate_const(U&& u);

    // 3.2.2.4, propagate_const assignment
    propagate_const& operator=(const propagate_const& p) = delete;
    constexpr propagate_const& operator=(propagate_const&& p) = default;
    template <class U>
      constexpr propagate_const& operator=(propagate_const<U>&& pu);
    template <class U>
      constexpr propagate_const& operator=(U&& u);

    // 3.2.2.5, propagate_const const observers
    explicit constexpr operator bool() const;
    constexpr const element_type* operator->() const;
    constexpr operator const element_type*() const; // Not always defined
    constexpr const element_type& operator*() const;
    constexpr const element_type* get() const;

    // 3.2.2.6, propagate_const non-const observers
    constexpr element_type* operator->();
    constexpr operator element_type*(); // Not always defined
    constexpr element_type& operator*();
    constexpr element_type* get();

    // 3.2.2.7, propagate_const modifiers
    constexpr void swap(propagate_const& pt) noexcept(see below);

  private:
    T t_; //exposition only
  };

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

propagate_const is a wrapper around a pointer-like object type T which treats the wrapped pointer as a pointer to const when the wrapper is accessed through a const access path.

3.2.2.2

propagate_const requirements on T

[propagate_const.requirements]

T shall be an object pointer type or a class type for which decltype(*declval<T&>()) is an lvalue reference; otherwise the program is ill-formed.

If T is an array type, reference type, pointer to function type or pointer to (possibly cv-qualified) void, then the program is ill-formed.

[ Note: propagate_const<const int*> is well-formed end note ]

3.2.2.2.1

propagate_const requirements on class type T

[propagate_const.class_type_requirements]

If T is class type then it shall satisfy the following requirements. In this sub-clause t denotes a non-const lvalue of type T, ct is a const T& bound to t, element_type denotes an object type.

T and const T shall be contextually convertible to bool.

If T is implicitly convertible to element_type*, (element_type*)t == t.get() shall be true.

If const T is implicitly convertible to const element_type*, (const element_type*)ct == ct.get() shall be true.

Table 3 — Requirements on class types T
Expression Return type Pre-conditions Operational semantics
t.get() element_type*
ct.get() const element_type* or element_type* t.get() == ct.get().
*t element_type& t.get() != nullptr *t refers to the same object as *(t.get())
*ct const element_type& or element_type& ct.get() != nullptr *ct refers to the same object as *(ct.get())
t.operator->() element_type* t.get() != nullptr t.operator->() == t.get()
ct.operator->() const element_type* or element_type* ct.get() != nullptr ct.operator->() == ct.get()
(bool)t bool (bool)t is equivalent to t.get() != nullptr
(bool)ct bool (bool)ct is equivalent to ct.get() != nullptr
3.2.2.3

propagate_const constructors

[propagate_const.ctor]

[ Note: The following constructors are conditionally specified as explicit. This is typically implemented by declaring two such constructors, of which at most one participates in overload resolution. end note ]

template <class U>
see below constexpr propagate_const(propagate_const<U>&& pu);
Remarks:
This constructor shall not participate in overload resolution unless is_constructible_v<T, U&&>. The constructor is specified as explicit if and only if !is_convertible_v<U&&, T>.
Effects:
Initializes t_ as if direct-non-list-initializing an object of type T with the expression std::move(pu.t_).
template <class U>
see below constexpr propagate_const(U&& u);
Remarks:
This constructor shall not participate in overload resolution unless is_constructible_v<T, U&&> and decay_t<U> is not a specialization of propagate_const. The constructor is specified as explicit if and only if !is_convertible_v<U&&, T>.
Effects:
Initializes t_ as if direct-non-list-initializing an object of type T with the expression std::forward<U>(u).
3.2.2.4

propagate_const assignment

[propagate_const.assignment]
template <class U>
constexpr propagate_const& operator=(propagate_const<U>&& pu);
Remarks:
This function shall not participate in overload resolution unless U is implicitly convertible to T.
Effects:
t_ = std::move(pu.t_).
Returns:
*this.
template <class U>
constexpr propagate_const& operator=(U&& u);
Remarks:
This function shall not participate in overload resolution unless U is implicitly convertible to T and decay_t<U> is not a specialization of propagate_const.
Effects:
t_ = std::forward<U>(u).
Returns:
*this.
3.2.2.5

propagate_const const observers

[propagate_const.const_observers]
explicit constexpr operator bool() const;
Returns:
(bool)t_.
constexpr const element_type* operator->() const;
Requires:
get() != nullptr.
Returns:
get().
constexpr operator const element_type*() const;
Returns:
get().
Remarks:
This function shall not participate in overload resolution unless T is an object pointer type or has an implicit conversion to const element_type*.
constexpr const element_type& operator*() const;
Requires:
get() != nullptr.
Returns:
*get().
constexpr const element_type* get() const;
Returns:
t_ if T is an object pointer type, otherwise t_.get().
3.2.2.6

propagate_const non-const observers

[propagate_const.non_const_observers]
constexpr element_type* operator->();
Requires:
get() != nullptr.
Returns:
get().
constexpr operator element_type*();
Returns:
get().
Remarks:
This function shall not participate in overload resolution unless T is an object pointer type or has an implicit conversion to element_type*.
constexpr element_type& operator*();
Requires:
get() != nullptr.
Returns:
*get().
constexpr element_type* get();
Returns:
t_ if T is an object pointer type, otherwise t_.get().
3.2.2.7

propagate_const modifiers

[propagate_const.modifiers]
constexpr void swap(propagate_const& pt) noexcept(see below);

The constant-expression in the exception-specification is noexcept(swap(t_, pt.t_)).

Effects:
swap(t_, pt.t_).
3.2.2.8

propagate_const relational operators

[propagate_const.relational]
template <class T>
constexpr bool operator==(const propagate_const<T>& pt, nullptr_t);
Returns:
pt.t_ == nullptr.
template <class T>
constexpr bool operator==(nullptr_t, const propagate_const<T>& pt);
Returns:
nullptr == pt.t_.
template <class T>
constexpr bool operator!=(const propagate_const<T>& pt, nullptr_t);
Returns:
pt.t_ != nullptr.
template <class T>
constexpr bool operator!=(nullptr_t, const propagate_const<T>& pt);
Returns:
nullptr != pt.t_.
template <class T, class U>
constexpr bool operator==(const propagate_const<T>& pt, const propagate_const<U>& pu);
Returns:
pt.t_ == pu.t_.
template <class T, class U>
constexpr bool operator!=(const propagate_const<T>& pt, const propagate_const<U>& pu);
Returns:
pt.t_ != pu.t_.
template <class T, class U>
constexpr bool operator<(const propagate_const<T>& pt, const propagate_const<U>& pu);
Returns:
pt.t_ < pu.t_.
template <class T, class U>
constexpr bool operator>(const propagate_const<T>& pt, const propagate_const<U>& pu);
Returns:
pt.t_ > pu.t_.
template <class T, class U>
constexpr bool operator<=(const propagate_const<T>& pt, const propagate_const<U>& pu);
Returns:
pt.t_ <= pu.t_.
template <class T, class U>
constexpr bool operator>=(const propagate_const<T>& pt, const propagate_const<U>& pu);
Returns:
pt.t_ >= pu.t_.
template <class T, class U>
constexpr bool operator==(const propagate_const<T>& pt, const U& u);
Returns:
pt.t_ == u.
template <class T, class U>
constexpr bool operator!=(const propagate_const<T>& pt, const U& u);
Returns:
pt.t_ != u.
template <class T, class U>
constexpr bool operator<(const propagate_const<T>& pt, const U& u);
Returns:
pt.t_ < u.
template <class T, class U>
constexpr bool operator>(const propagate_const<T>& pt, const U& u);
Returns:
pt.t_ > u.
template <class T, class U>
constexpr bool operator<=(const propagate_const<T>& pt, const U& u);
Returns:
pt.t_ <= u.
template <class T, class U>
constexpr bool operator>=(const propagate_const<T>& pt, const U& u);
Returns:
pt.t_ >= u.
template <class T, class U>
constexpr bool operator==(const T& t, const propagate_const<U>& pu);
Returns:
t == pu.t_.
template <class T, class U>
constexpr bool operator!=(const T& t, const propagate_const<U>& pu);
Returns:
t != pu.t_.
template <class T, class U>
constexpr bool operator<(const T& t, const propagate_const<U>& pu);
Returns:
t < pu.t_.
template <class T, class U>
constexpr bool operator>(const T& t, const propagate_const<U>& pu);
Returns:
t > pu.t_.
template <class T, class U>
constexpr bool operator<=(const T& t, const propagate_const<U>& pu);
Returns:
t <= pu.t_.
template <class T, class U>
constexpr bool operator>=(const T& t, const propagate_const<U>& pu);
Returns:
t >= pu.t_.
3.2.2.9

propagate_const specialized algorithms

[propagate_const.algorithms]
template <class T>
constexpr void swap(propagate_const<T>& pt1, propagate_const<T>& pt2) noexcept(see below);

The constant-expression in the exception-specification is noexcept(pt1.swap(pt2)).

Effects:
pt1.swap(pt2).
3.2.2.10

propagate_const underlying pointer access

[propagate_const.underlying]

Access to the underlying object pointer type is through free functions rather than member functions. These functions are intended to resemble cast operations to encourage caution when using them.

template <class T>
constexpr const T& get_underlying(const propagate_const<T>& pt) noexcept;
Returns:
a reference to the underlying object pointer type.
template <class T>
constexpr T& get_underlying(propagate_const<T>& pt) noexcept;
Returns:
a reference to the underlying object pointer type.
3.2.2.11

propagate_const hash support

[propagate_const.hash]
template <class T>
struct hash<experimental::fundamentals_v3::propagate_const<T>>;

For an object p of type propagate_const<T>, hash<experimental::fundamentals_v3::propagate_const<T>>()(p) shall evaluate to the same value as hash<T>()(p.t_).

Requires:
The specialization hash<T> shall be well-formed and well-defined, and shall meet the requirements of class template hash.
3.2.2.12

propagate_const comparison function objects

[propagate_const.comparison_function_objects]
template <class T>
struct equal_to<experimental::fundamentals_v3::propagate_const<T>>;

For objects p, q of type propagate_const<T>, equal_to<experimental::fundamentals_v3::propagate_const<T>>()(p, q) shall evaluate to the same value as equal_to<T>()(p.t_, q.t_).

Requires:
The specialization equal_to<T> shall be well-formed and well-defined.
template <class T>
struct not_equal_to<experimental::fundamentals_v3::propagate_const<T>>;

For objects p, q of type propagate_const<T>, not_equal_to<experimental::fundamentals_v3::propagate_const<T>>()(p, q) shall evaluate to the same value as not_equal_to<T>()(p.t_, q.t_).

Requires:
The specialization not_equal_to<T> shall be well-formed and well-defined.
template <class T>
struct less<experimental::fundamentals_v3::propagate_const<T>>;

For objects p, q of type propagate_const<T>, less<experimental::fundamentals_v3::propagate_const<T>>()(p, q) shall evaluate to the same value as less<T>()(p.t_, q.t_).

Requires:
The specialization less<T> shall be well-formed and well-defined.
template <class T>
struct greater<experimental::fundamentals_v3::propagate_const<T>>;

For objects p, q of type propagate_const<T>, greater<experimental::fundamentals_v3::propagate_const<T>>()(p, q) shall evaluate to the same value as greater<T>()(p.t_, q.t_).

Requires:
The specialization greater<T> shall be well-formed and well-defined.
template <class T>
struct less_equal<experimental::fundamentals_v3::propagate_const<T>>;

For objects p, q of type propagate_const<T>, less_equal<experimental::fundamentals_v3::propagate_const<T>>()(p, q) shall evaluate to the same value as less_equal<T>()(p.t_, q.t_).

Requires:
The specialization less_equal<T> shall be well-formed and well-defined.
template <class T>
struct greater_equal<experimental::fundamentals_v3::propagate_const<T>>;

For objects p, q of type propagate_const<T>, greater_equal<experimental::fundamentals_v3::propagate_const<T>>()(p, q) shall evaluate to the same value as greater_equal<T>()(p.t_, q.t_).

Requires:
The specialization greater_equal<T> shall be well-formed and well-defined.
3.3

Metaprogramming and type traits

[meta]
3.3.1

Header <experimental/type_traits> synopsis

[meta.type.synop]
#include <type_traits>

namespace std::experimental {
inline namespace fundamentals_v3 {

  // See C++17 §23.15.4.1, primary type categories
  template <class T> constexpr bool is_void_v
    = is_void<T>::value;
  template <class T> constexpr bool is_null_pointer_v
    = is_null_pointer<T>::value;
  template <class T> constexpr bool is_integral_v
    = is_integral<T>::value;
  template <class T> constexpr bool is_floating_point_v
    = is_floating_point<T>::value;
  template <class T> constexpr bool is_array_v
    = is_array<T>::value;
  template <class T> constexpr bool is_pointer_v
    = is_pointer<T>::value;
  template <class T> constexpr bool is_lvalue_reference_v
    = is_lvalue_reference<T>::value;
  template <class T> constexpr bool is_rvalue_reference_v
    = is_rvalue_reference<T>::value;
  template <class T> constexpr bool is_member_object_pointer_v
    = is_member_object_pointer<T>::value;
  template <class T> constexpr bool is_member_function_pointer_v
    = is_member_function_pointer<T>::value;
  template <class T> constexpr bool is_enum_v
    = is_enum<T>::value;
  template <class T> constexpr bool is_union_v
    = is_union<T>::value;
  template <class T> constexpr bool is_class_v
    = is_class<T>::value;
  template <class T> constexpr bool is_function_v
    = is_function<T>::value;

  // See C++17 §23.15.4.2, composite type categories
  template <class T> constexpr bool is_reference_v
    = is_reference<T>::value;
  template <class T> constexpr bool is_arithmetic_v
    = is_arithmetic<T>::value;
  template <class T> constexpr bool is_fundamental_v
    = is_fundamental<T>::value;
  template <class T> constexpr bool is_object_v
    = is_object<T>::value;
  template <class T> constexpr bool is_scalar_v
    = is_scalar<T>::value;
  template <class T> constexpr bool is_compound_v
    = is_compound<T>::value;
  template <class T> constexpr bool is_member_pointer_v
    = is_member_pointer<T>::value;

  // See C++17 §23.15.4.3, type properties
  template <class T> constexpr bool is_const_v
    = is_const<T>::value;
  template <class T> constexpr bool is_volatile_v
    = is_volatile<T>::value;
  template <class T> constexpr bool is_trivial_v
    = is_trivial<T>::value;
  template <class T> constexpr bool is_trivially_copyable_v
    = is_trivially_copyable<T>::value;
  template <class T> constexpr bool is_standard_layout_v
    = is_standard_layout<T>::value;
  template <class T> constexpr bool is_pod_v
    = is_pod<T>::value;
  template <class T> constexpr bool is_literal_type_v
    = is_literal_type<T>::value;
  template <class T> constexpr bool is_empty_v
    = is_empty<T>::value;
  template <class T> constexpr bool is_polymorphic_v
    = is_polymorphic<T>::value;
  template <class T> constexpr bool is_abstract_v
    = is_abstract<T>::value;
  template <class T> constexpr bool is_final_v
    = is_final<T>::value;
  template <class T> constexpr bool is_signed_v
    = is_signed<T>::value;
  template <class T> constexpr bool is_unsigned_v
    = is_unsigned<T>::value;
  template <class T, class... Args> constexpr bool is_constructible_v
    = is_constructible<T, Args...>::value;
  template <class T> constexpr bool is_default_constructible_v
    = is_default_constructible<T>::value;
  template <class T> constexpr bool is_copy_constructible_v
    = is_copy_constructible<T>::value;
  template <class T> constexpr bool is_move_constructible_v
    = is_move_constructible<T>::value;
  template <class T, class U> constexpr bool is_assignable_v
    = is_assignable<T, U>::value;
  template <class T> constexpr bool is_copy_assignable_v
    = is_copy_assignable<T>::value;
  template <class T> constexpr bool is_move_assignable_v
    = is_move_assignable<T>::value;
  template <class T> constexpr bool is_destructible_v
    = is_destructible<T>::value;
  template <class T, class... Args> constexpr bool is_trivially_constructible_v
    = is_trivially_constructible<T, Args...>::value;
  template <class T> constexpr bool is_trivially_default_constructible_v
    = is_trivially_default_constructible<T>::value;
  template <class T> constexpr bool is_trivially_copy_constructible_v
    = is_trivially_copy_constructible<T>::value;
  template <class T> constexpr bool is_trivially_move_constructible_v
    = is_trivially_move_constructible<T>::value;
  template <class T, class U> constexpr bool is_trivially_assignable_v
    = is_trivially_assignable<T, U>::value;
  template <class T> constexpr bool is_trivially_copy_assignable_v
    = is_trivially_copy_assignable<T>::value;
  template <class T> constexpr bool is_trivially_move_assignable_v
    = is_trivially_move_assignable<T>::value;
  template <class T> constexpr bool is_trivially_destructible_v
    = is_trivially_destructible<T>::value;
  template <class T, class... Args> constexpr bool is_nothrow_constructible_v
    = is_nothrow_constructible<T, Args...>::value;
  template <class T> constexpr bool is_nothrow_default_constructible_v
    = is_nothrow_default_constructible<T>::value;
  template <class T> constexpr bool is_nothrow_copy_constructible_v
    = is_nothrow_copy_constructible<T>::value;
  template <class T> constexpr bool is_nothrow_move_constructible_v
    = is_nothrow_move_constructible<T>::value;
  template <class T, class U> constexpr bool is_nothrow_assignable_v
    = is_nothrow_assignable<T, U>::value;
  template <class T> constexpr bool is_nothrow_copy_assignable_v
    = is_nothrow_copy_assignable<T>::value;
  template <class T> constexpr bool is_nothrow_move_assignable_v
    = is_nothrow_move_assignable<T>::value;
  template <class T> constexpr bool is_nothrow_destructible_v
    = is_nothrow_destructible<T>::value;
  template <class T> constexpr bool has_virtual_destructor_v
    = has_virtual_destructor<T>::value;

  // See C++17 §23.15.5, type property queries
  template <class T> constexpr size_t alignment_of_v
    = alignment_of<T>::value;
  template <class T> constexpr size_t rank_v
    = rank<T>::value;
  template <class T, unsigned I = 0> constexpr size_t extent_v
    = extent<T, I>::value;

  // See C++17 §23.15.6, type relations
  template <class T, class U> constexpr bool is_same_v
    = is_same<T, U>::value;
  template <class Base, class Derived> constexpr bool is_base_of_v
    = is_base_of<Base, Derived>::value;
  template <class From, class To> constexpr bool is_convertible_v
    = is_convertible<From, To>::value;

  // 3.3.2, Other type transformations
  template <class> class invocation_type; // not defined
  template <class F, class... ArgTypes> class invocation_type<F(ArgTypes...)>;
  template <class> class raw_invocation_type; // not defined
  template <class F, class... ArgTypes> class raw_invocation_type<F(ArgTypes...)>;

  template <class T>
    using invocation_type_t = typename invocation_type<T>::type;
  template <class T>
    using raw_invocation_type_t = typename raw_invocation_type<T>::type;

  // 3.3.3, Detection idiom
  template <class...> using void_t = void;

  struct nonesuch {
    nonesuch() = delete;
    ~nonesuch() = delete;
    nonesuch(nonesuch const&) = delete;

    void operator=(nonesuch const&) = delete;
  };

  template <template<class...> class Op, class... Args>
    using is_detected = see below;
  template <template<class...> class Op, class... Args>
    constexpr bool is_detected_v = is_detected<Op, Args...>::value;
  template <template<class...> class Op, class... Args>
    using detected_t = see below;
  template <class Default, template<class...> class Op, class... Args>
    using detected_or = see below;
  template <class Default, template<class...> class Op, class... Args>
    using detected_or_t = typename detected_or<Default, Op, Args...>::type;
  template <class Expected, template<class...> class Op, class... Args>
    using is_detected_exact = is_same<Expected, detected_t<Op, Args...>>;
  template <class Expected, template<class...> class Op, class... Args>
    constexpr bool is_detected_exact_v
      = is_detected_exact<Expected, Op, Args...>::value;
  template <class To, template<class...> class Op, class... Args>
    using is_detected_convertible = is_convertible<detected_t<Op, Args...>, To>;
  template <class To, template<class...> class Op, class... Args>
    constexpr bool is_detected_convertible_v
      = is_detected_convertible<To, Op, Args...>::value;

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

Other type transformations

[meta.trans.other]

This sub-clause contains templates that may be used to transform one type to another following some predefined rule.

Each of the templates in this subclause shall be a TransformationTrait (C++17 §23.15.1).

Within this section, define the invocation parameters of INVOKE(f, t1, t2, ..., tN) as follows, in which T1 is the possibly cv-qualified type of t1 and U1 denotes T1& if t1 is an lvalue or T1&& if t1 is an rvalue:

  • When f is a pointer to a member function of a class T the invocation parameters are U1 followed by the parameters of f matched by t2, ..., tN.
  • When N == 1 and f is a pointer to member data of a class T the invocation parameter is U1.
  • If f is a class object, the invocation parameters are the parameters matching t1, ..., tN of the best viable function (C++17 §16.3.3) for the arguments t1, ..., tN among the function call operators and surrogate call functions of f.
  • In all other cases, the invocation parameters are the parameters of f matching t1, ... tN.

In all of the above cases, if an argument tI matches the ellipsis in the function's parameter-declaration-clause, the corresponding invocation parameter is defined to be the result of applying the default argument promotions (C++17 §8.2.2) to tI.

[ Example: Assume S is defined as
struct S {
  int f(double const &) const;
  void operator()(int, int);
  void operator()(char const *, int i = 2, int j = 3);
  void operator()(...);
};
  • The invocation parameters of INVOKE(&S::f, S(), 3.5) are (S &&, double const &).
  • The invocation parameters of INVOKE(S(), 1, 2) are (int, int).
  • The invocation parameters of INVOKE(S(), "abc", 5) are (const char *, int). The defaulted parameter j does not correspond to an argument.
  • The invocation parameters of INVOKE(S(), locale(), 5) are (locale, int). Arguments corresponding to ellipsis maintain their types.
end example ]
Table 4 — Other type transformations
TemplateConditionComments
template <class Fn, class... ArgTypes>
struct raw_invocation_type<Fn(ArgTypes...)>;
Fn and all types in the parameter pack ArgTypes shall be complete types, (possibly cv-qualified) void, or arrays of unknown bound. see below
template <class Fn, class... ArgTypes>
struct invocation_type<Fn(ArgTypes...)>;
Fn and all types in the parameter pack ArgTypes shall be complete types, (possibly cv-qualified) void, or arrays of unknown bound. see below

Access checking is performed as if in a context unrelated to Fn and ArgTypes. Only the validity of the immediate context of the expression is considered. [ Note: The compilation of the expression can result in side effects such as the instantiation of class template specializations and function template specializations, the generation of implicitly-defined functions, and so on. Such side effects are not in the "immediate context" and can result in the program being ill-formed. end note ]

The member raw_invocation_type<Fn(ArgTypes...)>::type shall be defined as follows. If the expression INVOKE(declval<Fn>(), declval<ArgTypes>()...) is ill-formed when treated as an unevaluated operand (C++17 §8), there shall be no member type. Otherwise:

  • Let R denote result_of_t<Fn(ArgTypes...)>.
  • Let the types Ti be the invocation parameters of INVOKE(declval<Fn>(), declval<ArgTypes>()...).
  • Then the member type shall name the function type R(T1, T2, ...).

The member invocation_type<Fn(ArgTypes...)>::type shall be defined as follows. If raw_invocation_type<Fn(ArgTypes...)>::type does not exist, there shall be no member type. Otherwise:

  • Let A1, A2, … denote ArgTypes...
  • Let R(T1, T2, …) denote raw_invocation_type_t<Fn(ArgTypes...)>
  • Then the member type shall name the function type R(U1, U2, …) where Ui is decay_t<Ai> if declval<Ai>() is an rvalue otherwise Ti.
3.3.3

Detection idiom

[meta.detect]
template <class Default, class AlwaysVoid,
          template<class...> class Op, class... Args>
struct DETECTOR { // exposition only
  using value_t = false_type;
  using type = Default;
};

template <class Default, template<class...> class Op, class... Args>
struct DETECTOR<Default, void_t<Op<Args...>>, Op, Args...> { // exposition only
  using value_t = true_type;
  using type = Op<Args...>;
};

template <template<class...> class Op, class... Args>
  using is_detected = typename DETECTOR<nonesuch, void, Op, Args...>::value_t;

template <template<class...> class Op, class... Args>
  using detected_t = typename DETECTOR<nonesuch, void, Op, Args...>::type;

template <class Default, template<class...> class Op, class... Args>
  using detected_or = DETECTOR<Default, void, Op, Args...>;
[ Example:
// archetypal helper alias for a copy assignment operation:
template <class T>
  using copy_assign_t = decltype(declval<T&>() = declval<T const &>());

// plausible implementation for the is_assignable type trait:
template <class T>
  using is_copy_assignable = is_detected<copy_assign_t, T>;

// plausible implementation for an augmented is_assignable type trait
// that also checks the return type:
template <class T>
  using is_canonical_copy_assignable = is_detected_exact<T&, copy_assign_t, T>;
end example ]
[ Example:
// archetypal helper alias for a particular type member:
template <class T>
  using diff_t = typename T::difference_type;

// alias the type member, if it exists, otherwise alias ptrdiff_t:
template <class Ptr>
  using difference_type = detected_or_t<ptrdiff_t, diff_t, Ptr>;
end example ]
4

Function objects

[func]
4.1

Header <experimental/functional> synopsis

[header.functional.synop]
#include <functional>

namespace std {
  namespace experimental {
  inline namespace fundamentals_v3 {

    // See C++17 §, Function object binders
    template <class T> constexpr bool is_bind_expression_v
      = is_bind_expression<T>::value;
    template <class T> constexpr int is_placeholder_v
      = is_placeholder<T>::value;

    // 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 fundamentals_v3
  } // namespace experimental

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

} // namespace std
4.2

Class template function

[func.wrap.func]

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++17 §23.14.13.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 namespace 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 fundamentals_v3
  } // namespace experimental

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

} // namespace std
4.2.1

function construct/copy/destroy

[func.wrap.func.con]

When a function 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). If the constructor moves or makes a copy of a function object (C++17 §23.14), including an instance of the experimental::function class template, then that move or copy is performed by using-allocator construction with allocator get_memory_resource().

In the following descriptions, let ALLOCATOR_OF(f) be the allocator specified in the construction of function f, or the value of experimental::pmr::get_default_resource() at the time of the construction of f if no allocator was specified.

function& operator=(const function& f);
Effects:
function(allocator_arg, ALLOCATOR_OF(*this), f).swap(*this);
Returns:
*this.
function& operator=(function&& f);
Effects:
function(allocator_arg, ALLOCATOR_OF(*this), std::move(f)).swap(*this);
Returns:
*this.
function& operator=(nullptr_t) noexcept;
Effects:
If *this != nullptr, destroys the target of this.
Postconditions:
!(*this). The memory resource returned by get_memory_resource() after the assignment is equivalent to the memory resource before the assignment. [ Note: the address returned by get_memory_resource() might change end note ]
Returns:
*this.
template<class F> function& operator=(F&& f);
Effects:
function(allocator_arg, ALLOCATOR_OF(*this), std::forward<F>(f)).swap(*this);
Returns:
*this.
Remarks:
This assignment operator shall not participate in overload resolution unless declval<decay_t<F>&>() is Callable (C++17 §23.14.13.2) for argument types ArgTypes... and return type R.
template<class F> function& operator=(reference_wrapper<F> f);
Effects:
function(allocator_arg, ALLOCATOR_OF(*this), f).swap(*this);
Returns:
*this.
4.2.2

function modifiers

[func.wrap.func.mod]
void swap(function& other);
Requires:
*this->get_memory_resource() == *other.get_memory_resource().
Effects:
Interchanges the targets of *this and other.
Remarks:
The allocators of *this and other are not interchanged.
5

Memory

[memory]
5.1

Header <experimental/memory> synopsis

[header.memory.synop]
#include <memory>

namespace std {
  namespace experimental {
  inline namespace fundamentals_v3 {

    // See C++17 §23.10.7, uses_allocator
    template <class T, class Alloc> constexpr bool uses_allocator_v
      = uses_allocator<T, Alloc>::value;

    // 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>);

  } // inline namespace fundamentals_v3
  } // namespace experimental

  // , 
  template<class T> struct hash<experimental::shared_ptr<T>>;

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

} // namespace std
5.2

Non-owning pointers

[memory.observer.ptr]

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 CopyConstructible and CopyAssignable 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 ]

5.2.1

Class template observer_ptr overview

[memory.observer.ptr.overview]
namespace std::experimental {
inline namespace 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 c’tor
    constexpr observer_ptr() noexcept;

    // pointer-accepting c’tors
    constexpr observer_ptr(nullptr_t) noexcept;
    constexpr explicit observer_ptr(pointer) noexcept;

    // copying c’tors (in addition to compiler-generated copy c’tor)
    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<>

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

observer_ptr constructors

[memory.observer.ptr.ctor]
constexpr observer_ptr() noexcept;constexpr observer_ptr(nullptr_t) noexcept;
Effects:
Constructs an observer_ptr object that has no corresponding watched object.
Postconditions:
get() == nullptr.
constexpr explicit observer_ptr(pointer other) noexcept;
Postconditions:
get() == other.
template <class W2> constexpr observer_ptr(observer_ptr<W2> other) noexcept;
Postconditions:
get() == other.get().
Remarks:
This constructor shall not participate in overload resolution unless W2* is convertible to W*.
5.2.3

observer_ptr observers

[memory.observer.ptr.obs]
constexpr pointer get() const noexcept;
Returns:
The stored pointer.
constexpr reference operator*() const;
Requires:
get() != nullptr.
Returns:
*get().
Throws:
Nothing.
constexpr pointer operator->() const noexcept;
Returns:
get().
constexpr explicit operator bool() const noexcept;
Returns:
get() != nullptr.
5.2.4

observer_ptr conversions

[memory.observer.ptr.conv]
constexpr explicit operator pointer() const noexcept;
Returns:
get().
5.2.5

observer_ptr modifiers

[memory.observer.ptr.mod]
constexpr pointer release() noexcept;
Postconditions:
get() == nullptr.
Returns:
The value get() had at the start of the call to release.
constexpr void reset(pointer p = nullptr) noexcept;
Postconditions:
get() == p.
constexpr void swap(observer_ptr& other) noexcept;
Effects:
Invokes swap on the stored pointers of *this and other.
5.2.6

observer_ptr specialized algorithms

[memory.observer.ptr.special]
template <class W>
void swap(observer_ptr<W>& p1, observer_ptr<W>& p2) noexcept;
Effects:
p1.swap(p2).
template <class W> observer_ptr<W> make_observer(W* p) noexcept;
Returns:
observer_ptr<W>{p}.
template <class W1, class W2>
bool operator==(observer_ptr<W1> p1, observer_ptr<W2> p2);
Returns:
p1.get() == p2.get().
template <class W1, class W2>
bool operator!=(observer_ptr<W1> p1, observer_ptr<W2> p2);
Returns:
not (p1 == 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;
Returns:
not p.
template <class W>
bool operator!=(observer_ptr<W> p, nullptr_t) noexcept;template <class W>
bool operator!=(nullptr_t, observer_ptr<W> p) noexcept;
Returns:
(bool)p.
template <class W1, class W2>
bool operator<(observer_ptr<W1> p1, observer_ptr<W2> p2);
Returns:
less<W3>()(p1.get(), p2.get()), where W3 is the composite pointer type (C++17 §8) of W1* and W2*.
template <class W1, class W2>
bool operator>(observer_ptr<W1> p1, observer_ptr<W2> p2);
Returns:
p2 < p1.
template <class W1, class W2>
bool operator<=(observer_ptr<W1> p1, observer_ptr<W2> p2);
Returns:
not (p2 < p1).
template <class W1, class W2>
bool operator>=(observer_ptr<W1> p1, observer_ptr<W2> p2);
Returns:
not (p1 < p2).
5.2.7

observer_ptr hash support

[memory.observer.ptr.hash]
template <class T> struct hash<experimental::observer_ptr<T>>;

The template specialization shall meet the requirements of class template hash (C++17 §23.14.15). For an object p of type observer_ptr<T>, hash<observer_ptr<T>>()(p) shall evaluate to the same value as hash<T*>()(p.get()).

5.3

Type-erased allocator

[memory.type.erased.allocator]

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++17 §23.12.2). The process by which rptr is computed from alloc depends on the type of alloc as described in Table 5:

Table 5 — Computed memory_resource for type-erased allocator
If the type of alloc is then the value of rptr is
non-existent — no alloc specified The value of pmr::get_default_resource() at the time of construction.
nullptr_t The value of pmr::get_default_resource() at the time of construction.
a pointer type convertible to pmr::memory_resource* static_cast<pmr::memory_resource*>(alloc)
pmr::polymorphic_allocator<U> alloc.resource()
any other type meeting the Allocator requirements (C++17 §20.5.3.5) a pointer to a value of type pmr::resource_adaptor<A> where A is the type of alloc. rptr remains valid only for the lifetime of X.
None of the above The program is ill-formed.

Additionally, class C shall meet the following requirements:

  • C::allocator_type shall be identical to std::experimental::erased_type.
  • X.get_memory_resource() returns rptr.
5.4

Header <experimental/memory_resource> synopsis

[memory.resource.synop]
namespace std::experimental {
inline namespace fundamentals_v3 {
namespace 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 pmr
} // inline namespace fundamentals_v3
} // namespace std::experimental
5.5

template alias resource_adaptor

[memory.resource.adaptor]
5.5.1

resource_adaptor

[memory.resource.adaptor.overview]

An instance of resource_adaptor<Allocator> is an adaptor that wraps a memory_resource interface around Allocator. In order that resource_adaptor<X<T>> and resource_adaptor<X<U>> are the same type for any allocator template X and types T and U, resource_adaptor<Allocator> is rendered as an alias to a class template such that Allocator is rebound to a char value type in every specialization of the class template. The requirements on this class template are defined below. The name resource_adaptor_imp is for exposition only and is not normative, but the definitions of the members of that class, whatever its name, are normative. In addition to the Allocator requirements (C++17 §20.5.3.5), the parameter to resource_adaptor shall meet the following additional requirements:

  • typename allocator_traits<Allocator>::pointer shall be identical to typename allocator_traits<Allocator>::value_type*.
  • typename allocator_traits<Allocator>::const_pointer shall be identical to typename allocator_traits<Allocator>::value_type const*.
  • typename allocator_traits<Allocator>::void_pointer shall be identical to void*.
  • typename allocator_traits<Allocator>::const_void_pointer shall be identical to void const*.

// The name resource_adaptor_imp is for exposition only.
template <class Allocator>
class resource_adaptor_imp : public memory_resource {
  // for exposition only
  Allocator m_alloc;

public:
  using allocator_type = Allocator;

  resource_adaptor_imp() = default;
  resource_adaptor_imp(const resource_adaptor_imp&) = default;
  resource_adaptor_imp(resource_adaptor_imp&&) = default;

  explicit resource_adaptor_imp(const Allocator& a2);
  explicit resource_adaptor_imp(Allocator&& a2);

  resource_adaptor_imp& operator=(const resource_adaptor_imp&) = default;

  allocator_type get_allocator() const { return m_alloc; }

protected:
  virtual void* do_allocate(size_t bytes, size_t alignment);
  virtual void do_deallocate(void* p, size_t bytes, size_t alignment);

  virtual bool do_is_equal(const memory_resource& other) const noexcept;
};

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

resource_adaptor_imp constructors

[memory.resource.adaptor.ctor]
explicit resource_adaptor_imp(const Allocator& a2);
Effects:
Initializes m_alloc with a2.
explicit resource_adaptor_imp(Allocator&& a2);
Effects:
Initializes m_alloc with std::move(a2).
5.5.3

resource_adaptor_imp member functions

[memory.resource.adaptor.mem]
void* do_allocate(size_t bytes, size_t alignment);
Returns:
Allocated memory obtained by calling m_alloc.allocate. The size and alignment of the allocated memory shall meet the requirements for a class derived from memory_resource ().
void do_deallocate(void* p, size_t bytes, size_t alignment);
Requires:
p was previously allocated using A.allocate, where A == m_alloc, and not subsequently deallocated.
Effects:
Returns memory to the allocator using m_alloc.deallocate().
bool do_is_equal(const memory_resource& other) const noexcept;

Let p be dynamic_cast<const resource_adaptor_imp*>(&other).

Returns:
false if p is null, otherwise the value of m_alloc == p->m_alloc.
6

Containers

[container]
6.1

Uniform container erasure

[container.erasure]
6.1.1

Header synopsis

[container.erasure.syn]

For brevity, this section specifies the contents of 9 headers, each of which behaves as described by 1.3.

namespace std::experimental {
inline namespace fundamentals_v3 {

  // 6.1.2, Function template erase_if
  // 6.1.3, Function template erase

  // <experimental/string>
  template <class charT, class traits, class A, class Predicate>
    void erase_if(basic_string<charT, traits, A>& c, Predicate pred);
  template <class charT, class traits, class A, class U>
    void erase(basic_string<charT, traits, A>& c, const U& value);

  // <experimental/deque>
  template <class T, class A, class Predicate>
    void erase_if(deque<T, A>& c, Predicate pred);
  template <class T, class A, class U>
    void erase(deque<T, A>& c, const U& value);

  // <experimental/vector>
  template <class T, class A, class Predicate>
    void erase_if(vector<T, A>& c, Predicate pred);
  template <class T, class A, class U>
    void erase(vector<T, A>& c, const U& value);

  // <experimental/forward_list>
  template <class T, class A, class Predicate>
    void erase_if(forward_list<T, A>& c, Predicate pred);
  template <class T, class A, class U>
    void erase(forward_list<T, A>& c, const U& value);

  // <experimental/list>
  template <class T, class A, class Predicate>
    void erase_if(list<T, A>& c, Predicate pred);
  template <class T, class A, class U>
    void erase(list<T, A>& c, const U& value);

  // <experimental/map>
  template <class K, class T, class C, class A, class Predicate>
    void erase_if(map<K, T, C, A>& c, Predicate pred);
  template <class K, class T, class C, class A, class Predicate>
    void erase_if(multimap<K, T, C, A>& c, Predicate pred);

  // <experimental/set>
  template <class K, class C, class A, class Predicate>
    void erase_if(set<K, C, A>& c, Predicate pred);
  template <class K, class C, class A, class Predicate>
    void erase_if(multiset<K, C, A>& c, Predicate pred);

  // <experimental/unordered_map>
  template <class K, class T, class H, class P, class A, class Predicate>
    void erase_if(unordered_map<K, T, H, P, A>& c, Predicate pred);
  template <class K, class T, class H, class P, class A, class Predicate>
    void erase_if(unordered_multimap<K, T, H, P, A>& c, Predicate pred);

  // <experimental/unordered_set>
  template <class K, class H, class P, class A, class Predicate>
    void erase_if(unordered_set<K, H, P, A>& c, Predicate pred);
  template <class K, class H, class P, class A, class Predicate>
    void erase_if(unordered_multiset<K, H, P, A>& c, Predicate pred);

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

Function template erase_if

[container.erasure.erase_if]
template <class charT, class traits, class A, class Predicate>
void erase_if(basic_string<charT, traits, A>& c, Predicate pred);template <class T, class A, class Predicate>
void erase_if(deque<T, A>& c, Predicate pred);template <class T, class A, class Predicate>
void erase_if(vector<T, A>& c, Predicate pred);
Effects:
Equivalent to: c.erase(remove_if(c.begin(), c.end(), pred), c.end());
template <class T, class A, class Predicate>
void erase_if(forward_list<T, A>& c, Predicate pred);template <class T, class A, class Predicate>
void erase_if(list<T, A>& c, Predicate pred);
Effects:
Equivalent to: c.remove_if(pred);
template <class K, class T, class C, class A, class Predicate>
void erase_if(map<K, T, C, A>& c, Predicate pred);template <class K, class T, class C, class A, class Predicate>
void erase_if(multimap<K, T, C, A>& c, Predicate pred);template <class K, class C, class A, class Predicate>
void erase_if(set<K, C, A>& c, Predicate pred);template <class K, class C, class A, class Predicate>
void erase_if(multiset<K, C, A>& c, Predicate pred);template <class K, class T, class H, class P, class A, class Predicate>
void erase_if(unordered_map<K, T, H, P, A>& c, Predicate pred);template <class K, class T, class H, class P, class A, class Predicate>
void erase_if(unordered_multimap<K, T, H, P, A>& c, Predicate pred);template <class K, class H, class P, class A, class Predicate>
void erase_if(unordered_set<K, H, P, A>& c, Predicate pred);template <class K, class H, class P, class A, class Predicate>
void erase_if(unordered_multiset<K, H, P, A>& c, Predicate pred);
Effects:
Equivalent to:
for (auto i = c.begin(), last = c.end(); i != last; ) {
  if (pred(*i)) {
    i = c.erase(i);
  } else {
    ++i;
  }
}
6.1.3

Function template erase

[container.erasure.erase]
template <class charT, class traits, class A, class U>
void erase(basic_string<charT, traits, A>& c, const U& value);template <class T, class A, class U>
void erase(deque<T, A>& c, const U& value);template <class T, class A, class U>
void erase(vector<T, A>& c, const U& value);
Effects:
Equivalent to: c.erase(remove(c.begin(), c.end(), value), c.end());
template <class T, class A, class U>
void erase(forward_list<T, A>& c, const U& value);template <class T, class A, class U>
void erase(list<T, A>& c, const U& value);
Effects:
Equivalent to: erase_if(c, [&](auto& elem) { return elem == value; });
[ Note: Overloads of erase() for associative containers and unordered associative containers are intentionally not provided. end note ]
6.2

Class template array

[container.array]
6.2.1

Header <experimental/array> synopsis

[header.array.synop]
#include <array>

namespace std::experimental {
inline namespace fundamentals_v3 {

  // 6.2.2, Array creation functions
  template <class D = void, class... Types>
    constexpr array<VT, sizeof...(Types)> make_array(Types&&... t);
  template <class T, size_t N>
    constexpr array<remove_cv_t<T>, N> to_array(T (&a)[N]);

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

Array creation functions

[container.array.creation]
template <class D = void, class... Types>
  constexpr array<VT, sizeof...(Types)> make_array(Types&&... t);

Let Ui be decay_t<Ti> for each Ti in Types.

Remarks:
The program is ill-formed if D is void and at least one Ui is a specialization of reference_wrapper.
Returns:
array<VT, sizeof...(Types)>{ std::forward<Types>(t)... }, where VT is common_type_t<Types...> if D is void, otherwise VT is D.
[ Example:
int i = 1; int& ri = i;
auto a1 = make_array(i, ri);         // a1 is of type array<int, 2>
auto a2 = make_array(i, ri, 42L);    // a2 is of type array<long, 3>
auto a3 = make_array<long>(i, ri);   // a3 is of type array<long, 2>
auto a4 = make_array<long>();        // a4 is of type array<long, 0>
auto a5 = make_array();              // ill-formed
end example ]
template <class T, size_t N>
constexpr array<remove_cv_t<T>, N> to_array(T (&a)[N]);
Returns:
An array<remove_cv_t<T>, N> such that each element is copy-initialized with the corresponding element of a.
7

Iterators library

[iterator]
7.1

Header <experimental/iterator> synopsis

[iterator.synopsis]
#include <iterator>

namespace std::experimental {
inline namespace fundamentals_v3 {

  // 7.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);

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

Class template ostream_joiner

[iterator.ostream.joiner]

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 namespace 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
  };

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

ostream_joiner constructor

[iterator.ostream.joiner.cons]
ostream_joiner(ostream_type& s, const DelimT& delimiter);
Effects:
Initializes out_stream with std::addressof(s), delim with delimiter, and first_element with true.
ostream_joiner(ostream_type& s, DelimT&& delimiter);
Effects:
Initializes out_stream with std::addressof(s), delim with move(delimiter), and first_element with true.
7.2.2

ostream_joiner operations

[iterator.ostream.joiner.ops]
template<typename T>
ostream_joiner& operator=(const T& value);
Effects:
if (!first_element)
  *out_stream << delim;
first_element = false;
*out_stream << value;
return *this;
ostream_joiner& operator*() noexcept;
Returns:
*this.
ostream_joiner& operator++() noexcept;ostream_joiner& operator++(int) noexcept;
Returns:
*this.
7.2.3

ostream_joiner creation function

[iterator.ostream.joiner.creation]
template <class charT, class traits, class DelimT>
ostream_joiner<decay_t<DelimT>, charT, traits>
make_ostream_joiner(basic_ostream<charT, traits>& os, DelimT&& delimiter);
Returns:
ostream_joiner<decay_t<DelimT>, charT, traits>(os, forward<DelimT>(delimiter));
8

Futures

[futures]
8.1

Header <experimental/future> synopsis

[header.future.synop]
#include <future>

namespace std {
  namespace experimental {
  inline namespace 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 fundamentals_v3
  } // namespace experimental

  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
8.2

Class template promise

[futures.promise]

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

namespace std {
  namespace experimental {
  inline namespace 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 fundamentals_v3
  } // namespace experimental

  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).

8.3

Class template packaged_task

[futures.task]

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

namespace std {
  namespace experimental {
  inline namespace 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 fundamentals_v3
  } // namespace experimental

  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).

9

Algorithms library

[algorithms]
9.1

Header <experimental/algorithm> synopsis

[header.algorithm.synop]
#include <algorithm>

namespace std::experimental {
inline namespace fundamentals_v3 {

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

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

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

Sampling

[alg.random.sample]
template<class PopulationIterator, class SampleIterator, class Distance>
SampleIterator sample(PopulationIterator first, PopulationIterator last,
                      SampleIterator out, Distance n);
Effects:
Equivalent to:
return ::std::sample(first, last, out, n, g);
where g denotes the per-thread engine (10.1.2.1). To the extent that the implementation of this function makes use of random numbers, the object g shall serve as the implementation’s source of randomness.
9.3

Shuffle

[alg.random.shuffle]
template<class RandomAccessIterator>
  void shuffle(RandomAccessIterator first, RandomAccessIterator last);
Effects:
Permutes the elements in the range [first,last) such that each possible permutation of those elements has equal probability of appearance.
Requires:
RandomAccessIterator shall satisfy the requirements of ValueSwappable (C++17 §20.5.3.2).
Complexity:
Exactly (last - first) - 1 swaps.
Remarks:
To the extent that the implementation of this function makes use of random numbers, the per-thread engine (10.1.2.1) shall serve as the implementation's source of randomness.
10

Numerics library

[numeric]
10.1

Random number generation

[rand]
10.1.1

Header <experimental/random> synopsis

[rand.synopsis]
#include <random>

namespace std::experimental {
inline namespace fundamentals_v3 {

  // 10.1.2.1, Function template randint
  template <class IntType>
  IntType randint(IntType a, IntType b);
  void reseed();
  void reseed(default_random_engine::result_type value);

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

Utilities

[rand.util]
10.1.2.1

Function template randint

[rand.util.randint]

A separate per-thread engine of type default_random_engine (C++17 §29.6.5), initialized to an unpredictable state, shall be maintained for each thread.

template<class IntType>
IntType randint(IntType a, IntType b);
Requires:
ab.
Remarks:
If the template argument does not meet the requirements for IntType (C++17 §29.6.1.1), the program is ill-formed.
Returns:
A random integer i, aib, produced from a thread-local instance of uniform_int_distribution<IntType> (C++17 §29.6.8.2.1) invoked with the per-thread engine.
void reseed();void reseed(default_random_engine::result_type value);
Effects:
Let g be the per-thread engine. The first form sets g to an unpredictable state. The second form invokes g.seed(value).
Postconditions:
Subsequent calls to randint do not depend on values produced by g before calling reseed. [ Note: reseed also resets any instances of uniform_int_distribution used by randint. end note ]
11

Reflection library

[reflection]
11.1

Header <experimental/source_location> synopsis

[reflection.src_loc.synop]
namespace std::experimental {
inline namespace fundamentals_v3 {

  struct source_location;

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

Class source_location

[reflection.src_loc]
namespace std::experimental {
inline namespace fundamentals_v3 {

  struct source_location {
    // 11.2.1, source_location creation
    static constexpr source_location current() noexcept;

    constexpr source_location() noexcept;

    // 11.2.2, source_location field access
    constexpr uint_least32_t line() const noexcept;
    constexpr uint_least32_t column() const noexcept;
    constexpr const char* file_name() const noexcept;
    constexpr const char* function_name() const noexcept;
  };

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

[ Note: The intent of source_location is to have a small size and efficient copying. end note ]

11.2.1

source_location creation

[reflection.src_loc.creation]
static constexpr source_location current() noexcept;
Returns:
When invoked by a function call (C++17 §8.2.2) whose postfix-expression is a (possibly parenthesized) id-expression naming current, returns a source_location with an implementation-defined value. The value should be affected by #line (C++17 §19.4) in the same manner as for __LINE__ and __FILE__. If invoked in some other way, the value returned is unspecified.
Remarks:
When a brace-or-equal-initializer is used to initialize a non-static data member, any calls to current should correspond to the location of the constructor or aggregate initialization that initializes the member.

[ Note: When used as a default argument (C++17 §11.3.6), the value of the source_location will be the location of the call to current at the call site. end note ]

[ Example:
struct s {
  source_location member = source_location::current();
  int other_member;
  s(source_location loc = source_location::current())
    : member(loc) // values of member will be from call-site
  {}
  s(int blather) : // values of member should be hereabouts
    other_member(blather) {}
  s(double) // values of member should be hereabouts
  {}
};

void f(source_location a = source_location::current()) {
  source_location b = source_location::current(); // values in b represent this line
}

void g() {
  f(); // f’s first argument corresponds to this line of code

  source_location c = source_location::current();
  f(c); // f’s first argument gets the same values as c, above
}
end example ]
constexpr source_location() noexcept;
Effects:
Constructs an object of class source_location.
Remarks:
The values are implementation-defined.
11.2.2

source_location field access

[reflection.src_loc.fields]
constexpr uint_least32_t line() const noexcept;
Returns:
The presumed line number (C++17 §19.8) represented by this object.
constexpr uint_least32_t column() const noexcept;
Returns:
An implementation-defined value representing some offset from the start of the line represented by this object.
constexpr const char* file_name() const noexcept;
Returns:
The presumed name of the current source file (C++17 §19.8) represented by this object as an NTBS.
constexpr const char* function_name() const noexcept;
Returns:
If this object represents a position in the body of a function, returns an implementation-defined NTBS that should correspond to the function name. Otherwise, returns an empty string.