This Clause describes the contents of the Ranges library, how a well-formed C++ program makes use of the library, and how a conforming implementation may provide the entities in the library.
Clause [requirements], Clauses [concepts.lib] through [numerics], and Annex [depr] specify the contents of the library, as well as library requirements and constraints on both well-formed C++ programs and conforming implementations.
The concepts library (Clause [concepts.lib]) describes library components that C++ programs may use to perform compile-time validation of template parameters and perform function dispatch based on properties of types.
The general utilities library (Clause [utilities]) includes components used by other library elements and components used as infrastructure in C++ programs, such as function objects.
The iterators library (Clause [iterators]) describes components that C++ programs may use to perform iterations over containers (Clause ISO/IEC 14882:2014 §[containers]), streams ( ISO/IEC 14882:2014 §[iostream.format]), stream buffers ( ISO/IEC 14882:2014 §[stream.buffers]), and ranges ([ranges]).
The algorithms library (Clause [algorithms]) describes components that C++ programs may use to perform algorithmic operations on containers (Clause ISO/IEC 14882:2014 §[containers]) and other sequences.
This subclause describes the conventions used to specify the Ranges library. [structure] describes the structure of the normative Clauses [concepts.lib] through [numerics] and Annex [depr]. [conventions] describes other editorial conventions.
Each library clause contains the following elements, as applicable:1
To save space, items that do not apply to a Clause are omitted. For example, if a Clause does not specify any requirements, there will be no “Requirements” subclause.
The Summary provides a synopsis of the category, and introduces the first-level subclauses. Each subclause also provides a summary, listing the headers specified in the subclause and the library entities provided in each header.
Paragraphs labeled “Note(s):” or “Example(s):” are informative, other paragraphs are normative.
Containers, iterators, and algorithms that meet an interface convention or satisfy a concept
Interface convention requirements are stated as generally as possible. Instead of stating “class X has to define a member function operator++(),” the interface requires “for any object x of class X, ++x is defined.” That is, whether the operator is a member is unspecified.
Requirements are stated in terms of concepts (Concepts TS [dcl.spec.concept]). Concepts are stated in terms of well-defined expressions that define valid terms of the types that satisfy the concept. For every set of well-defined expression requirements there is a named concept that specifies an initial set of the valid expressions and their semantics. Any generic algorithm (Clause [algorithms]) that uses the well-defined expression requirements is described in terms of the valid expressions for its formal type parameters.
Template argument requirements are sometimes referenced by name. See ISO/IEC 14882:2014 §[type.descriptions].
In some cases the semantic requirements are presented as C++ code. Such code is intended as a specification of equivalence of a construct to another construct, not necessarily as the way the construct must be implemented.2
Required operations of any concept defined in this document need not be total functions; that is, some arguments to a required operation may result in the required semantics failing to be satisfied. [ Example: The required < operator of the StrictTotallyOrdered concept ([concepts.lib.compare.stricttotallyordered]) does not meet the semantic requirements of that concept when operating on NaNs. — end example ] This does not affect whether a type satisfies the concept.
A declaration may explicitly impose requirements through its associated constraints (Concepts TS [temp.constr.decl]). When the associated constraints refer to a concept (Concepts TS [dcl.spec.concept]), additional semantic requirements are imposed on the use of the declaration.
Although in some cases the code given is unambiguously the optimum implementation.
This subclause describes several editorial conventions used to describe the contents of the Ranges library. These conventions are for describing member functions ([functions.within.classes]), and private members ([objects.within.classes]).
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.
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.
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].
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.
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.
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].
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 ]