intro.tex

\rSec0[intro.scope]{Scope}

\pnum
This document describes extensions to the \Cpp
Programming Language~(\ref{intro.refs}) that
permit operations on ranges of data. These extensions include
changes and additions to the existing library facilities as well
as the extension of one core language facility. In particular,
changes and extensions to the Standard Library include:

\begin{itemize}
\item The formulation of the foundational and iterator concept requirements
using the syntax of the Concepts TS~(\ref{intro.refs}).
\item Analogues of the Standard Library algorithms specified in terms of the new
concepts.
\item The loosening of the algorithm constraints to permit the use of
\techterm{sentinels} to denote the end of a range and corresponding changes to algorithm
return types where necessary.
\item The addition of new concepts describing \techterm{range} and \techterm{view}
abstractions; that is, objects with a begin iterator and an end sentinel.
\item New algorithm overloads that take range objects.
\item Support of \techterm{callable objects} (as opposed to \techterm{function objects})
passed as arguments to the algorithms.
\item The addition of optional \techterm{projection} arguments to the algorithms to
permit on-the-fly data transformations.
\item Analogues of the iterator primitives and new primitives in support of the
addition of sentinels to the library.
\item Constrained analogues of the standard iterator adaptors and stream iterators
that satisfy the new iterator concepts.
\item New iterator adaptors (\tcode{counted_iterator} and \tcode{common_iterator}) and
sentinels (\tcode{unreachable}).
\end{itemize}

\pnum
Changes to the core language include:

\begin{itemize}
\item the extension of the range-based \tcode{for} statement to support
the new iterator range requirements~(\ref{range.access}).
\end{itemize}

\pnum
This document does not specify constrained analogues of other parts of the Standard
Library (e.g., the numeric algorithms), nor does it add range support to all the
places that could benefit from it (e.g., the containers).

\pnum
This document does not specify any new range views, actions, or facade or adaptor
utilities; all are left as future work.

\rSec0[intro.refs]{Normative References}

\pnum
The following documents are referred to in the text in such a way that some or
all of their content constitutes requirements of this document. For dated
references, only the edition cited applies. For undated references, the latest
edition of the referenced document (including any amendments) applies.

\begin{itemize}
\item ISO/IEC 14882:2014, \doccite{Programming Languages - \Cpp}
\item ISO/IEC TS 19217:2015, \doccite{Programming Languages - \Cpp Extensions for Concepts}
\end{itemize}

ISO/IEC 14882:2014 is herein called the \defn{C\Rplus\Rplus\xspace Standard} and
ISO/IEC TS 19217:2015 is called the \defn{Concepts TS}.

\rSec0[intro.defs]{Terms and definitions}

For the purposes of this document, the terms and definitions given in
ISO/IEC 14882:2014, ISO/IEC TS 19217:2015, and the following apply.

ISO and IEC maintain terminological databases for use in standardization at
the following addresses:
\begin{itemize}
\item
ISO Online browsing platform: available at http://www.iso.org/obp
\item
IEC Electropedia: available at http://www.electropedia.org/
\end{itemize}

\def\definition{\definitionx{\section}}%

\indexdefn{constant subexpression}%
\definition{constant subexpression}{defns.const.subexpr}
expression whose evaluation as subexpression of a conditional-expression
\tcode{CE}~(\cxxref{expr.cond}) would not prevent \tcode{CE} from being a core
constant expression~(\cxxref{expr.const})

\indexdefn{expression-equivalent}%
\definition{expression-equivalent}{defns.expr.equiv}
relationship that exists between two expressions \tcode{E1} and \tcode{E2} such that
\begin{itemize}
\item
\tcode{E1} and \tcode{E2} have the same effects,

\item
\tcode{noexcept(E1) == noexcept(E2)}, and

\item
\tcode{E1} is a constant subexpression if and only if \tcode{E2} is a constant subexpression
\end{itemize}

\indexdefn{projection}%
\definition{projection}{defns.projection}
\defncontext{function object argument} transformation which an algorithm applies
before inspecting the values of elements

\enterexample
\begin{codeblock}
std::pair<int, const char*> pairs[] = {{2, "foo"}, {1, "bar"}, {0, "baz"}};
ranges::sort(pairs, std::less<>{}, [](auto const& p) { return p.first; });
\end{codeblock}
sorts the pairs in increasing order of their \tcode{first} members:
\begin{codeblock}
{{0, "baz"}, {1, "bar"}, {2, "foo"}}
\end{codeblock}
\exitexample

\rSec0[intro]{General principles}

\rSec1[intro.compliance]{Implementation compliance}

\pnum
Conformance requirements for this specification are the same as those
defined in \cxxref{intro.compliance}.
\enternote
Conformance is defined in terms of the behavior of programs.
\exitnote

\rSec1[intro.namespaces]{Namespaces, headers, and modifications to standard classes}

\pnum
Since the extensions described in this document are experimental and not
part of the \Cpp standard library, they should not be declared directly within namespace
\tcode{std}. Unless otherwise specified, all components described in this document either:

\begin{itemize}
\item modify an existing interface in the \Cpp Standard Library in-place,
\item are declared in namespace \tcode{std::experimental::ranges::v1}.
\end{itemize}

\pnum
The International Standard, ISO/IEC 14882, together with ISO/IEC TS 19217:2015 (the Concepts TS),
provide important context and specification for this document. In places, this document suggests
changes to be made to components in namespace \tcode{std} in-place. In
other places, entire chapters and sections are copied from ISO/IEC 14882 and modified so as to
define similar but different components in namespace \tcode{std::experimental::ranges::v1}.

\pnum
Instructions to modify or add paragraphs are written as explicit instructions.
Modifications made to existing text from the International Standard use
\added{underlining} to represent added text and \removed{strikethrough} to
represent deleted text.

\pnum
This document assumes that the contents of the \tcode{std::experimental::ranges::v1}
namespace will become a new constrained version of the \Cpp Standard Library
that will be delivered alongside the existing unconstrained version.

\pnum
Unless otherwise specified, references to other entities described in this
document are assumed to be qualified with \tcode{std::experimental::ranges::}, and
references to entities described in the International Standard are assumed to be
qualified with \tcode{std::}.

\pnum
New header names are prefixed with \tcode{experimental/ranges/}. Where
the final element of a new header name is the same as an existing standard header
name (e.g., \tcode{<experimental/ranges/algorithm>}), the new header shall include
the standard header as if by

\begin{codeblock}
#include <algorithm>
\end{codeblock}