6 Library introduction [library]

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