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.
Detailed specifications for each of the components in the library are in Clauses [concepts.lib]–[numerics], as shown in Table [tab:library.categories].
| Clause | Category | |
| [concepts.lib] | Concepts library | |
| [utilities] | General utilities library | |
| [iterators] | Iterators library | |
| [ranges] | Ranges library | |
| [algorithms] | Algorithms library | |
| [numerics] | Numerics library | |
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.
The numerics library (Clause [numerics]) provides concepts that are useful to constrain numeric algorithms.
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
Summary
Requirements
Detailed specifications
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.
Requirements describe constraints that shall be met by a C++ program that extends the Ranges library. Such extensions are generally one of the following:
Template arguments
Derived classes
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.
The detailed specifications of each entity defined in Clauses [concepts.lib]–[numerics] follow the conventions established by ISO/IEC 14882:2014 §[structure.specifications].
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 document follows the same conventions as specified in ISO/IEC 14882:2014 §[functions.within.classes].
This document follows the same conventions as specified in ISO/IEC 14882:2014 §[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.
[contents] describes the entities and macros defined in the Ranges library.
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].
| <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> |
| <experimental/ranges/random> |
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]).
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].
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]).
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.
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]).
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.
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.
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.
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.
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 ]