6 Library introduction [library]

6.1 General [library.general]

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

Table 1 — 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 ranges library (Clause [ranges]) describes components for dealing with ranges of elements.

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.

6.2 Method of description (Informative) [description]

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.

6.2.1 Structure of each clause [structure] Elements [structure.elements]

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. Summary [structure.summary]

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.

The contents of the summary and the detailed specifications include: Requirements [structure.requirements]

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. Detailed specifications [structure.specifications]

The detailed specifications of each entity defined in Clauses [concepts.lib][numerics] follow the conventions established by ISO/IEC 14882:2014 §[structure.specifications].

6.2.2 Other conventions [conventions]

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]). Functions within classes [functions.within.classes]

This document follows the same conventions as specified in ISO/IEC 14882:2014 §[functions.within.classes]. Private members [objects.within.classes]

This document follows the same conventions as specified in ISO/IEC 14882:2014 §[objects.within.classes].

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 ]