6 Library introduction [library]

6.3 Library-wide requirements [requirements]

This subclause specifies requirements that apply to the entire Ranges library. Clauses [concepts.lib] through [numerics] and Annex [depr] specify the requirements of individual entities within the library.

Requirements specified in terms of interactions between threads do not apply to programs having only a single thread of execution.

Within this subclause, [organization] describes the library's contents and organization, [using] describes how well-formed C++ programs gain access to library entities, [constraints] describes constraints on well-formed C++ programs, and [conforming] describes constraints on conforming implementations.

6.3.1 Library contents and organization [organization]

[contents] describes the entities and macros defined in the Ranges library. Library contents [contents]

The Ranges library provides definitions for the entities and macros specified in the Ranges library headers ([headers]).

All library entities are defined within an inline namespace v1 within the namespace std::experimental::ranges or namespaces nested within namespace std::experimental::ranges::v1. It is unspecified whether names declared in a specific namespace are declared directly in that namespace or in an inline namespace inside that namespace.

6.3.2 Headers [headers]

Each element of the Ranges library is declared or defined (as appropriate) in a header.

The Ranges library provides the Ranges library headers, shown in Table [tab:headers].

Table 2 — Ranges TS library headers
<experimental/ranges/algorithm> <experimental/ranges/range>
<experimental/ranges/concepts> <experimental/ranges/tuple>
<experimental/ranges/functional> <experimental/ranges/type_traits>
<experimental/ranges/iterator> <experimental/ranges/utility>

6.3.3 Using the library [using] Overview [using.overview]

This section describes how a C++ program gains access to the facilities of the Ranges library. [using.headers] describes effects during translation phase 4, while [using.linkage] describes effects during phase 8 ( ISO/IEC 14882:2014 §[lex.phases]). Headers [using.headers]

The entities in the Ranges library are defined in headers, the use of which is governed by the same requirements as specified in ISO/IEC 14882:2014 §[using.headers]. Linkage [using.linkage]

Entities in the C++ standard library have external linkage ( ISO/IEC 14882:2014 §[basic.link]). Unless otherwise specified, objects and functions have the default extern "C++" linkage ( ISO/IEC 14882:2014 §[dcl.link]).

6.3.4 Constraints on programs [constraints] Overview [constraints.overview]

This section describes restrictions on C++ programs that use the facilities of the Ranges library. The following subclauses specify constraints on the program's use of Ranges library classes as base classes ([derived.classes]) and other constraints. Derived classes [derived.classes]

Virtual member function signatures defined for a base class in the Ranges library may be overridden in a derived class defined in the program ( ISO/IEC 14882:2014 §[class.virtual]). Other functions [res.on.functions]

In certain cases (operations on types used to instantiate Ranges library template components), the Ranges library depends on components supplied by a C++ program. If these components do not meet their requirements, this document places no requirements on the implementation.

In particular, the effects are undefined if an incomplete type ( ISO/IEC 14882:2014 §[basic.types]) is used as a template argument when instantiating a template component or evaluating a concept, unless specifically allowed for that component. Function arguments [res.on.arguments]

The constraints on arguments passed to C++ standard library function as specified in ISO/IEC 14882:2014 §[res.on.arguments] also apply to arguments passed to functions in the Ranges library. Library object access [res.on.objects]

The constraints on object access by C++ standard library functions as specified in ISO/IEC 14882:2014 §[res.on.objects] also apply to object access by functions in the Ranges library. Requires paragraph [res.on.required]

Violation of the preconditions specified in a function's Requires: paragraph results in undefined behavior unless the function's Throws: paragraph specifies throwing an exception when the precondition is violated. Semantic requirements [res.on.requirements]

If the semantic requirements of a declaration's constraints ([structure.requirements]) are not satisfied at the point of use, the program is ill-formed, no diagnostic required.

6.3.5 Conforming implementations [conforming]

The constraints upon, and latitude of, implementations of the Ranges library follow the same constraints and latitudes for implementations of the C++ standard library as specified in ISO/IEC 14882:2014 §[conforming]. Customization Point Objects [customization.point.object]

A customization point object is a function object ([function.objects]) with a literal class type that interacts with user-defined types while enforcing semantic requirements on that interaction.

The type of a customization point object shall satisfy Semiregular ([concepts.lib.object.semiregular]).

All instances of a specific customization point object type shall be equal ([concepts.lib.general.equality]).

The type of a customization point object T shall satisfy Invocable<const T, Args...> ([concepts.lib.callable.invocable]) when the types of Args... meet the requirements specified in that customization point object's definition. Otherwise, T shall not have a function call operator that participates in overload resolution.

Each customization point object type constrains its return type to satisfy a particular concept.

The library defines several named customization point objects. In every translation unit where such a name is defined, it shall refer to the same instance of the customization point object.

Note: Many of the customization point objects in the library evaluate function call expressions with an unqualified name which results in a call to a user-defined function found by argument dependent name lookup ( ISO/IEC 14882:2014 §[basic.lookup.argdep]). To preclude such an expression resulting in a call to unconstrained functions with the same name in namespace std, customization point objects specify that lookup for these expressions is performed in a context that includes deleted overloads matching the signatures of overloads defined in namespace std. When the deleted overloads are viable, user-defined overloads must be more specialized ( ISO/IEC 14882:2014 §[temp.func.order]) or more constrained (Concepts TS [temp.constr.order]) to be used by a customization point object.  — end note ]