lib-intro.tex

%!TEX root = std.tex
\rSec0[library]{Library introduction}

\rSec1[library.general]{General}

\pnum
This Clause describes the contents of the
\term{Ranges library},
\indextext{library!Ranges}%
how a well-formed \Cpp program makes use of the library, and
how a conforming implementation may provide the entities in the library.

\pnum
Clause~\ref{requirements}, Clauses~\ref{\firstlibchapter}
through~\ref{\lastlibchapter}, and Annex~\ref{depr} specify the contents of the
library, as well as library requirements and constraints on both well-formed
\Cpp programs and conforming implementations.

\pnum
Detailed specifications for each of the components in the library are in
Clauses~\ref{\firstlibchapter}--\ref{\lastlibchapter}, as shown in
Table~\ref{tab:library.categories}.

\begin{libsumtabbase}{Library categories}{tab:library.categories}{Clause}{Category}
\ref{concepts.lib}      &   &   Concepts library            \\
\ref{utilities}         &   &   General utilities library   \\
\ref{iterators}         &   &   Iterators library           \\
\ref{ranges}            &   &   Ranges library              \\
\ref{algorithms}        &   &   Algorithms library          \\
\ref{numerics}          &   &   Numerics library            \\
\end{libsumtabbase}

\pnum
The concepts library (Clause~\ref{concepts.lib}) describes library components
that \Cpp programs may use to perform compile-time validation of template
parameters and perform function dispatch based on properties of types.

\pnum
The general utilities library (Clause~\ref{utilities}) includes components used
by other library elements and components used as infrastructure in \Cpp
programs, such as function objects.

\pnum
The iterators library (Clause~\ref{iterators}) describes components that \Cpp
programs may use to perform iterations over containers (Clause~\cxxref{containers}),
streams~(\cxxref{iostream.format}), stream buffers~(\cxxref{stream.buffers}),
and ranges~(\ref{ranges}).

\pnum
The ranges library (Clause~\ref{ranges}) describes components for dealing with
ranges of elements.

\pnum
The algorithms library (Clause~\ref{algorithms}) describes components that \Cpp
programs may use to perform algorithmic operations on containers
(Clause~\cxxref{containers}) and other sequences.

\pnum
The numerics library (Clause~\ref{numerics}) provides concepts that are useful
to constrain numeric algorithms.

\rSec1[description]{Method of description (Informative)}

\pnum
This subclause describes the conventions used to specify the Ranges
library. \ref{structure} describes the structure of the normative
Clauses~\ref{\firstlibchapter} through~\ref{\lastlibchapter} and
Annex~\ref{depr}. \ref{conventions} describes other editorial conventions.

\rSec2[structure]{Structure of each clause}

\rSec3[structure.elements]{Elements}

\pnum
Each library clause contains the following elements, as applicable:\footnote{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.}

\begin{itemize}
\item Summary
\item Requirements
\item Detailed specifications
\end{itemize}

\rSec3[structure.summary]{Summary}

\pnum
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.

\pnum
Paragraphs labeled ``Note(s):'' or ``Example(s):'' are informative, other paragraphs
are normative.

\pnum
The contents of the summary and the detailed specifications include:

\begin{itemize}
\item macros
\item values
\item types
\item classes and class templates
\item functions and function templates
\item objects
\item concepts
\end{itemize}

\rSec3[structure.requirements]{Requirements}

\pnum
\indextext{requirements}%
Requirements describe constraints that shall be met by a \Cpp program that extends the Ranges library.
Such extensions are generally one of the following:

\begin{itemize}
\item Template arguments
\item Derived classes
\item Containers, iterators, and algorithms that meet an interface convention
or satisfy a concept
\end{itemize}

\pnum
Interface convention requirements are stated as generally as possible. Instead
of stating ``class X has to define a member function \tcode{operator++()},'' the
interface requires ``for any object \tcode{x} of class \tcode{X}, \tcode{++x} is
defined.'' That is, whether the operator is a member is unspecified.

\pnum
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~\ref{algorithms}) that uses the well-defined expression requirements
is described in terms of the valid expressions for its formal type parameters.

\pnum
Template argument requirements are sometimes referenced by name.
See~\cxxref{type.descriptions}.

\pnum
In some cases the semantic requirements are presented as \Cpp 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.\footnote{Although in some cases the code given is
unambiguously the optimum implementation.}

\pnum
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. \enterexample
The required \tcode{<} operator of the \tcode{StrictTotallyOrdered}
concept~(\ref{concepts.lib.compare.stricttotallyordered}) does not meet the
semantic requirements of that concept when operating on NaNs.\exitexample
This does not affect whether a type satisfies the concept.

\pnum
A declaration may explicitly impose requirements through its associated
constraints (Concepts TS\brk{} [temp.\brk{}constr.\brk{}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.

\rSec3[structure.specifications]{Detailed specifications}

\pnum
The detailed specifications of each entity defined in
Clauses~\ref{\firstlibchapter}--\ref{\lastlibchapter} follow the conventions
established by \cxxref{structure.specifications}.

\rSec2[conventions]{Other conventions}
\indextext{conventions}%

\pnum
This subclause describes several editorial conventions used to describe the contents
of the Ranges library. These conventions are for describing
member functions~(\ref{functions.within.classes}),
and private members~(\ref{objects.within.classes}).

\rSec3[functions.within.classes]{Functions within classes}

\pnum
This document follows the same conventions as specified in \cxxref{functions.within.classes}.

\rSec3[objects.within.classes]{Private members}

\pnum
This document follows the same conventions as specified in \cxxref{objects.within.classes}.

\rSec1[requirements]{Library-wide requirements}

\pnum
This subclause specifies requirements that apply to the entire Ranges library.
Clauses~\ref{\firstlibchapter} through~\ref{\lastlibchapter} and Annex~\ref{depr}
specify the requirements of individual entities within the library.

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

\pnum
Within this subclause, \ref{organization} describes the library's contents and
organization, \ref{using} describes how well-formed \Cpp programs gain access to
library entities, \ref{constraints} describes constraints on well-formed \Cpp
programs, and \ref{conforming} describes constraints on conforming
implementations.

\rSec2[organization]{Library contents and organization}

\pnum
\ref{contents} describes the entities and macros defined in the Ranges library.

\rSec3[contents]{Library contents}

\pnum
The Ranges library provides definitions for the entities and macros specified in
the Ranges library headers~(\ref{headers}).

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

\rSec2[headers]{Headers}

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

\pnum
The Ranges library provides the Ranges library headers, shown in Table~\ref{tab:headers}.

\begin{floattable}{Ranges TS library headers}{tab:headers}
{ll}
\topline
\tcode{<experimental/ranges/algorithm>}  & \tcode{<experimental/ranges/range>}       \\
\tcode{<experimental/ranges/concepts>}   & \tcode{<experimental/ranges/tuple>}       \\
\tcode{<experimental/ranges/functional>} & \tcode{<experimental/ranges/type_traits>} \\
\tcode{<experimental/ranges/iterator>}   & \tcode{<experimental/ranges/utility>}     \\
\tcode{<experimental/ranges/random>} & \\
\bottomline
\end{floattable}

\rSec2[using]{Using the library}

\rSec3[using.overview]{Overview}

\pnum
This section describes how a \Cpp program gains access to the facilities of the
Ranges library. \ref{using.headers} describes effects during translation
phase 4, while~\ref{using.linkage} describes effects during phase
8~(\cxxref{lex.phases}).

\rSec3[using.headers]{Headers}

The entities in the Ranges library are defined in headers, the use of which is
governed by the same requirements as specified in \cxxref{using.headers}.

\rSec3[using.linkage]{Linkage}

\pnum
Entities in the \Cpp standard library have external
linkage~(\cxxref{basic.link}). Unless otherwise specified, objects and functions
have the default \tcode{extern "C++"} linkage~(\cxxref{dcl.link}).

\rSec2[constraints]{Constraints on programs}

\rSec3[constraints.overview]{Overview}

\pnum
This section describes restrictions on \Cpp 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~(\ref{derived.classes})
and other constraints.

\rSec3[derived.classes]{Derived classes}

\pnum
Virtual member function signatures defined
\indextext{function!virtual member}%
for a base class in the Ranges
\indextext{class!base}%
\indextext{library!Ranges}%
library may be overridden in a derived class defined in the
program~(\cxxref{class.virtual}).

\rSec3[res.on.functions]{Other functions}

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

\pnum
In particular, the effects are undefined if an incomplete
type~(\cxxref{basic.types}) is used as a template argument when instantiating a
template component or evaluating a concept, unless specifically allowed for that
component.

\rSec3[res.on.arguments]{Function arguments}

\pnum
\indextext{restriction}%
\indextext{argument}%
The constraints on arguments passed to \Cpp standard library function as
specified in \cxxref{res.on.arguments} also apply to arguments passed to
functions in the Ranges library.

\rSec3[res.on.objects]{Library object access}

\pnum
The constraints on object access by \Cpp standard library functions as specified
in \cxxref{res.on.objects} also apply to object access by functions in the
Ranges library.

\rSec3[res.on.required]{Requires paragraph}

\pnum
\indextext{restriction}%
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.

\rSec3[res.on.requirements]{Semantic requirements}

\pnum
If the semantic requirements of a declaration's
constraints~(\ref{structure.requirements}) are not satisfied at the point of
use, the program is ill-formed, no diagnostic required.

\rSec2[conforming]{Conforming implementations}

\pnum
The constraints upon, and latitude of, implementations of the Ranges library
follow the same constraints and latitudes for implementations of the \Cpp
standard library as specified in \cxxref{conforming}.

\rSec3[customization.point.object]{Customization Point Objects}
\pnum
A \techterm{customization point object} is a function object~(\ref{function.objects}) with a
literal class type that interacts with user-defined types while
enforcing semantic requirements on that interaction.

\pnum
The type of a customization point object shall satisfy
\tcode{Semiregular}~(\ref{concepts.lib.object.semiregular}).

\pnum
All instances of a specific customization point object type shall
be equal~(\ref{concepts.lib.general.equality}).

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

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

\pnum
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.

\pnum
\enternote 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~(\cxxref{basic.lookup.argdep}). To preclude
such an expression resulting in a call to unconstrained functions
with the same name in namespace \tcode{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 \tcode{std}. When the deleted
overloads are viable, user-defined overloads must be more
specialized~(\cxxref{temp.func.order}) or more
constrained~(Concepts TS [temp.constr.order]) to be used by a
customization point object. \exitnote