numerics.tex

\rSec0[numerics]{Numerics library}

\rSec1[numerics.general]{General}

\pnum
This Clause describes components that \Cpp programs may use to perform
seminumerical operations.

\pnum
The following subclauses describe components for
complex number types, random number generation,
numeric (%
\textit{n}-at-a-time)
arrays, generalized numeric algorithms,
and facilities included from the ISO C library,
as summarized in Table~\ref{tab:numerics.lib.summary}.

\begin{libsumtab}{Numerics library summary}{tab:numerics.lib.summary}
\ref{numeric.requirements}  & Requirements &           \\ \rowsep
\ref{cfenv}           & Floating-Point Environment & \tcode{<cfenv>}  \\ \rowsep
\ref{complex.numbers} & Complex Numbers & \tcode{<complex>} \\ \rowsep
\ref{rand}  & Random number generation & \tcode{<random>} \\ \rowsep
\ref{numarray}  & Numeric arrays     & \tcode{<valarray>}  \\ \rowsep
\ref{numeric.ops} & Generalized numeric operations  & \tcode{<numeric>} \\ \rowsep
\ref{c.math}  & C library            & \tcode{<cmath>}   \\
              &                        & \tcode{<ctgmath>} \\
              &                        & \tcode{<tgmath.h>}\\
              &                        & \tcode{<cstdlib>} \\
\end{libsumtab}

\rSec1[numeric.requirements]{Numeric type requirements}
\indextext{requirements!numeric type}

\pnum
The
\tcode{complex}
and
\tcode{valarray}
components are parameterized by the type of information they contain and manipulate.
A \Cpp program shall instantiate these components only with a type
\tcode{T}
that satisfies the
following requirements:\footnote{In other words, value types.
These include arithmetic types,
pointers, the library class
\tcode{complex},
and instantiations of
\tcode{valarray}
for value types.}

\begin{itemize}
\item \tcode{T} is not an abstract class (it has no pure virtual member functions);
\item \tcode{T} is not a reference type;
\item \tcode{T} is not cv-qualified;
\item If \tcode{T} is a class, it has a public default constructor;
\item If \tcode{T} is a class, it has a public copy constructor with the signature \tcode{T::T(const T\&)}
\item If \tcode{T} is a class, it has a public destructor;
\item If \tcode{T} is a class, it has a public assignment operator whose signature is either
\tcode{T\& T::operator=(const T\&)}
or
\tcode{T\& T::operator=(T)}
\item If \tcode{T} is a class, its assignment operator, copy and default constructors,
and destructor shall correspond to each other in the following sense:
Initialization of raw storage using the default constructor, followed by
assignment, is semantically equivalent to initialization of raw
storage using the copy constructor.
Destruction of an object, followed by
initialization of its raw storage using the copy constructor,
is semantically equivalent to assignment to the original object.

\enternote
This rule states that there shall not be any subtle differences in the semantics
of initialization versus assignment.
This gives an implementation
considerable flexibility in how arrays are initialized.

\enterexample
An implementation is allowed to initialize a
\tcode{valarray}
by allocating storage using the
\tcode{new}
operator (which
implies a call to the default constructor for each element) and then
assigning each element its value.
Or the implementation can allocate raw
storage and use the copy constructor to initialize each element.
\exitexample

If the distinction between initialization and assignment is important
for a class, or if it fails to satisfy any of
the other conditions listed above, the programmer should use
\tcode{vector}~(\ref{vector}) instead of
\tcode{valarray}
for that class;
\exitnote
\item If \tcode{T} is a class, it does not overload unary
\tcode{operator\&}.
\end{itemize}

\pnum
If any operation on \tcode{T}
throws an exception the effects are undefined.

\pnum
In addition, many member and related functions of
\tcode{valarray<T>}
can be successfully instantiated
and will exhibit well-defined behavior if and only if
\tcode{T} satisfies additional requirements specified for each such member
or related function.

\pnum
\enterexample
It is valid to instantiate
\tcode{valarray<complex>},
but
\tcode{operator>()}
will not be successfully instantiated for
\tcode{valarray<complex>}
operands, since
\tcode{complex}
does not have any ordering operators.
\exitexample

\rSec1[cfenv]{The floating-point environment}
\rSec2[cfenv.syn]{Header \tcode{<cfenv>} synopsis}
\indexlibrary{\idxhdr{cfenv}}%
\begin{codeblock}
namespace std {
  // types
  typedef @\textit{object type}@  fenv_t;
  typedef @\textit{integer type}@ fexcept_t;

  // functions
  int feclearexcept(int except);
  int fegetexceptflag(fexcept_t *pflag, int except);
  int feraiseexcept(int except);
  int fesetexceptflag(const fexcept_t *pflag, int except);
  int fetestexcept(int except);

  int fegetround(void);
  int fesetround(int mode);

  int fegetenv(fenv_t *penv);
  int feholdexcept(fenv_t *penv);
  int fesetenv(const fenv_t *penv);
  int feupdateenv(const fenv_t *penv);
}
\end{codeblock}

\pnum
\indexlibrary{\idxcode{fenv_t}}%
\indexlibrary{\idxcode{fexcept_t}}%
\indexlibrary{\idxcode{feclearexcept}}%
\indexlibrary{\idxcode{fegetexceptflag}}%
\indexlibrary{\idxcode{feraiseexcept}}%
\indexlibrary{\idxcode{fesetexceptflag}}%
\indexlibrary{\idxcode{fetestexcept}}%
\indexlibrary{\idxcode{fegetround}}%
\indexlibrary{\idxcode{fesetround}}%
\indexlibrary{\idxcode{fegetenv}}%
\indexlibrary{\idxcode{feholdexcept}}%
\indexlibrary{\idxcode{fesetenv}}%
\indexlibrary{\idxcode{feupdateenv}}%
\indexlibrary{\idxcode{FE_ALL_EXCEPT}}%
\indexlibrary{\idxcode{FE_DIVBYZERO}}%
\indexlibrary{\idxcode{FE_INEXACT}}%
\indexlibrary{\idxcode{FE_INVALID}}%
\indexlibrary{\idxcode{FE_OVERFLOW}}%
\indexlibrary{\idxcode{FE_UNDERFLOW}}%
\indexlibrary{\idxcode{FE_DOWNWARD}}%
\indexlibrary{\idxcode{FE_TONEAREST}}%
\indexlibrary{\idxcode{FE_TOWARDZERO}}%
\indexlibrary{\idxcode{FE_UPWARD}}%
\indexlibrary{\idxcode{FE_DFL_ENV}}%
The header also defines the macros:
\begin{codeblock}
  FE_ALL_EXCEPT
  FE_DIVBYZERO
  FE_INEXACT
  FE_INVALID
  FE_OVERFLOW
  FE_UNDERFLOW

  FE_DOWNWARD
  FE_TONEAREST
  FE_TOWARDZERO
  FE_UPWARD

  FE_DFL_ENV
\end{codeblock}

\pnum
The header defines all functions, types, and macros the same as
Clause 7.6 of the C standard.

\pnum
The floating-point environment has thread storage
duration~(\ref{basic.stc.thread}). The initial state for a thread's floating-point
environment is the state of the floating-point environment of the thread that constructs
the corresponding \tcode{std::thread} object~(\ref{thread.thread.class}) at the time it
constructed the object. \enternote That is, the child thread gets the floating-point
state of the parent thread at the time of the child's creation. \exitnote

\pnum
A separate floating-point environment shall be maintained for each thread. Each function
accesses the environment corresponding to its calling thread.

\rSec1[complex.numbers]{Complex numbers}

\pnum
The header
\indexlibrary{\idxhdr{complex}}%
\tcode{<complex>}
defines a
class template,
and numerous functions for representing and manipulating complex numbers.

\pnum
The effect of instantiating the template
\tcode{complex}
for any type other than \tcode{float}, \tcode{double}, or \tcode{long double} is unspecified.
The specializations
\tcode{complex<float>},
\tcode{complex<double>}, and
\tcode{complex<long double>} are literal types~(\ref{basic.types}).

\pnum
If the result of a function is not mathematically defined or not in
the range of representable values for its type, the behavior is
undefined.

\pnum
If \tcode{z} is an lvalue expression of type \emph{cv} \tcode{std::complex<T>} then:

\begin{itemize}
\item the expression \tcode{reinterpret_cast<cv T(\&)[2]>(z)} shall be well-formed,
\item \tcode{reinterpret_cast<cv T(\&)[2]>(z)[0]} shall designate the real part of \tcode{z}, and
\item \tcode{reinterpret_cast<cv T(\&)[2]>(z)[1]} shall designate the imaginary part of \tcode{z}.
\end{itemize}

Moreover, if \tcode{a} is an expression of type \tcode{cv std::complex<T>*} and the expression \tcode{a[i]} is well-defined for an integer expression \tcode{i}, then:

\begin{itemize}
\item \tcode{reinterpret_cast<cv T*>(a)[2*i]} shall designate the real part of \tcode{a[i]}, and
\item \tcode{reinterpret_cast<cv T*>(a)[2*i + 1]} shall designate the imaginary part of \tcode{a[i]}.
\end{itemize}

\rSec2[complex.syn]{Header \tcode{<complex>} synopsis}

\indexlibrary{\idxhdr{complex}}%
\begin{codeblock}
namespace std {
  template<class T> class complex;
  template<> class complex<float>;
  template<> class complex<double>;
  template<> class complex<long double>;

  // \ref{complex.ops}, operators:
  template<class T>
    complex<T> operator+(const complex<T>&, const complex<T>&);
  template<class T> complex<T> operator+(const complex<T>&, const T&);
  template<class T> complex<T> operator+(const T&, const complex<T>&);

  template<class T> complex<T> operator-(
    const complex<T>&, const complex<T>&);
  template<class T> complex<T> operator-(const complex<T>&, const T&);
  template<class T> complex<T> operator-(const T&, const complex<T>&);

  template<class T> complex<T> operator*(
    const complex<T>&, const complex<T>&);
  template<class T> complex<T> operator*(const complex<T>&, const T&);
  template<class T> complex<T> operator*(const T&, const complex<T>&);

  template<class T> complex<T> operator/(
    const complex<T>&, const complex<T>&);
  template<class T> complex<T> operator/(const complex<T>&, const T&);
  template<class T> complex<T> operator/(const T&, const complex<T>&);

  template<class T> complex<T> operator+(const complex<T>&);
  template<class T> complex<T> operator-(const complex<T>&);

  template<class T> constexpr bool operator==(
    const complex<T>&, const complex<T>&);
  template<class T> constexpr bool operator==(const complex<T>&, const T&);
  template<class T> constexpr bool operator==(const T&, const complex<T>&);

  template<class T> constexpr bool operator!=(const complex<T>&, const complex<T>&);
  template<class T> constexpr bool operator!=(const complex<T>&, const T&);
  template<class T> constexpr bool operator!=(const T&, const complex<T>&);

  template<class T, class charT, class traits>
  basic_istream<charT, traits>&
  operator>>(basic_istream<charT, traits>&, complex<T>&);

  template<class T, class charT, class traits>
  basic_ostream<charT, traits>&
  operator<<(basic_ostream<charT, traits>&, const complex<T>&);

  // \ref{complex.value.ops}, values:
  template<class T> constexpr T real(const complex<T>&);
  template<class T> constexpr T imag(const complex<T>&);

  template<class T> T abs(const complex<T>&);
  template<class T> T arg(const complex<T>&);
  template<class T> T norm(const complex<T>&);

  template<class T> complex<T> conj(const complex<T>&);
  template <class T> complex<T> proj(const complex<T>&);
  template<class T> complex<T> polar(const T&, const T& = 0);

  // \ref{complex.transcendentals}, transcendentals:
  template<class T> complex<T> acos(const complex<T>&);
  template<class T> complex<T> asin(const complex<T>&);
  template<class T> complex<T> atan(const complex<T>&);

  template<class T> complex<T> acosh(const complex<T>&);
  template<class T> complex<T> asinh(const complex<T>&);
  template<class T> complex<T> atanh(const complex<T>&);

  template<class T> complex<T> cos  (const complex<T>&);
  template<class T> complex<T> cosh (const complex<T>&);
  template<class T> complex<T> exp  (const complex<T>&);
  template<class T> complex<T> log  (const complex<T>&);
  template<class T> complex<T> log10(const complex<T>&);

  template<class T> complex<T> pow(const complex<T>&, const T&);
  template<class T> complex<T> pow(const complex<T>&, const complex<T>&);
  template<class T> complex<T> pow(const T&, const complex<T>&);

  template<class T> complex<T> sin  (const complex<T>&);
  template<class T> complex<T> sinh (const complex<T>&);
  template<class T> complex<T> sqrt (const complex<T>&);
  template<class T> complex<T> tan  (const complex<T>&);
  template<class T> complex<T> tanh (const complex<T>&);
}
\end{codeblock}

\rSec2[complex]{Class template \tcode{complex}}

\indexlibrary{\idxcode{complex}}%
\begin{codeblock}
namespace std {
  template<class T>
  class complex {
  public:
    typedef T value_type;

    constexpr complex(const T& re = T(), const T& im = T());
    constexpr complex(const complex&);
    template<class X> constexpr complex(const complex<X>&);

    constexpr T real() const;
    void real(T);
    constexpr T imag() const;
    void imag(T);

    complex<T>& operator= (const T&);
    complex<T>& operator+=(const T&);
    complex<T>& operator-=(const T&);
    complex<T>& operator*=(const T&);
    complex<T>& operator/=(const T&);

    complex& operator=(const complex&);
    template<class X> complex<T>& operator= (const complex<X>&);
    template<class X> complex<T>& operator+=(const complex<X>&);
    template<class X> complex<T>& operator-=(const complex<X>&);
    template<class X> complex<T>& operator*=(const complex<X>&);
    template<class X> complex<T>& operator/=(const complex<X>&);
  };
}
\end{codeblock}

\pnum
The class
\tcode{complex}
describes an object that can
store the Cartesian components,
\tcode{real()}
and
\tcode{imag()},
of a complex
number.

\rSec2[complex.special]{\tcode{complex} specializations}

\begin{codeblock}
namespace std {
  template<> class complex<float> {
  public:
    typedef float value_type;

    constexpr complex(float re = 0.0f, float im = 0.0f);
    explicit constexpr complex(const complex<double>&);
    explicit constexpr complex(const complex<long double>&);

    constexpr float real() const;
    void real(float);
    constexpr float imag() const;
    void imag(float);

    complex<float>& operator= (float);
    complex<float>& operator+=(float);
    complex<float>& operator-=(float);
    complex<float>& operator*=(float);
    complex<float>& operator/=(float);

    complex<float>& operator=(const complex<float>&);
    template<class X> complex<float>& operator= (const complex<X>&);
    template<class X> complex<float>& operator+=(const complex<X>&);
    template<class X> complex<float>& operator-=(const complex<X>&);
    template<class X> complex<float>& operator*=(const complex<X>&);
    template<class X> complex<float>& operator/=(const complex<X>&);
  };

  template<> class complex<double> {
  public:
    typedef double value_type;

    constexpr complex(double re = 0.0, double im = 0.0);
    constexpr complex(const complex<float>&);
    explicit constexpr complex(const complex<long double>&);

    constexpr double real() const;
    void real(double);
    constexpr double imag() const;
    void imag(double);

    complex<double>& operator= (double);
    complex<double>& operator+=(double);
    complex<double>& operator-=(double);
    complex<double>& operator*=(double);
    complex<double>& operator/=(double);

    complex<double>& operator=(const complex<double>&);
    template<class X> complex<double>& operator= (const complex<X>&);
    template<class X> complex<double>& operator+=(const complex<X>&);
    template<class X> complex<double>& operator-=(const complex<X>&);
    template<class X> complex<double>& operator*=(const complex<X>&);
    template<class X> complex<double>& operator/=(const complex<X>&);
  };

  template<> class complex<long double> {
  public:
    typedef long double value_type;

    constexpr complex(long double re = 0.0L, long double im = 0.0L);
    constexpr complex(const complex<float>&);
    constexpr complex(const complex<double>&);

    constexpr long double real() const;
    void real(long double);
    constexpr long double imag() const;
    void imag(long double);

    complex<long double>& operator=(const complex<long double>&);
    complex<long double>& operator= (long double);
    complex<long double>& operator+=(long double);
    complex<long double>& operator-=(long double);
    complex<long double>& operator*=(long double);
    complex<long double>& operator/=(long double);

    template<class X> complex<long double>& operator= (const complex<X>&);
    template<class X> complex<long double>& operator+=(const complex<X>&);
    template<class X> complex<long double>& operator-=(const complex<X>&);
    template<class X> complex<long double>& operator*=(const complex<X>&);
    template<class X> complex<long double>& operator/=(const complex<X>&);
  };
}
\end{codeblock}

\rSec2[complex.members]{\tcode{complex} member functions}

\indexlibrary{\idxcode{complex}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> constexpr complex(const T& re = T(), const T& im = T());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{complex}.

\pnum
\postcondition
\tcode{real() == re \&\& imag() == im}.
\end{itemdescr}

\indexlibrary{\idxcode{real}!\idxcode{complex}}%
\indexlibrary{\idxcode{complex}!\idxcode{real}}%
\begin{itemdecl}
constexpr T real() const;
\end{itemdecl}

\begin{itemdescr}
\returns The value of the real component.
\end{itemdescr}

\indexlibrary{\idxcode{real}!\idxcode{complex}}%
\indexlibrary{\idxcode{complex}!\idxcode{real}}%
\begin{itemdecl}
void real(T val);
\end{itemdecl}

\begin{itemdescr}
\effects Assigns \tcode{val} to the real component.
\end{itemdescr}

\indexlibrary{\idxcode{imag}!\idxcode{complex}}%
\indexlibrary{\idxcode{complex}!\idxcode{imag}}%
\begin{itemdecl}
constexpr T imag() const;
\end{itemdecl}

\begin{itemdescr}
\returns The value of the imaginary component.
\end{itemdescr}

\indexlibrary{\idxcode{imag}!\idxcode{complex}}%
\indexlibrary{\idxcode{complex}!\idxcode{imag}}%
\begin{itemdecl}
void imag(T val);
\end{itemdecl}

\begin{itemdescr}
\effects Assigns \tcode{val} to the imaginary component.
\end{itemdescr}

\rSec2[complex.member.ops]{\tcode{complex} member operators}

\indexlibrary{\idxcode{operator+=}!\idxcode{complex}}%
\begin{itemdecl}
complex<T>& operator+=(const T& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Adds the scalar value \tcode{rhs} to the real part of the complex value
\tcode{*this}
and stores the result in the real part of
\tcode{*this},
leaving the imaginary part unchanged.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{operator-=}!\idxcode{complex}}%
\begin{itemdecl}
complex<T>& operator-=(const T& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Subtracts the scalar value \tcode{rhs} from the real part of the complex value
\tcode{*this}
and stores the result in the real part of
\tcode{*this},
leaving the imaginary part unchanged.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{operator*=}!\idxcode{complex}}%
\begin{itemdecl}
complex<T>& operator*=(const T& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Multiplies the scalar value \tcode{rhs} by the complex value
\tcode{*this}
and stores the result in
\tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{operator/=}!\idxcode{complex}}%
\begin{itemdecl}
complex<T>& operator/=(const T& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Divides the scalar value \tcode{rhs} into the complex value
\tcode{*this}
and stores the result in
\tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{operator+=}!\idxcode{complex}}%
\begin{itemdecl}
complex<T>& operator+=(const complex<T>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Adds the complex value \tcode{rhs} to the complex value
\tcode{*this}
and stores the sum in
\tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{operator-=}!\idxcode{complex}}%
\begin{itemdecl}
complex<T>& operator-=(const complex<T>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Subtracts the complex value \tcode{rhs} from the complex value
\tcode{*this}
and stores the difference in
\tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{operator*=}!\idxcode{complex}}%
\begin{itemdecl}
complex<T>& operator*=(const complex<T>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Multiplies the complex value \tcode{rhs} by the complex value
\tcode{*this}
and stores the product in
\tcode{*this}.

\returns
\tcode{*this}.
\end{itemdescr}

\indexlibrary{\idxcode{operator/=}!\idxcode{complex}}%
\begin{itemdecl}
complex<T>& operator/=(const complex<T>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Divides the complex value \tcode{rhs} into the complex value
\tcode{*this}
and stores the quotient in
\tcode{*this}.

\pnum
\returns
\tcode{*this}.
\end{itemdescr}

\rSec2[complex.ops]{\tcode{complex} non-member operations}

\indexlibrary{\idxcode{operator+}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> operator+(const complex<T>& lhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
unary operator.

\pnum
\returns
\tcode{complex<T>(lhs)}.
\end{itemdescr}

\begin{codeblock}
template<class T>
  complex<T> operator+(const complex<T>& lhs, const complex<T>& rhs);
template<class T> complex<T> operator+(const complex<T>& lhs, const T& rhs);
template<class T> complex<T> operator+(const T& lhs, const complex<T>& rhs);
\end{codeblock}

\begin{itemdescr}
\pnum
\returns
\tcode{complex<T>(lhs) += rhs}.
\end{itemdescr}

\indexlibrary{\idxcode{operator-}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> operator-(const complex<T>& lhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
unary operator.

\pnum
\returns
\tcode{complex<T>(-lhs.real(),-lhs.imag())}.
\end{itemdescr}

\indexlibrary{\idxcode{operator-}!\idxcode{complex}}%
\indexlibrary{\idxcode{complex}!\idxcode{operator-}}%
\begin{itemdecl}
template<class T>
  complex<T> operator-(const complex<T>& lhs, const complex<T>& rhs);
template<class T> complex<T> operator-(const complex<T>& lhs, const T& rhs);
template<class T> complex<T> operator-(const T& lhs, const complex<T>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{complex<T>(lhs) -= rhs}.
\end{itemdescr}

\indexlibrary{\idxcode{operator*}!\idxcode{complex}}%
\begin{itemdecl}
template<class T>
  complex<T> operator*(const complex<T>& lhs, const complex<T>& rhs);
template<class T> complex<T> operator*(const complex<T>& lhs, const T& rhs);
template<class T> complex<T> operator*(const T& lhs, const complex<T>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{complex<T>(lhs) *= rhs}.
\end{itemdescr}

\indexlibrary{\idxcode{operator/}!\idxcode{complex}}%
\indexlibrary{\idxcode{complex}!\idxcode{operator/}}%
\begin{itemdecl}
template<class T>
  complex<T> operator/(const complex<T>& lhs, const complex<T>& rhs);
template<class T> complex<T> operator/(const complex<T>& lhs, const T& rhs);
template<class T> complex<T> operator/(const T& lhs, const complex<T>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{complex<T>(lhs) /= rhs}.
\end{itemdescr}

\indexlibrary{\idxcode{operator==}!\idxcode{complex}}%
\begin{itemdecl}
template<class T>
  bool constexpr operator==(const complex<T>& lhs, const complex<T>& rhs);
template<class T> constexpr bool operator==(const complex<T>& lhs, const T& rhs);
template<class T> constexpr bool operator==(const T& lhs, const complex<T>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{lhs.real() == rhs.real() \&\& lhs.imag() == rhs.imag()}.

\pnum
\notes
The imaginary part is assumed to be
\tcode{T()},
or 0.0, for the
\tcode{T}
arguments.
\end{itemdescr}

\indexlibrary{\idxcode{operator"!=}!\idxcode{complex}}%
\begin{itemdecl}
template<class T>
  constexpr bool operator!=(const complex<T>& lhs, const complex<T>& rhs);
template<class T> constexpr bool operator!=(const complex<T>& lhs, const T& rhs);
template<class T> constexpr bool operator!=(const T& lhs, const complex<T>& rhs);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{rhs.real() != lhs.real() || rhs.imag() != lhs.imag()}.
\end{itemdescr}

\indexlibrary{operator>>@\tcode{operator\shr}!\idxcode{complex}}%
\begin{itemdecl}
template<class T, class charT, class traits>
basic_istream<charT, traits>&
operator>>(basic_istream<charT, traits>& is, complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Extracts a complex number \tcode{x} of the form:
\tcode{u},
\tcode{(u)},
or
\tcode{(u,v)},
where
\tcode{u}
is the real part and
\tcode{v}
is the imaginary part~(\ref{istream.formatted}).

\pnum
\requires
The input values shall be convertible to
\tcode{T}.

If bad input is encountered, calls
\tcode{is.setstate(ios_base::failbit)}
(which may throw
\tcode{ios::failure} (\ref{iostate.flags})).

\pnum
\returns
\tcode{is}.

\pnum
\notes
This extraction is performed as a series of simpler
extractions.
Therefore, the skipping of whitespace is specified to be
the same for each of the simpler extractions.
\end{itemdescr}

\indexlibrary{operator<<@\tcode{operator\shl}!\idxcode{complex}}%
\begin{itemdecl}
template<class T, class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& o, const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
inserts the complex number \tcode{x}
onto the stream \tcode{o} as if it were implemented as follows:

\begin{codeblock}
template<class T, class charT, class traits>
basic_ostream<charT, traits>&
operator<<(basic_ostream<charT, traits>& o, const complex<T>& x) {
  basic_ostringstream<charT, traits> s;
  s.flags(o.flags());
  s.imbue(o.getloc());
  s.precision(o.precision());
  s << '(' << x.real() << "," << x.imag() << ')';
  return o << s.str();
}
\end{codeblock}

\pnum
\realnote In a locale in which comma is used as a decimal point character, the
use of comma as a field separator can be ambiguous. Inserting
\tcode{std::showpoint} into the output stream forces all outputs to
show an explicit decimal point character; as a result, all inserted sequences of
complex numbers can be extracted unambiguously.

\end{itemdescr}

\rSec2[complex.value.ops]{\tcode{complex} value operations}

\indexlibrary{\idxcode{real}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> constexpr T real(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.real()}.
\end{itemdescr}

\indexlibrary{\idxcode{imag}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> constexpr T imag(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{x.imag()}.
\end{itemdescr}

\indexlibrary{\idxcode{abs}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> T abs(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The magnitude of \tcode{x}.
\end{itemdescr}

\indexlibrary{\idxcode{arg}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> T arg(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The phase angle of \tcode{x}, or \tcode{atan2(imag(x), real(x))}.
\end{itemdescr}

\indexlibrary{\idxcode{norm}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> T norm(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The squared magnitude of \tcode{x}.
\end{itemdescr}

\indexlibrary{\idxcode{conj}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> conj(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The complex conjugate of \tcode{x}.
\end{itemdescr}

\indexlibrary{\idxcode{proj}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> proj(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns The projection of \tcode{x} onto the Riemann sphere.

\pnum
\remarks
Behaves the same as the C function \tcode{cproj}, defined in 7.3.9.4.
\end{itemdescr}

\indexlibrary{\idxcode{polar}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> polar(const T& rho, const T& theta = 0);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The
\tcode{complex}
value corresponding
to a complex number whose magnitude is \tcode{rho} and whose phase angle
is \tcode{theta}.
\end{itemdescr}

\rSec2[complex.transcendentals]{\tcode{complex} transcendentals}

\indexlibrary{\idxcode{acos}!\idxcode{complex}}%
\indexlibrary{\idxcode{cacos}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> acos(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns The complex arc cosine of \tcode{x}.

\pnum
\remarks
Behaves the same as C function \tcode{cacos},
defined in 7.3.5.1.
\end{itemdescr}

\indexlibrary{\idxcode{asin}!\idxcode{complex}}%
\indexlibrary{\idxcode{casin}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> asin(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns The complex arc sine of \tcode{x}.

\pnum
\remarks
Behaves the same as C function \tcode{casin},
defined in 7.3.5.2.
\end{itemdescr}

\indexlibrary{\idxcode{atan}!\idxcode{complex}}%
\indexlibrary{\idxcode{catan}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> atan(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns The complex arc tangent of \tcode{x}.

\pnum
\remarks
Behaves the same as C function \tcode{catan},
defined in 7.3.5.3.
\end{itemdescr}

\indexlibrary{\idxcode{acosh}!\idxcode{complex}}%
\indexlibrary{\idxcode{cacosh}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> acosh(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns The complex arc hyperbolic cosine of \tcode{x}.

\pnum
\remarks
Behaves the same as C function \tcode{cacosh},
defined in 7.3.6.1.
\end{itemdescr}

\indexlibrary{\idxcode{asinh}!\idxcode{complex}}%
\indexlibrary{\idxcode{casinh}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> asinh(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns The complex arc hyperbolic sine of \tcode{x}.

\pnum
\remarks
Behaves the same as C function \tcode{casinh},
defined in 7.3.6.2.
\end{itemdescr}

\indexlibrary{\idxcode{atanh}!\idxcode{complex}}%
\indexlibrary{\idxcode{catanh}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> atanh(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns The complex arc hyperbolic tangent of \tcode{x}.

\pnum
\remarks
Behaves the same as C function \tcode{catanh},
defined in 7.3.6.3.
\end{itemdescr}

\indexlibrary{\idxcode{cos}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> cos(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The complex cosine of \tcode{x}.
\end{itemdescr}

\indexlibrary{\idxcode{cosh}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> cosh(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The complex hyperbolic cosine of \tcode{x}.
\end{itemdescr}

\indexlibrary{\idxcode{exp}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> exp(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The complex base e exponential of \tcode{x}.
\end{itemdescr}

\indexlibrary{\idxcode{log}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> log(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
the branch cuts are along the negative real axis.

\pnum
\returns
The complex natural (base e) logarithm of \tcode{x},
in the range of a strip mathematically unbounded along the
real axis and in the interval \crange{-i times pi}{i times pi}
along the imaginary axis.
When \tcode{x} is a negative real
number,
\tcode{imag(log(x))}
is pi.
\end{itemdescr}

\indexlibrary{\idxcode{log10}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> log10(const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
the branch cuts are along the negative real axis.

\pnum
\returns
The complex common (base 10) logarithm of \tcode{x}, defined as
\tcode{log(x)/log(10)}.
\end{itemdescr}

\indexlibrary{\idxcode{pow}!\idxcode{complex}}%
\begin{itemdecl}
template<class T>
  complex<T> pow(const complex<T>& x, const complex<T>& y);
template<class T> complex<T> pow  (const complex<T>& x, const T& y);
template<class T> complex<T> pow  (const T& x, const complex<T>& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
the branch cuts are along the negative real axis.

\pnum
\returns
The complex power of base \tcode{x} raised to the \tcode{y}-th power,
defined as
\tcode{exp(y*log(x))}.
The value returned for
\tcode{pow(0,0)}
is implementation-defined.
\end{itemdescr}

\indexlibrary{\idxcode{sin}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> sin  (const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The complex sine of \tcode{x}.
\end{itemdescr}

\indexlibrary{\idxcode{sinh}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> sinh (const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The complex hyperbolic sine of \tcode{x}.
\end{itemdescr}

\indexlibrary{\idxcode{sqrt}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> sqrt (const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\notes
the branch cuts are along the negative real axis.

\pnum
\returns
The complex square root of \tcode{x}, in the range of the right
half-plane.
If the argument is a negative real number, the
value returned lies on the positive imaginary axis.
\end{itemdescr}

\indexlibrary{\idxcode{tan}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> tan  (const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The complex tangent of \tcode{x}.
\end{itemdescr}

\indexlibrary{\idxcode{tanh}!\idxcode{complex}}%
\begin{itemdecl}
template<class T> complex<T> tanh (const complex<T>& x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
The complex hyperbolic tangent of \tcode{x}.
\end{itemdescr}

\rSec2[cmplx.over]{Additional overloads}

\pnum
\indexlibrary{\idxcode{arg}}%
\indexlibrary{\idxcode{conj}}%
\indexlibrary{\idxcode{imag}}%
\indexlibrary{\idxcode{norm}}%
\indexlibrary{\idxcode{real}}%
The following function templates shall have additional overloads:
\begin{codeblock}
arg                   norm 
conj                  proj
imag                  real 
\end{codeblock}

\pnum
\indextext{overloads!floating point}%
The additional overloads shall be sufficient to ensure:

\begin{enumerate}
        \item If the argument has type \tcode{long double}, then it is effectively 
              cast to \tcode{complex<long double>}.
        \item Otherwise, if the argument has type \tcode{double} or an integer type,
              then it is effectively cast to \tcode{complex<\brk{}double>}.
        \item Otherwise, if the argument has type \tcode{float}, then it is 
              effectively cast to \tcode{complex<float>}.
\end{enumerate}

\pnum
\indexlibrary{\idxcode{pow}}%
Function template \tcode{pow} shall have additional overloads sufficient to
ensure, for a call with at least one argument of type \tcode{complex<T>}:

\begin{enumerate}

  \item If either argument has type \tcode{complex<long double>} or type \tcode{long
        double}, then both arguments are effectively cast to
        \tcode{complex<long double>}.
  \item Otherwise, if either argument has type \tcode{complex<double>}, \tcode{double},
        or an integer type, then both arguments are effectively cast to
        \tcode{complex<double>}.
  \item Otherwise, if either argument has type \tcode{complex<float>} or \tcode{float},
        then both arguments are effectively cast to \tcode{complex<float>}.
\end{enumerate}

\rSec2[ccmplx]{Header \tcode{<ccomplex>}}
\pnum
\indexlibrary{\idxhdr{ccomplex}}%
The header behaves as if it simply includes the header \tcode{<complex>}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%                                                                %%%
%%%                                                                %%%
%%%      Numerical facilities:  Random number generation           %%%
%%%                    (without concepts)                          %%%
%%%                                                                %%%
%%%                                                                %%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\rSec1[rand]{Random number generation}

\indextext{random number generation|(}%
\indextext{distribution|see{random number distribution}}%
\indextext{engine|see{random number engine}}%
\indextext{engine adaptor|see{random number engine adaptor}}%
\indextext{random number generator|see{uniform random number generator}}

\pnum
This subclause defines a facility
for generating (pseudo-)random numbers.

\pnum
In addition to a few utilities,
four categories of entities are described:
\techterm{uniform random number generators},
\techterm{random number engines},
\techterm{random number engine adaptors},
and
\techterm{random number distributions}.
These categorizations are applicable
to types that satisfy the corresponding requirements,
to objects instantiated from such types,
and to templates producing such types when instantiated.
\enternote
 These entities are specified in such a way
 as to permit the binding
 of any uniform random number generator object \tcode{e}
 as the argument
 to any random number distribution object \tcode{d},
 thus producing a zero-argument function object
 such as given by
 \tcode{bind(d,e)}.
\exitnote

\pnum
\indextext{\idxcode{result_type}!entity characterization based on}%
Each of the entities specified via this subclause
has an associated arithmetic type~(\ref{basic.fundamental})
identified as \tcode{result_type}.
With \tcode{T} as the \tcode{result_type}
thus associated with such an entity,
that entity is characterized:
\begin{enumeratea}
 \item
   as \techterm{boolean} or equivalently as \techterm{boolean-valued},
   if \tcode{T} is \tcode{bool};
 \item
   otherwise
   as \techterm{integral} or equivalently as \techterm{integer-valued},
   if \tcode{numeric_limits<T>\colcol{}is_integer} is \tcode{true};
 \item
   otherwise
   as \techterm{floating} or equivalently as \techterm{real-valued}.
\end{enumeratea}
\noindent
If integer-valued,
an entity may optionally be further characterized as
\techterm{signed} or \techterm{unsigned},
according to \tcode{numeric\_limits<T>::is\_signed}.

\pnum
Unless otherwise specified,
all descriptions of calculations
in this subclause
use mathematical real numbers.

\pnum
Throughout this subclause,
the operators
\bitand, \bitor, and \xor
denote the respective conventional bitwise operations.
Further:

\begin{enumeratea}
 \item
   the operator \rightshift\xspace
   denotes a bitwise right shift
   with zero-valued bits appearing in the high bits of the result,
 and
 \item
   the operator $ \leftshift{w} $
   denotes a bitwise left shift
   with zero-valued bits appearing in the low bits of the result,
   and whose result is always taken modulo $2^w$.
\end{enumeratea}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Requirements section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\rSec2[rand.req]{Requirements}%
\indextext{random number generation!requirements|(}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  general requirements section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\rSec3[rand.req.genl]{General requirements}%

\pnum
Throughout this subclause \ref{rand},
the effect of instantiating a template:
\begin{enumeratea}
  \item
    that has a template type parameter
    named \tcode{Sseq}
    is undefined unless the corresponding template argument
    is cv-unqualified and
    satisfies the requirements
    of seed sequence~(\ref{rand.req.seedseq}).
  \item
    that has a template type parameter
    named \tcode{URNG}
    is undefined unless the corresponding template argument
    is cv-unqualified and
    satisfies the requirements
    of uniform random number generator~(\ref{rand.req.urng}).
  \item
    that has a template type parameter
    named \tcode{Engine}
    is undefined unless the corresponding template argument
    is cv-unqualified and
    satisfies the requirements
    of random number engine~(\ref{rand.req.eng}).
  \item
    that has a template type parameter
    named \tcode{RealType}
    is undefined unless the corresponding template argument
    is cv-unqualified and
    is one of
    \tcode{float}, \tcode{double}, or \tcode{long} \tcode{double}.
  \item
    that has a template type parameter
    named \tcode{IntType}
    is undefined unless the corresponding template argument
    is cv-unqualified and
    is one of
      \tcode{short},
      \tcode{int},
      \tcode{long},
      \tcode{long} \tcode{long},
      \tcode{unsigned} \tcode{short},
      \tcode{unsigned} \tcode{int},
      \tcode{unsigned} \tcode{long},
      or
      \tcode{unsigned} \tcode{long} \tcode{long}.
  \item
    that has a template type parameter
    named \tcode{UIntType}
    is undefined unless the corresponding template argument
    is cv-unqualified and
    is one of
      \tcode{unsigned} \tcode{short},
      \tcode{unsigned} \tcode{int},
      \tcode{unsigned} \tcode{long},
      or
      \tcode{unsigned} \tcode{long} \tcode{long}.
\end{enumeratea}

\pnum
Throughout this subclause \ref{rand},
phrases of the form ``\tcode{x} is an iterator of a specific kind''
shall be interpreted as equivalent to the more formal requirement that
``\tcode{x} is a value
of a type satisfying the requirements
of the specified iterator type.''

\pnum
Throughout this subclause \ref{rand},
any constructor that can be called with a single argument
and that satisfies a requirement specified in this subclause
shall be declared \tcode{explicit}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Seed Sequence requirements:

\rSec3[rand.req.seedseq]{Seed sequence requirements}%
\indextext{seed sequence!requirements|(}%
\indextext{requirements!seed sequence|(}

\pnum
 A \techterm{seed sequence}\indextext{seed sequence}
 is an object
 that consumes a sequence
 of integer-valued data
 and produces a requested number
 of unsigned integer values $i$, $ 0 \le i < 2^{32} $,
 based on the consumed data.
\enternote
 Such an object provides a mechanism
 to avoid replication of streams of random variates.
 This can be useful, for example, in applications
 requiring large numbers of random number engines.
\exitnote

\pnum
A class \tcode{S}
satisfies the requirements
of a seed sequence
if the expressions shown
in Table~\ref{tab:SeedSequence}
are valid and have the indicated semantics,
and if \tcode{S} also satisfies all other requirements
of this section \ref{rand.req.seedseq}.
In that Table and throughout this section:
\begin{enumeratea}
  \item
    \tcode{T} is the type named by
    \tcode{S}'s associated \tcode{result_type};
  \item
    \tcode{q} is a value of \tcode{S}
    and
    \tcode{r} is a possibly const value of \tcode{S};
  \item
    \tcode{ib} and \tcode{ie} are input iterators
    with an unsigned integer \tcode{value_type} of at least 32 bits;
  \item
    \tcode{rb} and \tcode{re} are mutable random access iterators
    with an unsigned integer \tcode{value_type} of at least 32 bits;
  \item
    \tcode{ob} is an output iterator;
  and
  \item
    \tcode{il} is a value of \tcode{initializer_list<T>}.
\end{enumeratea}


\begin{libreqtab4d}
  {Seed sequence requirements}
  {tab:SeedSequence}
\\ \topline
\lhdr{Expression}
  & \chdr{Return type}
  & \chdr{Pre/post-condition}
  & \rhdr{Complexity}
  \\ \capsep
\endfirsthead
\continuedcaption\\
\hline
\lhdr{Expression}
  & \chdr{Return type}
  & \chdr{Pre/post-condition}
  & \rhdr{Complexity}
  \\ \capsep
\endhead
\indextext{\idxcode{result_type}!seed sequence requirement}%
\tcode{S::result_type}
  & \tcode{T}
  & \tcode{T} is an unsigned integer type~(\ref{basic.fundamental})
    of at least 32 bits.
  & compile-time
  \\ \rowsep
\tcode{S()}%
\indextext{default constructor!seed sequence requirement}
  &
  & Creates a seed sequence
    with the same initial state as all other default-constructed seed sequences
    of type \tcode{S}.
  & constant
  \\ \rowsep
\tcode{S(ib,ie)}%
\indextext{sequence constructor!seed sequence requirement}
  &
  & Creates a seed sequence
    having internal state
    that depends on some or all of the bits
    of the supplied sequence $[\tcode{ib},\tcode{ie})$.
  & \bigoh{\tcode{ie} - \tcode{ib}}
  \\ \rowsep
\tcode{S(il)}%
\indextext{initializer-list constructor!seed sequence requirement}
  &
  & Same as \tcode{S(il.begin(), il.end())}.
  & same as \tcode{S(il.begin(), il.end())}
  \\ \rowsep
\tcode{q.generate(rb,re)}%
\indextext{\idxcode{generate}!seed sequence requirement}
  & \tcode{void}
  & Does nothing if \tcode{rb == re}.
    Otherwise,
    fills the supplied sequence $[\tcode{rb},\tcode{re})$
    with 32-bit quantities
    that depend on the sequence supplied to the constructor
    and possibly also depend on the history
    of \tcode{generate}'s previous invocations.
  & \bigoh{\tcode{re} - \tcode{rb}}
  \\ \rowsep
\tcode{r.size()}%
\indextext{\idxcode{size}!seed sequence requirement}
  & \tcode{size_t}
  & The number of 32-bit units
    that would be copied
    by a call to \tcode{r.param}.
  & constant
  \\ \rowsep
\tcode{\tcode{r.param(ob)}}%
\indextext{\idxcode{param}!seed sequence requirement}
  & \tcode{void}
  & Copies to the given destination
    a sequence of 32-bit units
    that can be provided
    to the constructor of a second object of type \tcode{S},
    and that would reproduce in that second object
    a state indistinguishable
    from the state of the first object.
  & \bigoh{\tcode{r.size()}}
  \\
\end{libreqtab4d}%

\indextext{requirements!seed sequence|)}
\indextext{seed sequence!requirements|)}%



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Uniform Random Number Generator requirements:

\rSec3[rand.req.urng]{Uniform random number generator requirements}%
\indextext{uniform random number generator!requirements|(}%
\indextext{requirements!uniform random number generator|(}

\pnum
A \techterm{uniform random number generator}
\tcode{g} of type \tcode{G}
is a function object
returning unsigned integer values
such that each value
in the range of possible results
has (ideally) equal probability
of being returned.
\enternote
 The degree to which \tcode{g}'s results
 approximate the ideal
 is often determined statistically.
\exitnote

\pnum
A class \tcode{G}
satisfies the requirements
of a \techterm{uniform random number generator}
if the expressions shown
in Table~\ref{tab:UniformRandomNumberGenerator}
are valid and have the indicated semantics,
and if \tcode{G} also satisfies all other requirements
of this section \ref{rand.req.urng}.
In that Table and throughout this section:
\begin{enumeratea}
  \item
    \tcode{T} is the type named by
    \tcode{G}'s associated \tcode{result_type},
  and
  \item
    \tcode{g} is a value of \tcode{G}.
\end{enumeratea}

\begin{libreqtab4d}
  {Uniform random number generator requirements}
  {tab:UniformRandomNumberGenerator}
\\ \topline
\lhdr{Expression}
  & \chdr{Return type}
  & \chdr{Pre/post-condition}
  & \rhdr{Complexity}
  \\ \capsep
\endfirsthead
\hline
\lhdr{Expression}
  & \chdr{Return type}
  & \chdr{Pre/post-condition}
  & \rhdr{Complexity}
  \\ \capsep
\endhead
\indextext{\idxcode{result_type}!uniform random number generator requirement}%
\tcode{G::result_type}
  & \tcode{T}
  & \tcode{T} is an unsigned integer type~(\ref{basic.fundamental}).
  & compile-time
  \\ \rowsep
\tcode{g()}%
\indextext{\idxcode{operator()}!uniform random number generator requirement}
  & \tcode{T}
  & Returns a value in the closed interval
    $[$\tcode{G::min()}, \tcode{G::max()}$]$.
  & amortized constant
  \\ \rowsep
\tcode{G::min()}%
\indextext{\idxcode{min}!uniform random number generator requirement}
  & \tcode{T}
  & Denotes the least value potentially returned
    by \tcode{operator()}.
  & compile-time
  \\ \rowsep
\tcode{G::max()}
\indextext{\idxcode{max}!uniform random number generator requirement}
  & \tcode{T}
  & Denotes the greatest value potentially returned
    by \tcode{operator()}.
  & compile-time
  \\
\end{libreqtab4d}

\pnum
The following relation shall hold:
\tcode{G::min() < G::max()}.
\indextext{requirements!uniform random number generator|)}%
\indextext{uniform random number generator!requirements|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Random Number Engine requirements:

\rSec3[rand.req.eng]{Random number engine requirements}%
\indextext{random number engine!requirements|(}%
\indextext{requirements!random number engine|(}

\pnum
A \techterm{random number engine}
(commonly shortened to \techterm{engine})
\tcode{e} of type \tcode{E}
is a uniform random number generator
that additionally meets the requirements
(\textit{e.g.}, for seeding and for input/output)
specified in this section.

\pnum
At any given time,
\tcode{e} has a state \state{e}{i}
for some integer $i \geq 0$.
Upon construction,
\tcode{e}
has an initial state \state{e}{0}.
An engine's state may be established via
 a constructor,
 a \tcode{seed} function,
 assignment,
 or a suitable \tcode{operator\shr{}}.

\pnum
\tcode{E}'s specification shall define:
\begin{enumeratea}
 \item
   the size of \tcode{E}'s state
   in multiples of the size of \tcode{result_type},
   given as an integral constant expression;
 \item
   the \techterm{transition algorithm}
   $ \mathsf{TA} $
   by which \tcode{e}'s state \state{e}{i}
   is advanced to its \techterm{successor state}
   \state{e}{i+1};
 and
 \item
   the \techterm{generation algorithm}
   $ \mathsf{GA} $
   by which an engine's state is mapped
   to a value of type \tcode{result_type}.
\end{enumeratea}

\pnum
A class \tcode{E}
that satisfies the requirements
of a uniform random number generator~(\ref{rand.req.urng})
also satisfies the requirements
of a \techterm{random number engine}
if the expressions shown
in Table~\ref{tab:RandomEngine}
are valid and have the indicated semantics,
and if \tcode{E} also satisfies all other requirements
of this section \ref{rand.req.eng}.
In that Table and throughout this section:
\begin{enumeratea}
  \item
    \tcode{T} is the type named by
    \tcode{E}'s associated \tcode{result_type};
  \item
    \tcode{e} is a value of \tcode{E},
    \tcode{v} is an lvalue of \tcode{E},
    \tcode{x} and \tcode{y} are (possibly \tcode{const}) values of \tcode{E};
  \item
    \tcode{s} is a value of \tcode{T};
  \item
    \tcode{q} is an lvalue
    satisfying the requirements of a seed sequence~(\ref{rand.req.seedseq});
  \item
    \tcode{z} is a value
    of type \tcode{unsigned long long};
  \item
    \tcode{os} is an lvalue of the type of some class template specialization
    \tcode{basic_ostream<charT,} \tcode{traits>};
  and
  \item
    \tcode{is} is an lvalue of the type of some class template specialization
    \tcode{basic_istream<charT,} \tcode{traits>};
\end{enumeratea}
where \tcode{charT} and \tcode{traits} are constrained
according to Clause~\ref{strings} and Clause~\ref{input.output}.

\begin{libreqtab4d}
  {Random number engine requirements}
  {tab:RandomEngine}
\\ \topline
\lhdr{Expression}
  & \chdr{Return type}
  & \chdr{Pre/post-condition}
  & \rhdr{Complexity}
  \\ \capsep
\endfirsthead
\hline
\lhdr{Expression}
  & \chdr{Return type}
  & \chdr{Pre/post-condition}
  & \rhdr{Complexity}
  \\ \capsep
\endhead
\tcode{E()}%
\indextext{constructor!random number engine requirement}
  &
  & Creates an engine
    with the same initial state
    as all other default-constructed engines
    of type \tcode{E}.
  & \bigoh{$\mbox{size of state}$}
  \\ \rowsep
\tcode{E(x)}
\indextext{copy constructor!random number engine requirement}
  &
  & Creates an engine
    that compares equal to \tcode{x}.
  & \bigoh{$\mbox{size of state}$}
  \\ \rowsep
\tcode{E(s)}%
\indextext{constructor!random number engine requirement}
  &
  & Creates an engine
      with initial state determined by \tcode{s}.
  & \bigoh{$\mbox{size of state}$}
  \\ \rowsep
\tcode{E(q)}%
\indextext{constructor!random number engine requirement}\footnote{  This constructor
  (as well as the subsequent corresponding \tcode{seed()} function)
  may be particularly useful
  to applications requiring
  a large number of independent random sequences.
  }
  &
  & Creates an engine
    with an initial state
    that depends on a sequence
    produced by one call
    to \tcode{q.generate}.
  & same as complexity of \tcode{q.generate}
    called on a sequence
    whose length is size of state
  \\ \rowsep
\tcode{e.seed()}%
\indextext{\idxcode{seed}!random number engine requirement}
  & \tcode{void}
  & post:
    \tcode{e == E()}.
  & same as \tcode{E()}
  \\ \rowsep
\tcode{e.seed(s)}%
\indextext{\idxcode{seed}!random number engine requirement}
  & \tcode{void}
  & post:
    \tcode{e == E(s)}.
  & same as \tcode{E(s)}
  \\ \rowsep
\tcode{e.seed(q)}%
\indextext{\idxcode{seed}!random number engine requirement}
  & \tcode{void}
  & post:
    \tcode{e == E(q)}.
  & same as \tcode{E(q)}
  \\ \rowsep
\tcode{e()}%
\indextext{\idxcode{operator()}!random number engine requirement}
  & \tcode{T}
  & Advances \tcode{e}'s state \state{e}{i} to
      \state{e}{i+1} $ = \mathsf{TA}($\state{e}{i}$)$
    and returns
      $ \mathsf{GA}($\state{e}{i}$)$.
  & per Table~\ref{tab:UniformRandomNumberGenerator}
  \\ \rowsep
\tcode{e.discard(z)}%
\indextext{\idxcode{discard}!random number engine requirement}
\footnote{  This operation is common
  in user code,
  and can often be implemented
  in an engine-specific manner
  so as to provide significant performance improvements
  over an equivalent naive loop
  that makes \tcode{z} consecutive calls \tcode{e()}.
}
  & \tcode{void}
  & Advances \tcode{e}'s state \state{e}{i}
      to $\tcode{e}_{i+\tcode{z}}$
      by any means equivalent to \tcode{z} consecutive calls \tcode{e()}.
  & no worse than the complexity
    of \tcode{z} consecutive calls \tcode{e()}
  \\ \rowsep
\tcode{x == y}%
\indextext{\idxcode{operator==}!random number engine requirement}
  & \tcode{bool}
  & This operator is an equivalence relation.
    With $S_x$ and $S_y$
    as the infinite sequences of values
    that would be generated
    by repeated future calls
    to \tcode{x()} and \tcode{y()},
    respectively,
    returns \tcode{true}
      if $ S_x = S_y $;
    else returns \tcode{false}.
  & \bigoh{$\mbox{size of state}$}
  \\ \rowsep
\tcode{x != y}%
\indextext{\idxcode{operator"!=}!random number engine requirement}
  & \tcode{bool}
  & \tcode{!(x == y)}.
  & \bigoh{$\mbox{size of state}$}
  \\ \rowsep
\tcode{os \shl{} x}%
\indextext{\idxcode{operator\shl}!random number engine requirement}
  & reference to the type of \tcode{os}
  & With \tcode{os.}\textit{fmtflags} set to
    \tcode{ios_base\colcol{}dec|ios_base\colcol{}left}
    and the fill character set to the space character,
    writes to \tcode{os}
    the textual representation
    of \tcode{x}'s current state.
    In the output,
    adjacent numbers are separated
    by one or more space characters.

    post: The \tcode{os.}\textit{fmtflags} and fill character are unchanged.
  & \bigoh{$\mbox{size of state}$}
  \\ \rowsep
\tcode{is \shr{} v}%
\indextext{\idxcode{operator\shr}!random number engine requirement}
  & reference to the type of \tcode{is}
  & With \tcode{is.fmtflags}
    set to \tcode{ios_base::dec},
    sets \tcode{v}'s state
    as determined by reading its textual representation from \tcode{is}.
    If bad input is encountered,
    ensures that \tcode{v}'s state is unchanged by the operation
    and
    calls \tcode{is.setstate(ios::failbit)}
    (which may throw \tcode{ios::failure}~[\ref{iostate.flags}]).
    If a textual representation written via \tcode{os \shl{} x}
    was subsequently read via \tcode{is \shr{} v},
    then \tcode{x == v}
    provided that there have been no intervening invocations
    of \tcode{x} or of \tcode{v}.

    pre:
    \tcode{is} provides a textual representation
    that was previously written
    using an output stream
    whose imbued locale
    was the same as that of \tcode{is},
    and whose type's template specialization arguments
    \tcode{charT} and \tcode{traits}
    were respectively the same as those of \tcode{is}.

    post: The \tcode{is.}\textit{fmtflags} are unchanged.
  & \bigoh{$\mbox{size of state}$}
  \\
\end{libreqtab4d}

\pnum
\tcode{E} shall meet the requirements
of \tcode{CopyConstructible} (Table~\ref{copyconstructible})
and \tcode{CopyAssignable} (Table~\ref{copyassignable}) types.
These operations shall each be of complexity
no worse than \bigoh{\mbox{size of state}}.


\indextext{requirements!random number engine|)}
\indextext{random number engine!requirements|)}%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Random Number Engine Adaptor requirements:

\rSec3[rand.req.adapt]{Random number engine adaptor requirements}%

\pnum
A \techterm{random number engine adaptor}
(commonly shortened to \techterm{adaptor})
\tcode{a} of type \tcode{A}
is a random number engine
that takes values
produced by some other random number engine,
and applies an algorithm to those values
in order to deliver a sequence of values
with different randomness properties.
An engine \tcode{b} of type \tcode{B} adapted in this way
is termed a \techterm{base engine}
in this context.
The expression \tcode{a.base()} shall be valid and shall return a
const reference to \tcode{a}'s base engine.

\pnum
The requirements of a random number engine type
shall be interpreted as follows
with respect to a random number engine adaptor type.

\begin{itemdecl}
A::A();
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
 The base engine is initialized
 as if by its default constructor.
\end{itemdescr}

\begin{itemdecl}
bool operator==(const A& a1, const A& a2);
\end{itemdecl}

\begin{itemdescr}
\pnum\returns
 \tcode{true} if \tcode{a1}'s base engine is equal to \tcode{a2}'s base engine.
 Otherwise returns \tcode{false}.
\end{itemdescr}


\begin{itemdecl}
A::A(result_type s);  
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
 The base engine is initialized
 with \tcode{s}.
\end{itemdescr}


\begin{itemdecl}
template<class Sseq> void A::A(Sseq& q);  
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
 The base engine is initialized
 with \tcode{q}.
\end{itemdescr}

\begin{itemdecl}
void seed();  
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
 With \tcode{b} as the base engine, invokes \tcode{b.seed()}.
\end{itemdescr}

\begin{itemdecl}
void seed(result_type s);  
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
 With \tcode{b} as the base engine, invokes \tcode{b.seed(s)}.
\end{itemdescr}

\begin{itemdecl}
template<class Sseq> void seed(Sseq& q);  
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
 With \tcode{b} as the base engine, invokes \tcode{b.seed(q)}.
\end{itemdescr}

\pnum
\tcode{A} shall also satisfy
the following additional requirements:
\begin{enumeratea}
 \item
   The complexity
   of each function
   shall not exceed the complexity
   of the corresponding function
   applied to the base engine.
 \item
   The state
   of \tcode{A}
   shall include the state
   of its base engine.
   The size of \tcode{A}'s state
   shall be no less than the size of the base engine.
 \item
   Copying \tcode{A}'s state
   (\textit{e.g.}, during copy construction or copy assignment)
   shall include copying
   the state of the base engine of \tcode{A}.
 \item
   The textual representation
   of \tcode{A}
   shall include
   the textual representation of its base engine.
\end{enumeratea}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Random Number Distribution requirements:

\rSec3[rand.req.dist]{Random number distribution requirements}%
\indextext{random number distribution!requirements|(}%
\indextext{requirements!random number distribution|(}

\pnum
A \techterm{random number distribution}
(commonly shortened to \techterm{distribution})
\tcode{d} of type \tcode{D}
is a function object
returning values
that are distributed according to
an associated mathematical \techterm{probability density function}
$p(z)$
or according to
an associated \techterm{discrete probability function}
$P(z_i)$.
A distribution's specification
identifies its associated probability function
$p(z)$ or $P(z_i)$.

\pnum
An associated probability function is typically expressed
using certain externally-supplied quantities
known as the \techterm{parameters of the distribution}.
Such distribution parameters are identified
in this context by writing, for example,
  $p(z\,|\,a,b)$ or $P(z_i\,|\,a,b)$,
  to name specific parameters,
or by writing, for example,
  $p(z\,|\left\{\tcode{p}\right\})$
  or $P(z_i\,|\left\{\tcode{p}\right\})$,
  to denote a distribution's parameters \tcode{p} taken as a whole.

\pnum
A class \tcode{D}
satisfies the requirements
of a \techterm{random number distribution}
if the expressions shown
in Table~\ref{tab:RandomDistribution}
are valid and have the indicated semantics,
and if \tcode{D} and its associated types
also satisfy all other requirements
of this section \ref{rand.req.dist}.
In that Table and throughout this section,
\begin{enumeratea}
  \item
    \tcode{T} is the type named by
    \tcode{D}'s associated \tcode{result_type};
  \item
    \tcode{P} is the type named by
    \tcode{D}'s associated \tcode{param_type};
  \item
    \tcode{d} is a
    value of \tcode{D},
    and
    \tcode{x} and \tcode{y} are (possibly \tcode{const}) values of \tcode{D};
  \item
    \tcode{glb} and \tcode{lub}
    are values of \tcode{T}
    respectively corresponding to
    the greatest lower bound and the least upper bound
    on the values potentially returned by \tcode{d}'s \tcode{operator()},
    as determined by the current values of \tcode{d}'s parameters;
  \item
    \tcode{p} is a (possibly \tcode{const}) value of \tcode{P};
  \item
    \tcode{g}, \tcode{g1}, and \tcode{g2} are lvalues of a type
    satisfying the requirements
    of a uniform random number generator [\ref{rand.req.urng}];
  \item
    \tcode{os} is an lvalue of the type of some class template specialization
    \tcode{basic_ostream<charT,} \tcode{traits>};
  and
  \item
    \tcode{is} is an lvalue of the type of some class template specialization
    \tcode{basic_istream<charT,} \tcode{traits>};
\end{enumeratea}
where \tcode{charT} and \tcode{traits} are constrained
according to Clauses~\ref{strings} and \ref{input.output}.

\begin{libreqtab4d}
  {Random number distribution requirements}
  {tab:RandomDistribution}
\\ \topline
\lhdr{Expression}
  & \chdr{Return type}
  & \chdr{Pre/post-condition}
  & \rhdr{Complexity}
  \\ \capsep
\endfirsthead
\hline
\lhdr{Expression}
  & \chdr{Return type}
  & \chdr{Pre/post-condition}
  & \rhdr{Complexity}
  \\ \capsep
\endhead
\indextext{\idxcode{result_type}!random number distribution requirement}%
\tcode{D::result_type}
  & \tcode{T}
  & \tcode{T} is an arithmetic type~(\ref{basic.fundamental}).
  & compile-time
  \\ \rowsep
\tcode{D::param_type}
\indextext{\idxcode{param_type}!random number distribution requirement}
  & \tcode{P}
  &
  & compile-time
  \\ \rowsep
\tcode{D()}%
\indextext{default constructor!random number distribution requirement}
  &
  & Creates a distribution whose behavior is indistinguishable
    from that of any other newly default-constructed distribution
    of type \tcode{D}.
  & constant
  \\ \rowsep
\tcode{D(p)}
\indextext{constructor!random number distribution requirement}
  &
  & Creates a distribution whose behavior is indistinguishable
    from that of a distribution
    newly constructed directly from the values used to construct \tcode{p}.
  & same as \tcode{p}'s construction
  \\ \rowsep
\tcode{d.reset()}
\indextext{\idxcode{reset}!random number distribution requirement}
  & \tcode{void}
  & Subsequent uses of \tcode{d} do not depend
    on values produced by any engine
    prior to invoking \tcode{reset}.
  & constant
  \\ \rowsep
\tcode{x.param()}
\indextext{\idxcode{param}!random number distribution requirement}
  & \tcode{P}
  & Returns a value
    \tcode{p} such that \tcode{D(p).param() == p}.
  & no worse than the complexity of \tcode{D(p)}
  \\ \rowsep
\tcode{d.param(p)}
\indextext{\idxcode{param}!random number distribution requirement}
  & \tcode{void}
  & post: \tcode{d.param() == p}.
  & no worse than the complexity of \tcode{D(p)}
  \\ \rowsep
\tcode{d(g)}
\indextext{\idxcode{operator()}!random number distribution requirement}
  & \tcode{T}
  & With $\texttt{p} = \texttt{d.param()}$,
    the sequence of numbers
    returned by successive invocations
    with the same object \tcode{g}
    is randomly distributed
    according to the associated
      $p(z\,|\left\{\texttt{p}\right\})$
    or
      $P(z_i\,|\left\{\texttt{p}\right\})$
    function.
  & amortized constant number of invocations of \tcode{g}
  \\ \rowsep
\tcode{d(g,p)}
\indextext{\idxcode{operator()}!random number distribution requirement}
  & \tcode{T}
  & The sequence of numbers
    returned by successive invocations
    with the same objects \tcode{g} and \tcode{p}
    is randomly distributed
    according to the associated
      $p(z\,|\left\{\texttt{p}\right\})$
    or
      $P(z_i\,|\left\{\texttt{p}\right\})$
    function.
  & amortized constant number of invocations of \tcode{g}
  \\ \rowsep
\tcode{x.min()}
\indextext{\idxcode{min}!random number distribution requirement}
  & \tcode{T}
  & Returns \tcode{glb}.
  & constant
  \\ \rowsep
\tcode{x.max()}
\indextext{\idxcode{max}!random number distribution requirement}
  & \tcode{T}
  & Returns \tcode{lub}.
  & constant
  \\ \rowsep
\tcode{x == y}%
\indextext{\idxcode{operator==}!random number distribution requirement}
  & \tcode{bool}
  & This operator is an equivalence relation.
    Returns \tcode{true}
      if \tcode{x.param() == y.param()} and $ S_1 = S_2 $,
      where $S_1$ and $S_2$ are
      the infinite sequences of values
      that would be generated, respectively,
      by repeated future calls
      to \tcode{x(g1)} and \tcode{y(g2)}
      whenever \tcode{g1 == g2}.
      Otherwise returns \tcode{false}.
  & constant
  \\ \rowsep
\tcode{x != y}%
\indextext{\idxcode{operator"!=}!random number distribution requirement}
  & \tcode{bool}
  & \tcode{!(x == y)}.
  & same as \tcode{x == y}.
  \\ \rowsep
\tcode{os \shl{} x}
\indextext{\idxcode{operator\shl}!random number distribution requirement}
  & reference to the type of \tcode{os}
  & Writes to \tcode{os} a textual representation
    for the parameters and the additional internal data of \tcode{x}.

    post: The \tcode{os.}\textit{fmtflags} and fill character are unchanged.
  &
  \\ \rowsep
\tcode{is \shr{} d}
\indextext{\idxcode{operator\shr}!random number distribution requirement}
  & reference to the type of \tcode{is}
  & Restores from \tcode{is}
    the parameters and additional internal data of the lvalue \tcode{d}.
    If bad input is encountered,
    ensures that \tcode{d} is unchanged by the operation
    and
    calls \tcode{is.setstate(ios\colcol{}failbit)}
    (which may throw \tcode{ios\colcol{}failure}~[\ref{iostate.flags}]).

    pre: \tcode{is} provides a textual representation
    that was previously written
    using an \tcode{os} whose imbued locale
    and whose type's template specialization arguments
    \tcode{charT} and \tcode{traits}
    were the same as those of \tcode{is}.

    post: The \tcode{is.}\textit{fmtflags} are unchanged.
  &
  \\
\end{libreqtab4d}

\pnum
\tcode{D} shall satisfy the requirements
of \tcode{CopyConstructible} (Table~\ref{copyconstructible})
and \tcode{CopyAssignable} (Table~\ref{copyassignable}) types.

\pnum
The sequence of numbers
produced by repeated invocations of \tcode{d(g)}
shall be independent of any invocation of
\tcode{os \shl{} d}
or of
any \tcode{const} member function of \tcode{D}
between any of the invocations \tcode{d(g)}.

\pnum
If a textual representation is written using \tcode{os \shl{} x}
and that representation is restored
into the same or a different object \tcode{y}
of the same type using \tcode{is \shr{} y},
repeated invocations of \tcode{y(g)}
shall produce the same sequence of numbers
as would repeated invocations of \tcode{x(g)}.

\pnum
It is unspecified whether \tcode{D::param_type}
is declared as a (nested) \tcode{class}
or via a \tcode{typedef}.
In this subclause \ref{rand},
declarations of \tcode{D::param_type}
are in the form of \tcode{typedef}s
for convenience of exposition only.

\pnum
\tcode{P} shall satisfy the requirements
of \tcode{CopyConstructible} (Table~\ref{copyconstructible}),
\tcode{CopyAssignable} (Table~\ref{copyassignable}),
and
\tcode{EqualityComparable} (Table~\ref{equalitycomparable}) types.

\pnum
For each of the constructors of \tcode{D}
taking arguments corresponding to parameters of the distribution,
\tcode{P} shall have a corresponding constructor
subject to the same requirements
and taking arguments identical in number, type, and default values.
Moreover,
for each of the member functions of \tcode{D}
that return values corresponding to parameters of the distribution,
\tcode{P} shall have a corresponding member function
with the identical name, type, and semantics.

\pnum
\tcode{P} shall have a declaration of the form
\begin{codeblock}
typedef  D  distribution_type;
\end{codeblock}

\indextext{requirements!random number distribution|)}%
\indextext{random number distribution!requirements|)}%
\indextext{random number generation!requirements|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Header synopsis section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\rSec2[rand.synopsis]{Header \tcode{<random>} synopsis}%
\indexlibrary{\idxhdr{random}|(}%
\indextext{random number generation!synopsis|(}

\begin{codeblock}
#include <initializer_list>

namespace std {

 // \ref{rand.eng.lcong}, class template linear_congruential_engine
 template<class UIntType, UIntType a, UIntType c, UIntType m>
   class linear_congruential_engine;

 // \ref{rand.eng.mers}, class template mersenne_twister_engine
 template<class UIntType, size_t w, size_t n, size_t m, size_t r,
          UIntType a, size_t u, UIntType d, size_t s,
          UIntType b, size_t t,
          UIntType c, size_t l, UIntType f>
   class mersenne_twister_engine;

 // \ref{rand.eng.sub}, class template subtract_with_carry_engine
 template<class UIntType, size_t w, size_t s, size_t r>
   class subtract_with_carry_engine;

 // \ref{rand.adapt.disc}, class template discard_block_engine
 template<class Engine, size_t p, size_t r>
   class discard_block_engine;

 // \ref{rand.adapt.ibits}, class template independent_bits_engine
 template<class Engine, size_t w, class UIntType>
   class independent_bits_engine;

 // \ref{rand.adapt.shuf}, class template shuffle_order_engine
 template<class Engine, size_t k>
   class shuffle_order_engine;

 // \ref{rand.predef}, engines and engine adaptors with predefined parameters
 typedef @\seebelow@ minstd_rand0;
 typedef @\seebelow@ minstd_rand;
 typedef @\seebelow@ mt19937;
 typedef @\seebelow@ mt19937_64;
 typedef @\seebelow@ ranlux24_base;
 typedef @\seebelow@ ranlux48_base;
 typedef @\seebelow@ ranlux24;
 typedef @\seebelow@ ranlux48;
 typedef @\seebelow@ knuth_b;
 typedef @\seebelow@ default_random_engine;

 // \ref{rand.device}, class random_device
 class random_device;

 // \ref{rand.util.seedseq}, class seed_seq
 class seed_seq;

 // \ref{rand.util.canonical}, function template generate_canonical
 template<class RealType, size_t bits, class URNG>
   RealType generate_canonical(URNG& g);

 // \ref{rand.dist.uni.int}, class template uniform_int_distribution
 template<class IntType = int>
   class uniform_int_distribution;

 // \ref{rand.dist.uni.real}, class template uniform_real_distribution
 template<class RealType = double>
   class uniform_real_distribution;

 // \ref{rand.dist.bern.bernoulli}, class bernoulli_distribution
 class bernoulli_distribution;

 // \ref{rand.dist.bern.bin}, class template binomial_distribution
 template<class IntType = int>
   class binomial_distribution;

 // \ref{rand.dist.bern.geo}, class template geometric_distribution
 template<class IntType = int>
   class geometric_distribution;

 // \ref{rand.dist.bern.negbin}, class template negative_binomial_distribution
 template<class IntType = int>
   class negative_binomial_distribution;

 // \ref{rand.dist.pois.poisson}, class template poisson_distribution
 template<class IntType = int>
   class poisson_distribution;

 // \ref{rand.dist.pois.exp}, class template exponential_distribution
 template<class RealType = double>
   class exponential_distribution;

 // \ref{rand.dist.pois.gamma}, class template gamma_distribution
 template<class RealType = double>
   class gamma_distribution;

 // \ref{rand.dist.pois.weibull}, class template weibull_distribution
 template<class RealType = double>
   class weibull_distribution;

 // \ref{rand.dist.pois.extreme}, class template extreme_value_distribution
 template<class RealType = double>
   class extreme_value_distribution;

 // \ref{rand.dist.norm.normal}, class template normal_distribution
 template<class RealType = double>
   class normal_distribution;

 // \ref{rand.dist.norm.lognormal}, class template lognormal_distribution
 template<class RealType = double>
   class lognormal_distribution;

 // \ref{rand.dist.norm.chisq}, class template chi_squared_distribution
 template<class RealType = double>
   class chi_squared_distribution;

 // \ref{rand.dist.norm.cauchy}, class template cauchy_distribution
 template<class RealType = double>
   class cauchy_distribution;

 // \ref{rand.dist.norm.f}, class template fisher_f_distribution
 template<class RealType = double>
   class fisher_f_distribution;

 // \ref{rand.dist.norm.t}, class template student_t_distribution
 template<class RealType = double>
   class student_t_distribution;

 // \ref{rand.dist.samp.discrete}, class template discrete_distribution
 template<class IntType = int>
   class discrete_distribution;

 // \ref{rand.dist.samp.pconst}, class template piecewise_constant_distribution
 template<class RealType = double>
   class piecewise_constant_distribution;

 // \ref{rand.dist.samp.plinear}, class template piecewise_linear_distribution
 template<class RealType = double>
   class piecewise_linear_distribution;

} // namespace std
\end{codeblock}%
\indextext{random number generation!synopsis|)}%
\indexlibrary{\idxhdr{random}|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Engine class templates section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\rSec2[rand.eng]{Random number engine class templates}%
\indextext{random number generation!engines|(}

\pnum
Each type instantiated
from a class template specified in this section~\ref{rand.eng}
satisfies the requirements
of a random number engine~(\ref{rand.req.eng}) type.

\pnum
Except where specified otherwise,
the complexity of each function
specified in this section~\ref{rand.eng}
is constant.

\pnum
Except
where specified otherwise,
no function described in this section~\ref{rand.eng}
throws an exception.

\pnum
Descriptions are provided in this section~\ref{rand.eng}
only for engine operations
that are not described in  \mbox{\ref{rand.req.eng}}
or for operations where there is additional semantic information.
In particular,
declarations for copy constructors,
for copy assignment operators,
for streaming operators,
and for equality and inequality operators
are not shown in the synopses.

\pnum
Each template specified in this section~\ref{rand.eng}
requires one or more relationships,
involving the value(s) of its non-type template parameter(s), to hold.
A program instantiating any of these templates
is ill-formed
if any such required relationship fails to hold.

\pnum
For every random number engine and for every random number engine adaptor \tcode{X}
defined in this sub-clause~(\ref{rand.eng}) and in sub-clause~\ref{rand.adapt}:

\begin{itemize}
\item
if the constructor
\begin{codeblock}
template <class Sseq> explicit X(Sseq& q);
\end{codeblock}
is called with a type \tcode{Sseq} that does not qualify as a seed sequence, then this
constructor shall not participate in overload resolution;

\item
if the member function
\begin{codeblock}
template <class Sseq> void seed(Sseq& q);
\end{codeblock}
is called with a type \tcode{Sseq} that does not qualify as a seed sequence, then this
function shall not participate in overload resolution.
\end{itemize}

The extent to which an implementation determines that a type cannot be a seed sequence
is unspecified, except that as a minimum a type shall not qualify as a seed sequence
if it is implicitly convertible to \tcode{X::result_type}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% linear_congruential_engine engine:

\rSec3[rand.eng.lcong]{Class template \tcode{linear_congruential_engine}}%
\indexlibrary{\idxcode{linear_congruential_engine}}%
\indextext{random number engine!\idxcode{linear_congruential_engine}}

\pnum
A \tcode{linear_congruential_engine} random number engine
produces unsigned integer random numbers.
The state%
\indextext{\idxcode{linear_congruential_engine}!state}
\indextext{state!\idxcode{linear_congruential_engine}}
\state{x}{i}
of a \tcode{linear_congruential_engine} object \tcode{x}
is of size $1$
and consists of a single integer.
The transition algorithm%
\indextext{\idxcode{linear_congruential_engine}!transition algorithm}%
\indextext{transition algorithm!\idxcode{linear_congruential_engine}}
is a modular linear function of the form
$\mathsf{TA}(\state{x}{i}) = (a \cdot \state{x}{i} + c) \bmod m$;
the generation algorithm%
\indextext{\idxcode{linear_congruential_engine}!generation algorithm}%
\indextext{generation algorithm!\idxcode{linear_congruential_engine}}
is $ \mathsf{GA}(\state{x}{i}) = \state{x}{i+1} $.

\begin{codeblock}
template<class UIntType, UIntType a, UIntType c, UIntType m>
 class linear_congruential_engine
{
public:
 // types
 typedef UIntType result_type;

 // engine characteristics
 static constexpr result_type multiplier = a;
 static constexpr result_type increment = c;
 static constexpr result_type modulus = m;
 static constexpr result_type min() { return c == 0u ? 1u: 0u };
 static constexpr result_type max() { return m - 1u };
 static constexpr result_type default_seed = 1u;

 // constructors and seeding functions
 explicit linear_congruential_engine(result_type s = default_seed);
 template<class Sseq> explicit linear_congruential_engine(Sseq& q);
 void seed(result_type s = default_seed);
 template<class Sseq> void seed(Sseq& q);

 // generating functions
 result_type operator()();
 void discard(unsigned long long z);
};
\end{codeblock}

\pnum
If the template parameter
\tcode{m} is $0$,
the modulus $m$
used throughout this section~\ref{rand.eng.lcong}
\indextext{\idxcode{linear_congruential_engine}!modulus}
is \tcode{numeric_limits<result_type>\colcol{}max()} plus $1$.
\enternote
 $m$ need not be representable
 as a value of type \tcode{result_type}.
\exitnote

\pnum
If the template parameter
\tcode{m} is not $0$,
the following relations shall hold:
  \tcode{a < m}
and
  \tcode{c < m}.

\pnum The textual representation%
\indextext{\idxcode{linear_congruential_engine}!textual representation}
consists of
the value of \state{x}{i}.

\indexlibrary{\idxcode{linear_congruential_engine}!constructor}%

\begin{itemdecl}
explicit linear_congruential_engine(result_type s = default_seed);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{linear_congruential_engine} object.
 If $ c \bmod m $ is $0$ and $ \tcode{s} \bmod m $ is $0$,
 sets the engine's state to $1$,
 otherwise sets the engine's state to $\tcode{s} \bmod m$.
\end{itemdescr}

\indexlibrary{\idxcode{linear_congruential_engine}!constructor}%

\begin{itemdecl}
template<class Sseq> explicit linear_congruential_engine(Sseq& q);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{linear_congruential_engine} object.
 With
 $ k = \left\lceil \frac{\log_2 m}
                        {32}
            \right\rceil
 $
 and $a$ an array (or equivalent)
 of length $k + 3$,
 invokes \tcode{q.generate($a+0$, $a+k+3$)}
 and then computes
 $ S = \left(\sum_{j=0}^{k-1}a_{j+3} \cdot 2^{32j} \right) \bmod m $.
 If
   $ c \bmod m $ is $0$
 and
   $S$ is $0$,
 sets the engine's state to $1$,
 else sets the engine's state
 to $S$.
\end{itemdescr}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% mersenne_twister_engine engine:

\rSec3[rand.eng.mers]{Class template \tcode{mersenne_twister_engine}}%
\indexlibrary{\idxcode{mersenne_twister_engine}}%
\indextext{random number engine!\idxcode{mersenne_twister_engine}}

\pnum
A \tcode{mersenne_twister_engine} random number
engine\footnote{The name of this engine refers, in part, to a property of its period:
 For properly-selected values of the parameters,
 the period is closely related to a large Mersenne prime number.}
produces unsigned integer random numbers
in the closed interval $[0,2^w-1]$.
The
\indextext{\idxcode{mersenne_twister_engine}!state}%
\indextext{state!\idxcode{mersenne_twister_engine}}%
state
\state{x}{i}
of a \tcode{mersenne_twister_engine} object \tcode{x}
is of size $n$
and consists of a sequence $X$
of $n$ values of the type delivered by \tcode{x};
all subscripts applied to $X$ are to be taken modulo $n$.

\pnum
The transition algorithm%
\indextext{\idxcode{mersenne_twister_engine}!transition algorithm}%
\indextext{transition algorithm!\idxcode{mersenne_twister_engine}}
employs a twisted generalized feedback shift register
defined by shift values $n$ and $m$, a twist value $r$,
and a conditional xor-mask $a$.
To improve the uniformity of the result,
the bits of the raw shift register are additionally \techterm{tempered}
(\textit{i.e.}, scrambled)
according to a bit-scrambling matrix
defined by values $u, d, s, b, t, c,$ and $\ell$.

The state transition is performed as follows:
\begin{enumeratea}
 \item
   Concatenate
     the upper $w-r$ bits of $X_{i-n}$
   with
     the lower $r$ bits of $X_{i+1-n}$
   to obtain an unsigned integer value $Y$.
 \item
   With $\alpha = a \cdot (Y \bitand 1)$,
   set $X_i$ to
     $X_{i+m-n} \, \xor \, (Y \rightshift 1) \, \xor \, \alpha$.
\end{enumeratea}
The sequence $X$ is initialized
with the help of an initialization multiplier $f$.

\pnum
The generation algorithm%
\indextext{\idxcode{mersenne_twister_engine}!generation algorithm}%
\indextext{generation algorithm!\idxcode{mersenne_twister_engine}}
 determines the unsigned integer values $z_1, z_2, z_3, z_4$ as follows,
 then delivers $z_4$ as its result:
\begin{enumeratea}
 \item
   Let $z_1 = X_i \xor \bigl(( X_i \rightshift u ) \bitand d\bigr)$.
 \item
   Let $z_2 = z_1 \xor \bigl( (z_1 \leftshift{w} \, s) \bitand b \bigr)$.
 \item
   Let $z_3 = z_2 \xor \bigl( (z_2 \leftshift{w} \, t) \bitand c \bigr)$.
 \item
   Let $z_4 = z_3 \xor ( z_3 \rightshift \ell )$.
\end{enumeratea}

\begin{codeblock}
template<class UIntType, size_t w, size_t n, size_t m, size_t r,
          UIntType a, size_t u, UIntType d, size_t s,
          UIntType b, size_t t,
          UIntType c, size_t l, UIntType f>
 class mersenne_twister_engine
{
public:
 // types
 typedef UIntType result_type;

 // engine characteristics
 static constexpr size_t word_size = w;
 static constexpr size_t state_size = n;
 static constexpr size_t shift_size = m;
 static constexpr size_t mask_bits = r;
 static constexpr UIntType xor_mask = a;
 static constexpr size_t tempering_u = u;
 static constexpr UIntType tempering_d = d;
 static constexpr size_t tempering_s = s;
 static constexpr UIntType tempering_b = b;
 static constexpr size_t tempering_t = t;
 static constexpr UIntType tempering_c = c;
 static constexpr size_t tempering_l = l;
 static constexpr UIntType initialization_multiplier = f;
 static constexpr result_type min () { return 0; }
 static constexpr result_type max() { return  @$2^w - 1$@; }
 static constexpr result_type default_seed = 5489u;

 // constructors and seeding functions
 explicit mersenne_twister_engine(result_type value = default_seed);
 template<class Sseq> explicit mersenne_twister_engine(Sseq& q);
 void seed(result_type value = default_seed);
 template<class Sseq> void seed(Sseq& q);

 // generating functions
 result_type operator()();
 void discard(unsigned long long z);
};
\end{codeblock}

\pnum
The following relations shall hold:
  \tcode{0 < m},
  \tcode{m <= n},
  \tcode{2u < w},
  \tcode{r <= w},
  \tcode{u <= w},
  \tcode{s <= w},
  \tcode{t <= w},
  \tcode{l <= w},
  \tcode{w <= numeric_limits<UIntType>::digits},
  \tcode{a <= (1u\shl{}w) - 1u},
  \tcode{b <= (1u\shl{}w) - 1u},
  \tcode{c <= (1u\shl{}w) - 1u},
  \tcode{d <= (1u\shl{}w) - 1u},
and
  \tcode{f <= (1u\shl{}w) - 1u}.

\pnum
The textual representation%
\indextext{\idxcode{mersenne_twister_engine}!textual representation}
of \state{x}{i}
consists of
the values of
 $X_{i-n}, \ldots, X_{i-1}$,
in that order.

\indexlibrary{\idxcode{mersenne_twister_engine}!constructor}%

\begin{itemdecl}
explicit mersenne_twister_engine(result_type value = default_seed);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{mersenne_twister_engine} object.
Sets $X_{-n}$ to $\tcode{value} \bmod 2^w$.
 Then, iteratively for $i = 1\!-\!n,\ldots,-1$,
 sets $X_i$
 to
\[%
 \bigl[f \cdot
       \bigl(X_{i-1} \xor \bigl(X_{i-1} \rightshift (w-2)\bigr)
       \bigr)
       + i \bmod n
 \bigr] \bmod 2^w
\; \mbox{.}
\]%

\pnum\complexity \bigoh{n}.
\end{itemdescr}

\indexlibrary{\idxcode{mersenne_twister_engine}!constructor}%

\begin{itemdecl}
template<class Sseq> explicit mersenne_twister_engine(Sseq& q);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{mersenne_twister_engine} object.
 With
 $ k = \left\lceil w / 32 \right\rceil $
 and $a$ an array (or equivalent)
 of length $ n \cdot k $,
 invokes \tcode{q.generate($a+0$, $a+n \cdot k$)}
 and then, iteratively for $i = -n,\ldots,-1$,
 sets $X_i$
 to $ \left(\sum_{j=0}^{k-1}a_{k(i+n)+j} \cdot 2^{32j} \right) \bmod 2^w $.
 Finally,
 if the most significant $w-r$ bits of $X_{-n}$
 are zero,
 and if each of the other resulting $X_i$ is $0$,
 changes $X_{-n}$
 to $ 2^{w-1} $.
\end{itemdescr}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% subtract_with_carry_engine engine:

\rSec3[rand.eng.sub]{Class template \tcode{subtract_with_carry_engine}}%
\indexlibrary{\idxcode{subtract_with_carry_engine}}%
\indextext{random number engine!\idxcode{subtract_with_carry_engine}}

\pnum
A \tcode{subtract_with_carry_engine} random number engine
produces unsigned integer random numbers.

\pnum
The state%
\indextext{\idxcode{subtract_with_carry_engine}!state}%
\indextext{state!\idxcode{subtract_with_carry_engine}}
\state{x}{i}
of a \tcode{subtract_with_carry_engine} object \tcode{x}
is of size
\bigoh{r},
and consists of
a sequence $X$ of $r$ integer values $0 \leq X_i < m \,= 2^w$;
all subscripts applied to $X$ are to be taken modulo $r$.
The state \state{x}{i}
additionally consists of an integer $c$
(known as the \techterm{carry})%
\indextext{\idxcode{subtract_with_carry_engine}!carry}%
\indextext{carry!\idxcode{subtract_with_carry_engine}}
whose value is either $0$ or $1$.

\pnum
The state transition%
\indextext{\idxcode{subtract_with_carry_engine}!transition algorithm}%
\indextext{transition algorithm!\idxcode{subtract_with_carry_engine}}
is performed as follows:
\begin{enumeratea}
 \item
   Let $ Y = X_{i-s} - X_{i-r} - c $.
 \item
   Set $X_i$ to $ y = Y \bmod m $.
   Set $c$ to 1 if $Y < 0$,
   otherwise set $c$ to 0.
\end{enumeratea}
\enternote
 This algorithm corresponds
 to a modular linear function
 of the form
 $ \mathsf{TA}(\state{x}{i}) = (a \cdot \state{x}{i}) \bmod b $,
 where $b$ is of the form
 $ m^r - m^s + 1 $
 and $ a = b - (b-1) / m $.
\exitnote

\pnum
The generation algorithm%
\indextext{\idxcode{subtract_with_carry_engine}!generation algorithm}%
\indextext{generation algorithm!\idxcode{subtract_with_carry_engine}}
is given by
$ \mathsf{GA}(\state{x}{i}) = y $,
where
 $y$
is the value produced
as a result
of advancing the engine's state
as described above.

\begin{codeblock}
template<class UIntType, size_t w, size_t s, size_t r>
 class subtract_with_carry_engine
{
public:
 // types
 typedef UIntType result_type;

 // engine characteristics
 static constexpr size_t word_size = w;
 static constexpr size_t short_lag = s;
 static constexpr size_t long_lag = r;
 static constexpr result_type min() { return 0; }
 static constexpr result_type max() { return @$m - 1$@; }
 static constexpr result_type default_seed = 19780503u;

 // constructors and seeding functions
 explicit subtract_with_carry_engine(result_type value = default_seed);
 template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);
 void seed(result_type value = default_seed);
 template<class Sseq> void seed(Sseq& q);

 // generating functions
 result_type operator()();
 void discard(unsigned long long z);
};
\end{codeblock}

\pnum
The following relations shall hold:
  \tcode{0u < s},
  \tcode{s < r},
  \tcode{0 < w},
and
  \tcode{w <= numeric_limits<UIntType>::digits}.

\pnum
The textual representation%
\indextext{\idxcode{subtract_with_carry_engine}!textual representation}%
\indextext{textual representation!\idxcode{subtract_with_carry_engine}}
consists of the values of
 $X_{i-r}, \ldots, X_{i-1}$,
in that order, followed by $c$.


\indexlibrary{\idxcode{subtract_with_carry_engine}!constructor}%
\begin{itemdecl}
explicit subtract_with_carry_engine(result_type value = default_seed);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{subtract_with_carry_engine} object.
 Sets the values of
 $ X_{-r}, \ldots, X_{-1} $,
 in that order, as specified below.
 If $X_{-1}$ is then $0$,
 sets $c$ to $1$;
 otherwise sets $c$ to $0$.

 To set the values $X_k$,
 first construct \tcode{e}, a \tcode{linear_congruential_engine} object,
 as if by the following definition:
\begin{codeblock}
linear_congruential_engine<result_type,
                          40014u,0u,2147483563u> e(value == 0u ? default_seed : value);
\end{codeblock}
 Then, to set each $X_k$,
 obtain new values $ z_0, \ldots, z_{n-1} $
 from $n = \lceil w/32 \rceil $ successive invocations
 of \tcode{e} taken modulo $2^{32}$.
 Set $X_k$ to $ \left( \sum_{j=0}^{n-1} z_j \cdot 2^{32j}\right) \bmod m$.

\pnum\complexity Exactly $n \cdot \tcode{r}$ invocations
 of \tcode{e}.
\end{itemdescr}



\indexlibrary{\idxcode{subtract_with_carry_engine}!constructor}%
\begin{itemdecl}
template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{subtract_with_carry_engine} object.
 With
 $ k = \left\lceil w / 32 \right\rceil $
 and $a$ an array (or equivalent)
 of length $ r \cdot k $,
 invokes \tcode{q.generate($a+0$, $a+r \cdot k$)}
 and then, iteratively for $i = -r, \ldots, -1$,
 sets $X_i$
 to $ \left(\sum_{j=0}^{k-1}a_{k(i+r)+j} \cdot 2^{32j} \right) \bmod m $.
 If $X_{-1}$ is then $0$,
 sets $c$ to $1$;
 otherwise sets $c$ to $0$.
\end{itemdescr}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Engine adaptors class templates section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\rSec2[rand.adapt]{Random number engine adaptor class templates}

\rSec3[rand.adapt.general]{In general}

\pnum
Each type instantiated
from a class template specified in this section~\ref{rand.eng}
satisfies the requirements
of a random number engine adaptor~(\ref{rand.req.adapt}) type.

\pnum
Except where specified otherwise,
the complexity of each function
specified in this section~\ref{rand.adapt}
is constant.

\pnum
Except
where specified otherwise,
no function described in this section~\ref{rand.adapt}
throws an exception.

\pnum
Descriptions are provided in this section~\ref{rand.adapt}
only for adaptor operations
that are not described in section~\ref{rand.req.adapt}
or for operations where there is additional semantic information.
In particular,
declarations for copy constructors,
for copy assignment operators,
for streaming operators,
and for equality and inequality operators
are not shown in the synopses.

\pnum
Each template specified in this section~\ref{rand.adapt}
requires one or more relationships,
involving the value(s) of its non-type template parameter(s), to hold.
A program instantiating any of these templates
is ill-formed
if any such required relationship fails to hold.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% discard_block_engine engine adaptor:

\rSec3[rand.adapt.disc]{Class template \tcode{discard_block_engine}}%
\indexlibrary{\idxcode{discard_block_engine}}%
\indextext{random number engine adaptor!\idxcode{discard_block_engine}}

\pnum
A \tcode{discard_block_engine} random number engine adaptor
produces random numbers
selected from those produced by some base engine $e$.
The state%
\indextext{\idxcode{discard_block_engine}!state}%
\indextext{state!\idxcode{discard_block_engine}}
\state{x}{i}
of a \tcode{discard_block_engine} engine adaptor object \tcode{x}
consists of the state \state{e}{i} of its base engine \tcode{e}
and an additional integer $n$.
The size of the state is
 the size of $e$'s state plus $1$.

\pnum
The transition algorithm%
\indextext{\idxcode{discard_block_engine}!transition algorithm}%
\indextext{transition algorithm!\idxcode{discard_block_engine}}
discards all but $r > 0$ values
from each block of $p \geq r$ values delivered by $e$.
The state transition is performed as follows:
If $n \geq r$,
 advance the state of \tcode{e} from \state{e}{i} to \state{e}{i+p-r}
 and set $n$ to $0$.
In any case,
 then increment $n$
 and advance \tcode{e}'s then-current state \state{e}{j}
 to \state{e}{j+1}.

\pnum
The generation algorithm%
\indextext{\idxcode{discard_block_engine}!generation algorithm}%
\indextext{generation algorithm!\idxcode{discard_block_engine}}
yields the value returned by the last invocation of \tcode{e()}
 while advancing \tcode{e}'s state as described above.

\begin{codeblock}
template<class Engine, size_t p, size_t r>
 class discard_block_engine
{
public:
 // types
 typedef typename Engine::result_type result_type;

 // engine characteristics
 static constexpr size_t block_size = p;
 static constexpr size_t used_block = r;
 static constexpr result_type min() { return Engine::min(); }
 static constexpr result_type max() { return Engine::max(); }

 // constructors and seeding functions
 discard_block_engine();
 explicit discard_block_engine(const Engine& e);
 explicit discard_block_engine(Engine&& e);
 explicit discard_block_engine(result_type s);
 template<class Sseq> explicit discard_block_engine(Sseq& q);
 void seed();
 void seed(result_type s);
 template<class Sseq> void seed(Sseq& q);

 // generating functions
 result_type operator()();
 void discard(unsigned long long z);

 // property functions
 const Engine& base() const noexcept { return e; };

private:
 Engine e;   // \expos
 int n;      // \expos
};
\end{codeblock}

\pnum
The following relations shall hold:
  \tcode{0 < r}
and
  \tcode{r <= p}.

\pnum
The textual representation%
\indextext{\idxcode{discard_block_engine}!textual representation}%
\indextext{textual representation!\idxcode{discard_block_engine}}
consists of
 the textual representation of \tcode{e}
followed by
 the value of \tcode{n}.

\pnum
In addition to its behavior
pursuant to section~\ref{rand.req.adapt},
each constructor%
\indexlibrary{\idxcode{discard_block_engine}!constructor}
that is not a copy constructor
sets \tcode{n} to $0$.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% independent_bits_engine engine adaptor:

\rSec3[rand.adapt.ibits]{Class template \tcode{independent_bits_engine}}%
\indexlibrary{\idxcode{independent_bits_engine}}%
\indextext{random number engine adaptor!\idxcode{independent_bits_engine}}

\pnum
An \tcode{independent_bits_engine}
random number engine adaptor
combines random numbers
that are produced by some base engine $e$,
so as to produce random numbers
with a specified number of bits $w$.
The state%
\indextext{\idxcode{independent_bits_engine}!state}%
\indextext{state!\idxcode{independent_bits_engine}}
\state{x}{i}
of an \tcode{independent_bits_engine}
engine adaptor object \tcode{x}
consists of
 the state \state{e}{i} of its base engine \tcode{e};
the size of the state is
 the size of $e$'s state.

\pnum
The transition and generation algorithms
are described in terms
of the following integral constants:%
\begin{enumeratea}
 \item
   Let
     $ R = \tcode{e.max() - e.min() + 1} $
   and
     $ m = \left\lfloor \log_2 R \right\rfloor $.
 \item
   With $n$ as determined below,
   let
     $ w_0 = \left\lfloor w / n \right\rfloor $,
     $ n_0 = n - w \bmod n $,
     $ y_0 = 2^{w_0} \left\lfloor R / 2^{w_0} \right\rfloor $,
   and
     $ y_1 = 2^{w_0 + 1} \left\lfloor R / 2^{w_0 + 1} \right\rfloor $.
 \item
   Let
     $ n = \left\lceil w / m \right\rceil $
   if and only if the relation
     $ R - y_0 \leq \left\lfloor y_0 / n \right\rfloor $
   holds as a result.
   Otherwise let
     $ n = 1 + \left\lceil w / m \right\rceil $.
\end{enumeratea}
\enternote
 The relation
 $ w = n_0 w_0 + (n - n_0)(w_0 + 1) $
 always holds.
\exitnote

\pnum
The transition algorithm%
\indextext{\idxcode{independent_bits_engine}!transition algorithm}%
\indextext{transition algorithm!\idxcode{independent_bits_engine}}
is carried out
by invoking \tcode{e()}
as often as needed
to obtain
 $ n_0 $
values less than
$ y_0 $ $ + \tcode{e.min()} $
and
 $ n - n_0 $
values less than $ y_1 + \tcode{e.min()} $%
.

\pnum
The generation algorithm%
\indextext{\idxcode{independent_bits_engine}!generation algorithm}%
\indextext{generation algorithm!\idxcode{independent_bits_engine}}
uses the values produced
while advancing the state as described above
to yield a quantity $S$
obtained as if by the following algorithm:
\begin{codeblock}
@$S$@ = 0;
for (@$k$@ = @$0$@; @$k \neq n_0$@; @$k$@ += @$1$@)  {
 do @$u$@ = e() - e.min(); while (@$ u \ge y_0 $@);
 @$S$@ = @$ 2^{w_0} \cdot S + u \bmod 2^{w_0} $@;
}
for (@$k$@ = @$n_0$@; @$k \neq n$@; @$k$@ += @$1$@)  {
 do @$u$@ = e() - e.min(); while (@$ u \ge y_1 $@);
 @$S$@ = @$ 2^{w_0 + 1} \cdot S + u \bmod 2^{w_0 + 1} $@;
}
\end{codeblock}

\begin{codeblock}
template<class Engine, size_t w, class UIntType>
class independent_bits_engine
{
public:
 // types
 typedef UIntType result_type;

 // engine characteristics
 static constexpr result_type min() { return 0; }
 static constexpr result_type max() { return @$2^w - 1$@; }

 // constructors and seeding functions
 independent_bits_engine();
 explicit independent_bits_engine(const Engine& e);
 explicit independent_bits_engine(Engine&& e);
 explicit independent_bits_engine(result_type s);
 template<class Sseq> explicit independent_bits_engine(Sseq& q);
 void seed();
 void seed(result_type s);
 template<class Sseq> void seed(Sseq& q);

 // generating functions
 result_type operator()();
 void discard(unsigned long long z);

 // property functions
 const Engine& base() const noexcept { return e; };

private:
 Engine e;   // \expos
};
\end{codeblock}%

\pnum
The following relations shall hold:
  \tcode{0 < w}
and
  \tcode{w <= numeric_limits<result_type>::digits}.

\pnum
The textual representation%
\indextext{\idxcode{independent_bits_engine}!textual representation}%
\indextext{textual representation!\idxcode{independent_bits_engine}}
consists of
 the textual representation of \tcode{e}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% shuffle_order_engine engine adaptor:

\rSec3[rand.adapt.shuf]{Class template \tcode{shuffle_order_engine}}%
\indexlibrary{\idxcode{shuffle_order_engine}}%
\indextext{random number engine adaptor!\idxcode{shuffle_order_engine}}

\pnum
A \tcode{shuffle_order_engine} random number engine adaptor
produces the same random numbers
that are produced by some base engine $e$,
but delivers them in a different sequence.
The state%
\indextext{\idxcode{shuffle_order_engine}!state}%
\indextext{state!\idxcode{shuffle_order_engine}}
\state{x}{i}
of a \tcode{shuffle_order_engine} engine adaptor object \tcode{x}
consists of
 the state \state{e}{i} of its base engine \tcode{e},
 an additional value $Y$ of the type delivered by \tcode{e},
and
 an additional sequence $V$ of $k$ values
 also of the type delivered by \tcode{e}.
The size of the state is
 the size of $e$'s state plus $k+1$.

\pnum
The transition algorithm%
\indextext{\idxcode{shuffle_order_engine}!transition algorithm}%
\indextext{transition algorithm!\idxcode{shuffle_order_engine}}
permutes the values produced by $e$.
The state transition is performed as follows:
\begin{enumeratea}
 \item
   Calculate an integer
   $j = \left\lfloor \frac{k \cdot (Y - e_{\min})}
                          {e_{\max} - e_{\min} +1}
        \right\rfloor
   $%
   .
 \item
   Set $Y$ to $V_j$ and then set $V_j$ to $\tcode{e()}$.
\end{enumeratea}

\pnum
The generation algorithm%
\indextext{\idxcode{shuffle_order_engine}!generation algorithm}%
\indextext{generation algorithm!\idxcode{shuffle_order_engine}}
yields the last value of \tcode{Y}
 produced while advancing \tcode{e}'s state as described above.

\begin{codeblock}
template<class Engine, size_t k>
 class shuffle_order_engine
{
public:
 // types
 typedef typename Engine::result_type result_type;

 // engine characteristics
 static constexpr size_t table_size = k;
 static constexpr result_type min() { return Engine::min(); }
 static constexpr result_type max() { return Engine::max(); }

 // constructors and seeding functions
 shuffle_order_engine();
 explicit shuffle_order_engine(const Engine& e);
 explicit shuffle_order_engine(Engine&& e);
 explicit shuffle_order_engine(result_type s);
 template<class Sseq> explicit shuffle_order_engine(Sseq& q);
 void seed();
 void seed(result_type s);
 template<class Sseq> void seed(Sseq& q);

 // generating functions
 result_type operator()();
 void discard(unsigned long long z);

 // property functions
 const Engine& base() const noexcept { return e; };

private:
 Engine e;           // \expos
 result_type Y;      // \expos
 result_type V[k];   // \expos
};
\end{codeblock}

\pnum
The following relation shall hold:
  \tcode{0 < k}.

\pnum
The textual representation%
\indextext{\idxcode{shuffle_order_engine}!textual representation}%
\indextext{textual representation!\idxcode{shuffle_order_engine}}
consists of
 the textual representation of \tcode{e},
followed by
 the \tcode{k} values of $V$,
followed by
 the value of $Y$.

\pnum
In addition to its behavior
pursuant to section~\ref{rand.req.adapt},
each constructor%
\indexlibrary{\idxcode{shuffle_order_engine}!constructor}
that is not a copy constructor
initializes $\tcode{V[0]}, \ldots, \tcode{V[k-1]}$ and $Y$,
in that order,
with values returned by successive invocations of \tcode{e()}.%
\indextext{random number generation!engines|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Engines with predefined parameters section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\rSec2[rand.predef]{Engines and engine adaptors with predefined parameters}%
\indextext{random number engine!with predefined parameters|(}%
\indextext{random number engine adaptor!with predefined parameters|(}%
\indextext{random number generation!predefined engines and adaptors|(}

\indexlibrary{\idxcode{minstd_rand0}}%
\indextext{engines with predefined parameters!\idxcode{minstd_rand0}}%
\begin{itemdecl}
typedef linear_congruential_engine<uint_fast32_t, 16807, 0, 2147483647>
       minstd_rand0;
\end{itemdecl}

\begin{itemdescr}
\pnum\required
 The $10000^{\,\mathrm{th}}$ consecutive invocation
 of a default-constructed object
 of type \tcode{minstd_rand0}
 shall produce the value $1043618065$.
\end{itemdescr}

\indexlibrary{\idxcode{minstd_rand}}%
\indextext{engines with predefined parameters!\idxcode{minstd_rand}}%
\begin{itemdecl}
typedef linear_congruential_engine<uint_fast32_t, 48271, 0, 2147483647>
       minstd_rand;
\end{itemdecl}

\begin{itemdescr}
\pnum\required
 The $10000^{\,\mathrm{th}}$ consecutive invocation
 of a default-constructed object
 of type \tcode{minstd_rand}
 shall produce the value $399268537$.
\end{itemdescr}

\indexlibrary{\idxcode{mt19937}}%
\indextext{engines with predefined parameters!\idxcode{mt19937}}%
\begin{itemdecl}
typedef mersenne_twister_engine<uint_fast32_t,
       32,624,397,31,0x9908b0df,11,0xffffffff,7,0x9d2c5680,15,0xefc60000,18,1812433253>
       mt19937;
\end{itemdecl}

\begin{itemdescr}
\pnum\required
 The $10000^{\,\mathrm{th}}$ consecutive invocation
 of a default-constructed object
 of type \tcode{mt19937}
 shall produce the value $4123659995$.
\end{itemdescr}

\indexlibrary{\idxcode{mt19937_64}}%
\indextext{engines with predefined parameters!\idxcode{mt19937_64}}%
\begin{itemdecl}
typedef mersenne_twister_engine<uint_fast64_t,
       64,312,156,31,0xb5026f5aa96619e9,29,
       0x5555555555555555,17,
       0x71d67fffeda60000,37,
       0xfff7eee000000000,43,
       6364136223846793005>
       mt19937_64;
\end{itemdecl}

\begin{itemdescr}
\pnum\required
 The $10000^{\,\mathrm{th}}$ consecutive invocation
 of a default-constructed object
 of type \tcode{mt19937_64}
 shall produce the value $9981545732273789042$.
\end{itemdescr}

\indexlibrary{\idxcode{ranlux24_base}}%
\indextext{engines with predefined parameters!\idxcode{ranlux24_base}}%
\begin{itemdecl}
typedef subtract_with_carry_engine<uint_fast32_t, 24, 10, 24>
       ranlux24_base;
\end{itemdecl}

\begin{itemdescr}
\pnum\required
 The $10000^{\,\mathrm{th}}$ consecutive invocation
 of a default-constructed object
 of type \tcode{ranlux24_base}
 shall produce the value
 $ 7937952 $.
\end{itemdescr}

\indexlibrary{\idxcode{ranlux48_base}}%
\indextext{engines with predefined parameters!\idxcode{ranlux48_base}}%
\begin{itemdecl}
typedef subtract_with_carry_engine<uint_fast64_t, 48, 5, 12>
       ranlux48_base;
\end{itemdecl}

\begin{itemdescr}
\pnum\required
 The $10000^{\,\mathrm{th}}$ consecutive invocation
 of a default-constructed object
 of type \tcode{ranlux48_base}
 shall produce the value
 $ 61839128582725 $.
\end{itemdescr}

\indexlibrary{\idxcode{ranlux24}}%
\indextext{engines with predefined parameters!\idxcode{ranlux24}}%
\begin{itemdecl}
typedef discard_block_engine<ranlux24_base, 223, 23>
       ranlux24;
\end{itemdecl}

\begin{itemdescr}
\pnum\required
 The $10000^{\,\mathrm{th}}$ consecutive invocation
 of a default-constructed object
 of type \tcode{ranlux24}
 shall produce the value
 $ 9901578 $.
\end{itemdescr}

\indexlibrary{\idxcode{ranlux48}}%
\indextext{engines with predefined parameters!\idxcode{ranlux48}}%
\begin{itemdecl}
typedef discard_block_engine<ranlux48_base, 389, 11>
       ranlux48@
\end{itemdecl}

\begin{itemdescr}
\pnum\required
 The $10000^{\,\mathrm{th}}$ consecutive invocation
 of a default-constructed object
 of type \tcode{ranlux48}
 shall produce the value
 $ 249142670248501 $.
\end{itemdescr}

\indexlibrary{\idxcode{knuth_b}}%
\indextext{engines with predefined parameters!\idxcode{knuth_b}}%
\begin{itemdecl}
typedef shuffle_order_engine<minstd_rand0,256>
       knuth_b;
\end{itemdecl}

\begin{itemdescr}
\pnum\required
 The $10000^{\,\mathrm{th}}$ consecutive invocation
 of a default-constructed object
 of type \tcode{knuth_b}
 shall produce the value $1112339016$.
\end{itemdescr}%

\indexlibrary{\idxcode{default_random_engine}}%
\indextext{engines with predefined parameters!\idxcode{default_random_engine}}%
\begin{itemdecl}
typedef @\textit{implementation-defined}@
       default_random_engine;
\end{itemdecl}

\begin{itemdescr}
\pnum\note
The choice of engine type
named by this \tcode{typedef}
is implementation-defined.
\enternote
 The implementation
 may select this type
 on the basis of performance,
 size,
 quality,
 or any combination of such factors,
 so as to provide at least acceptable engine behavior
 for relatively casual, inexpert, and/or lightweight use.
 Because different implementations
 may select different underlying engine types,
 code that uses this \tcode{typedef}
 need not generate identical sequences across implementations.
\exitnote
\end{itemdescr}%
\indextext{random number generation!predefined engines and adaptors|)}%
\indextext{random number engine adaptor!with predefined parameters|)}%
\indextext{random number engine!with predefined parameters|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% random_device class section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\rSec2[rand.device]{Class \tcode{random_device}}%
\indexlibrary{\idxcode{random_device}}

\pnum
A \tcode{random_device}
uniform random number generator
produces non-deterministic random numbers.

\pnum
If implementation limitations%
\indextext{\idxcode{random_device}!implementation leeway}
prevent generating non-deterministic random numbers,
the implementation may employ a random number engine.

\begin{codeblock}
class random_device
{
public:
 // types
 typedef unsigned int result_type;

 // generator characteristics
 static constexpr result_type min() { return numeric_limits<result_type>::min(); }
 static constexpr result_type max() { return numeric_limits<result_type>::max(); }

 // constructors
 explicit random_device(const string& token = @\textit{implementation-defined}@);

 // generating functions
 result_type operator()();

 // property functions
 double entropy() const noexcept;

 @\textit{// no copy functions}@
 random_device(const random_device& ) = delete;
 void operator=(const random_device& ) = delete;
};
\end{codeblock}


\indexlibrary{\idxcode{random_device}!constructor}%
\begin{itemdecl}
explicit random_device(const string& token = @\textit{implementation-defined}@);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{random_device}
 non-deterministic uniform random number generator object.
 The semantics and default value of the \tcode{token}
 parameter are implementation-defined.\footnote{   The parameter is intended
   to allow an implementation to differentiate
   between different sources of randomness.
 }

\pnum
\throws A value of an implementation-defined type
 derived from \tcode{exception}
 if the \tcode{random_device} could not be initialized.
\end{itemdescr}

\indexlibrary{\idxcode{random_device}!\idxcode{entropy}}%
\indexlibrary{\idxcode{entropy}!\idxcode{random_device}}%
\begin{itemdecl}
double entropy() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns If the implementation employs a random number engine,
 returns $0.0$.
 Otherwise, returns an entropy estimate\footnote{If a device has $n$ states
   whose respective probabilities are
   $ P_0, \ldots, P_{n-1} $,
   the device entropy $S$ is defined as\\
   $ S = - \sum_{i=0}^{n-1} P_i \cdot \log P_i $.}
 for the random numbers returned by \tcode{operator()},
 in the range
   \tcode{min()}
 to
   $\log_2( \tcode{max()}+1)$.
\end{itemdescr}

\indexlibrary{\idxcode{random_device}!\idxcode{operator()}}%
\indexlibrary{\idxcode{operator()}!\idxcode{random_device}}%
\begin{itemdecl}
result_type operator()();
\end{itemdecl}

\begin{itemdescr}
\pnum\returns A non-deterministic random value,
 uniformly distributed
 between \tcode{min()} and \tcode{max()},
 inclusive.
 It is implementation-defined how these values are generated.

\pnum
\throws A value of an implementation-defined type
 derived from \tcode{exception}
 if a random number could not be obtained.
\end{itemdescr}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% utilities section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\rSec2[rand.util]{Utilities}%
\indextext{random number generation!utilities|(}%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% class seed_seq:

\rSec3[rand.util.seedseq]{Class \tcode{seed_seq}}%

\pnum
 No function described in this section~\ref{rand.util.seedseq}
 throws an exception.

\begin{codeblock}
class seed_seq
{
public:
 // types
 typedef uint_least32_t result_type;

 // constructors
 seed_seq();
 template<class T>
   seed_seq(initializer_list<T> il);
 template<class InputIterator>
   seed_seq(InputIterator begin, InputIterator end);

 // generating functions
 template<class RandomAccessIterator>
   void generate(RandomAccessIterator begin, RandomAccessIterator end);

 // property functions
 size_t size() const;
 template<class OutputIterator>
   void param(OutputIterator dest) const;

 // no copy functions
 seed_seq(const seed_seq& ) = delete;
 void operator=(const seed_seq& ) = delete;

private:
 vector<result_type> v;   // \expos
};
\end{codeblock}%


\indexlibrary{\idxcode{seed_seq}!constructor}%
\begin{itemdecl}
seed_seq();
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{seed_seq} object
 as if by default-constructing its member \tcode{v}.
\end{itemdescr}


\indexlibrary{\idxcode{seed_seq}!constructor}%
\begin{itemdecl}
template<class T>
 seed_seq(initializer_list<T> il);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires \tcode{T} shall be an integer type.

\pnum\effects
 Same as \tcode{seed_seq(il.begin(), il.end())}.
\end{itemdescr}


\indexlibrary{\idxcode{seed_seq}!constructor}%
\begin{itemdecl}
template<class InputIterator>
  seed_seq(InputIterator begin, InputIterator end);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
  \tcode{InputIterator} shall satisfy the requirements
  of an input iterator (Table~\ref{tab:iterator.input.requirements}) type.
  Moreover,
  \tcode{iterator_traits<InputIterator>::value_type}
  shall denote an integer type.

\pnum\effects Constructs a \tcode{seed_seq} object
 by the following algorithm:
\begin{codeblock}
for( InputIterator s = begin; s != end; ++s)
 v.push_back((*s)@$\bmod 2^{32}$@);
\end{codeblock}%
\end{itemdescr}

\indexlibrary{\idxcode{seed_seq}!\idxcode{generate}}%
\indexlibrary{\idxcode{generate}!\idxcode{seed_seq}}%
\begin{itemdecl}
template<class RandomAccessIterator>
  void generate(RandomAccessIterator begin, RandomAccessIterator end);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires \tcode{RandomAccessIterator}
  shall meet the requirements of a mutable random access iterator
  (Table~\ref{tab:iterator.random.access.requirements}) type.
  Moreover,
  \tcode{iterator_traits<RandomAccessIterator>::value_type}
  shall denote an unsigned integer type
  capable of accommodating 32-bit quantities.

\pnum\effects
 Does nothing if \tcode{begin == end}.
 Otherwise,
 with $ s = \tcode{v.size()} $
 and  $ n = \tcode{end} - \tcode{begin} $,
 fills the supplied range $[\tcode{begin},\tcode{end})$
 according to the following algorithm
 in which
 each operation is to be carried out modulo $2^{32}$,
 each indexing operator applied to \tcode{begin} is to be taken modulo $n$,
 and $T(x)$ is defined as $ x \, \xor \, (x \, \rightshift \, 27)$:

\begin{enumeratea}
 \item
   By way of initialization,
   set each element of the range to the value \tcode{0x8b8b8b8b}.
   Additionally,
   for use in subsequent steps,
   let $p = (n - t) / 2$
   and let $q = p + t$,
   where
   \[%
     t = (n \ge 623) \mbox{ ? } 11 \mbox{ : } (n \ge 68) \mbox{ ? } 7 \mbox{ : } (n \ge 39) \mbox{ ? } 5 \mbox{ : } (n \ge 7) \mbox{ ? } 3 \mbox{ : } (n - 1)/2;
   \]%
 \item
   With $m$ as the larger of $s + 1$ and $n$,
   transform the elements of the range:
   iteratively for $ k = 0, \ldots, m-1 $,
   calculate values
   \begin{eqnarray*}
     r_1 & = &
       1664525 \cdot \tcode{T}\left(     \tcode{begin[}k\tcode{]}
                                    \xor \tcode{begin[}k+p\tcode{]}
                                    \xor \tcode{begin[}k-1 \tcode{]}
                               \right)
     \\
     r_2 & = & r_1 + \left\{
       \begin{array}{cl}
         s                                  & \mbox{,  } k = 0
         \\
         k \bmod n + \tcode{v[}k-1\tcode{]} & \mbox{,  } 0 < k \le s
         \\
         k \bmod n                          & \mbox{,  } s < k
       \end{array}
     \right.
   \end{eqnarray*}
   and, in order,
   increment $\tcode{begin[}k+p\tcode{]}$ by $r_1$,
   increment $\tcode{begin[}k+q\tcode{]}$ by $r_2$,
   and
   set \tcode{begin[k]} to $r_2$.
 \item
   Transform the elements of the range again,
   beginning where the previous step ended:
   iteratively for $ k = m, \ldots, m\!+\!n\!-\!1 $,
   calculate values
   \begin{eqnarray*}
     r_3 & = &
       1566083941 \cdot \tcode{T}\left( \tcode{begin[}k  \tcode{]}
                                      + \tcode{begin[}k+p\tcode{]}
                                      + \tcode{begin[}k-1\tcode{]}
                                 \right)
     \\
     r_4 & = & r_3 - (k \bmod n)
   \end{eqnarray*}
   and, in order,
   \noindent
   update $\tcode{begin[}k+p\tcode{]}$ by xoring it with $r_3$,
   update $\tcode{begin[}k+q\tcode{]}$ by xoring it with $r_4$,
   and
   set $\tcode{begin[}k\tcode{]}$ to $r_4$.
\end{enumeratea}
\end{itemdescr}

\indexlibrary{\idxcode{seed_seq}!\idxcode{size}}%
\indexlibrary{\idxcode{size}!\idxcode{seed_seq}}%
\begin{itemdecl}
size_t size() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The number of 32-bit units
 that would be returned
 by a call to \tcode{param()}.

\pnum\complexity constant time.
\end{itemdescr}

\indexlibrary{\idxcode{seed_seq}!\idxcode{param}}%
\indexlibrary{\idxcode{param}!\idxcode{seed_seq}}%
\begin{itemdecl}
template<class OutputIterator>
  void param(OutputIterator dest) const;
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
  \tcode{OutputIterator} shall satisfy the requirements
  of an output iterator (Table~\ref{tab:iterator.output.requirements}) type.
  Moreover,
  the expression
  \tcode{*dest = rt}
  shall be valid for a value \tcode{rt} of type \tcode{result_type}.

\pnum\effects Copies the sequence of prepared 32-bit units
 to the given destination,
 as if by executing the following statement:
\begin{codeblock}
copy(v.begin(), v.end(), dest);
\end{codeblock}%
\end{itemdescr}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% generate_canonical function template:

\rSec3[rand.util.canonical]{Function template \tcode{generate_canonical}}%
\indexlibrary{\idxcode{generate_canonical}}%

\pnum
 Each function instantiated
 from the template
 described in this section~\ref{rand.util.canonical}
 maps the result of one or more invocations
 of a supplied uniform random number generator \tcode{g}
 to one member
 of the specified \tcode{RealType}
 such that,
 if the values $g_i$
 produced by \tcode{g}
 are uniformly distributed,
 the instantiation's results
 $t_j$, $ 0 \leq t_j < 1 $,
 are distributed as uniformly as possible
 as specified below.

\pnum
\enternote
 Obtaining a value in this way
 can be a useful step
 in the process of transforming
 a value generated by a uniform random number generator
 into a value
 that can be delivered by a random number distribution.
\exitnote

\indexlibrary{\idxcode{generate_canonical}}%
\begin{itemdecl}
template<class RealType, size_t bits, class URNG>
 RealType generate_canonical(URNG& g);
\end{itemdecl}

\begin{itemdescr}
\pnum\complexity Exactly
 $ k = \max(1, \left\lceil b / \log_2 R \right\rceil)$
 invocations
 of \tcode{g},
 where $b$\footnote{$b$ is introduced
   to avoid any attempt
   to produce more bits of randomness
   than can be held in \tcode{RealType}.}
   is the lesser of \tcode{numeric_limits<RealType>\colcol{}digits}
                and \tcode{bits},
 and
   $R$ is the value of $ \tcode{g.max()} - \tcode{g.min()} + 1 $.

\pnum\effects
 Invokes \tcode{g()} $k$ times
 to obtain values $ g_0, \ldots, g_{k-1} $, respectively.
 Calculates a quantity
 \[
   S = \sum_{i=0}^{k-1} (g_i - \tcode{g.min()})
                        \cdot R^i
 \]
 using arithmetic of type
 \tcode{RealType}.

\pnum\returns
 $ S / R^k $.

\pnum\throws What and when \tcode{g} throws.
\end{itemdescr}%
\indextext{random number generation!utilities|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Distribution class templates section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\rSec2[rand.dist]{Random number distribution class templates}%
\indextext{random number generation!distributions|(}

\rSec3[rand.dist.general]{In general}

\pnum
Each type instantiated
from a class template specified in this section~\ref{rand.dist}
satisfies the requirements
of a random number distribution~(\ref{rand.req.dist}) type.

\pnum
Descriptions are provided in this section~\ref{rand.dist}
only for distribution operations
that are not described in \ref{rand.req.dist}
or for operations where there is additional semantic information.
In particular,
declarations for copy constructors,
for copy assignment operators,
for streaming operators,
and for equality and inequality operators
are not shown in the synopses.

\pnum
The algorithms
for producing each
of the specified distributions
are implementation-defined.

\pnum
The value of each probability density function $p(z)$
and of each discrete probability function $P(z_i)$
specified in this section
is $0$
everywhere outside its stated domain.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Uniform distributions section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\rSec3[rand.dist.uni]{Uniform distributions}%
\indextext{uniform distributions|(}%
\indextext{random number distributions!uniform|(}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% uniform_int_distribution distribution:

\rSec4[rand.dist.uni.int]{Class template \tcode{uniform_int_distribution}}%
\indexlibrary{\idxcode{uniform_int_distribution}}%
\indextext{random number distribution!\idxcode{uniform_int_distribution}}

\pnum
A \tcode{uniform_int_distribution} random number distribution
produces random integers $i$,
$ a \leq i \leq b $,
distributed according to
the constant discrete probability function%
\indextext{discrete probability function!\idxcode{uniform_int_distribution}}%
\indextext{\idxcode{uniform_int_distribution}!discrete probability function}
\[%
 P(i\,|\,a,b) = 1 / (b - a + 1)
\; \mbox{.}
\]

\begin{codeblock}
template<class IntType = int>
 class uniform_int_distribution
{
public:
 // types
 typedef IntType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructors and reset functions
 explicit uniform_int_distribution(IntType a = 0, IntType b = numeric_limits<IntType>::max());
 explicit uniform_int_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 result_type a() const;
 result_type b() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{uniform_int_distribution}!constructor}%
\begin{itemdecl}
explicit uniform_int_distribution(IntType a = 0, IntType b = numeric_limits<IntType>::max());
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ \tcode{a} \leq \tcode{b} $.

\pnum\effects Constructs a \tcode{uniform_int_distribution} object;
 \tcode{a} and \tcode{b}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{uniform_int_distribution}!\idxcode{a}}%
\indexlibrary{\idxcode{a}!\idxcode{uniform_int_distribution}}%
\begin{itemdecl}
result_type a() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{a} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{uniform_int_distribution}!\idxcode{b}}%
\indexlibrary{\idxcode{b}!\idxcode{uniform_int_distribution}}%
\begin{itemdecl}
result_type b() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{b} parameter
 with which the object was constructed.
\end{itemdescr}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% uniform_real distribution:

\rSec4[rand.dist.uni.real]{Class template \tcode{uniform_real_distribution}}%
\indexlibrary{\idxcode{uniform_real_distribution}}%
\indextext{random number distribution!\idxcode{uniform_real_distribution}}

\pnum
A \tcode{uniform_real_distribution} random number distribution
produces random numbers $x$,
$ a \leq x < b $,
distributed according to
the constant probability density function%
\indextext{probability density function!\idxcode{uniform_real_distribution}}%
\indextext{\idxcode{uniform_real_distribution}!probability density function}
\[%
 p(x\,|\,a,b) = 1 / (b - a)
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class uniform_real_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructors and reset functions
 explicit uniform_real_distribution(RealType a = 0.0, RealType b = 1.0);
 explicit uniform_real_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 result_type a() const;
 result_type b() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{uniform_real_distribution}!constructor}%
\begin{itemdecl}
explicit uniform_real_distribution(RealType a = 0.0, RealType b = 1.0);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ \tcode{a} \leq \tcode{b} $
 and
 $ \tcode{b} - \tcode{a} \leq \tcode{numeric_limits<RealType>\colcol{}max()} $.

\pnum\effects Constructs a \tcode{uniform_real_distribution} object;
 \tcode{a} and \tcode{b}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{uniform_real_distribution}!\idxcode{a}}%
\indexlibrary{\idxcode{a}!\idxcode{uniform_real_distribution}}%
\begin{itemdecl}
result_type a() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{a} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{uniform_real_distribution}!\idxcode{b}}%
\indexlibrary{\idxcode{b}!\idxcode{uniform_real_distribution}}%
\begin{itemdecl}
result_type b() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{b} parameter
 with which the object was constructed.
\end{itemdescr}%
\indextext{random number distributions!uniform|)}%
\indextext{uniform distributions|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Bernoulli distributions section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\rSec3[rand.dist.bern]{Bernoulli distributions}%
\indextext{Bernoulli distributions|(}%
\indextext{random number distributions!Bernoulli|(}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% bernoulli_distribution

\rSec4[rand.dist.bern.bernoulli]{Class \tcode{bernoulli_distribution}}%
\indexlibrary{\idxcode{bernoulli_distribution}}%
\indextext{random number distribution!\idxcode{bernoulli_distribution}}

\pnum
A \tcode{bernoulli_distribution} random number distribution
produces \tcode{bool} values $b$
distributed according to
the discrete probability function
\indextext{discrete probability function!\idxcode{bernoulli_distribution}}%
\indextext{\idxcode{bernoulli_distribution}!discrete probability function}
\[%
 P(b\,|\,p)
      = \left\{ \begin{array}{lcl}
          p    &  \mbox{if} & b = \tcode{true} \\
          1-p  &  \mbox{if} & b = \tcode{false}
        \end{array}\right.
\; \mbox{.}
\]

\begin{codeblock}
class bernoulli_distribution
{
public:
 // types
 typedef bool result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructors and reset functions
 explicit bernoulli_distribution(double p = 0.5);
 explicit bernoulli_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 double p() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{bernoulli_distribution}!constructor}%
\begin{itemdecl}
explicit bernoulli_distribution(double p = 0.5);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $0 \leq \tcode{p} \leq 1$.

\pnum\effects Constructs a \tcode{bernoulli_distribution} object;
 \tcode{p}
 corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{bernoulli_distribution}!\idxcode{p}}%
\indexlibrary{\idxcode{p}!\idxcode{bernoulli_distribution}}%
\begin{itemdecl}
double p() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{p} parameter
 with which the object was constructed.
\end{itemdescr}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% binomial_distribution

\rSec4[rand.dist.bern.bin]{Class template \tcode{binomial_distribution}}%
\indexlibrary{\idxcode{binomial_distribution}}%
\indextext{random number distribution!\idxcode{binomial_distribution}}

\pnum
A \tcode{binomial_distribution} random number distribution
produces integer values $i \geq 0$
distributed according to
the discrete probability function%
\indextext{discrete probability function!\idxcode{binomial_distribution}}%
\indextext{\idxcode{binomial_distribution}!discrete probability function}
\[%
 P(i\,|\,t,p)
      = {t \choose i} \cdot p^i \cdot (1-p)^{t-i}
\; \mbox{.}
\]

\begin{codeblock}
template<class IntType = int>
 class binomial_distribution
{
public:
 // types
 typedef IntType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructors and reset functions
 explicit binomial_distribution(IntType t = 1, double p = 0.5);
 explicit binomial_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 IntType t() const;
 double p() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{binomial_distribution}!constructor}%
\begin{itemdecl}
explicit binomial_distribution(IntType t = 1, double p = 0.5);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $0 \leq \tcode{p} \leq 1$ and $0 \leq \tcode{t} $.

\pnum\effects Constructs a \tcode{binomial_distribution} object;
 \tcode{t} and \tcode{p}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{binomial_distribution}!\idxcode{t}}%
\indexlibrary{\idxcode{t}!\idxcode{binomial_distribution}}%
\begin{itemdecl}
IntType t() const;
\end{itemdecl}%
\begin{itemdescr}
\pnum\returns The value of the \tcode{t} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{binomial_distribution}!\idxcode{p}}%
\indexlibrary{\idxcode{p}!\idxcode{binomial_distribution}}%
\begin{itemdecl}
double p() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{p} parameter
 with which the object was constructed.
\end{itemdescr}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% geometric_distribution

\rSec4[rand.dist.bern.geo]{Class template \tcode{geometric_distribution}}
\indexlibrary{\idxcode{geometric_distribution}}
\indextext{random number distribution!\idxcode{geometric_distribution}}

\pnum
A \tcode{geometric_distribution} random number distribution
produces integer values $i \geq 0$
distributed according to
the discrete probability function
\indextext{discrete probability function!\idxcode{geometric_distribution}}%
\indextext{\idxcode{geometric_distribution}!discrete probability function}
\[%
 P(i\,|\,p)
      = p \cdot (1-p)^{i}
\; \mbox{.}
\]

\begin{codeblock}
template<class IntType = int>
 class geometric_distribution
{
public:
 // types
 typedef IntType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructors and reset functions
 explicit geometric_distribution(double p = 0.5);
 explicit geometric_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 double p() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
 };
\end{codeblock}


\indexlibrary{\idxcode{geometric_distribution}!constructor}%
\begin{itemdecl}
explicit geometric_distribution(double p = 0.5);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $0 < \tcode{p} < 1$.

\pnum\effects Constructs a \tcode{geometric_distribution} object;
 \tcode{p}
 corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{geometric_distribution}!\idxcode{p}}%
\indexlibrary{\idxcode{p}!\idxcode{geometric_distribution}}%
\begin{itemdecl}
double p() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{p} parameter
 with which the object was constructed.
\end{itemdescr}

% ----------------------------------------------------------------------
% Class template negative_binomial_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.bern.negbin]{Class template \tcode{negative_binomial_distribution}}
\indexlibrary{\idxcode{negative_binomial_distribution}}
\indextext{random number distribution!\idxcode{negative_binomial_distribution}}

\pnum
A \tcode{negative_binomial_distribution} random number distribution
produces random integers $i \geq 0$
distributed according to
the discrete probability function
\indextext{discrete probability function!\idxcode{negative_binomial_distribution}}%
\indextext{\idxcode{negative_binomial_distribution}!discrete probability function}
\[%
 P(i\,|\,k,p)
      = {k+i-1 \choose i} \cdot p^k \cdot (1-p)^i
\; \mbox{.}
\]

\begin{codeblock}
template<class IntType = int>
 class negative_binomial_distribution
{
public:
 // types
 typedef IntType  result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 explicit negative_binomial_distribution(IntType k = 1, double p = 0.5);
 explicit negative_binomial_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 IntType k() const;
 double p() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{negative_binomial_distribution}!constructor}%
\begin{itemdecl}
explicit negative_binomial_distribution(IntType k = 1, double p = 0.5);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $0 < \tcode{p} \leq 1$
 and $0 < \tcode{k} $.

\pnum\effects Constructs a \tcode{negative_binomial_distribution} object;
 \tcode{k} and \tcode{p}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{negative_binomial_distribution}!\idxcode{t}}%
\indexlibrary{\idxcode{t}!\idxcode{negative_binomial_distribution}}%
\begin{itemdecl}
IntType k() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{k} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{negative_binomial_distribution}!\idxcode{p}}%
\indexlibrary{\idxcode{p}!\idxcode{negative_binomial_distribution}}%
\begin{itemdecl}
double p() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{p} parameter
 with which the object was constructed.
\end{itemdescr}%
\indextext{random number distributions!Bernoulli|)}%
\indextext{Bernoulli distributions|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Poisson distributions section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\rSec3[rand.dist.pois]{Poisson distributions}%
\indextext{Poisson distributions|(}%
\indextext{random number distributions!Poisson|(}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% poisson_distribution

\rSec4[rand.dist.pois.poisson]{Class template \tcode{poisson_distribution}}%
\indexlibrary{\idxcode{poisson_distribution}}%
\indextext{random number distribution!\idxcode{poisson_distribution}}

\pnum
A \tcode{poisson_distribution} random number distribution
produces integer values $ i \geq 0 $
distributed according to
the discrete probability function
\indextext{discrete probability function!\idxcode{poisson_distribution}}%
\indextext{\idxcode{poisson_distribution}!discrete probability function}
\[%
 P(i\,|\,\mu)
      = \frac{ e^{-\mu} \mu^{i} }
             { i\,! }
\; \mbox{.}
\]
The distribution parameter $\mu$
is also known as this distribution's \techterm{mean}%
\indextext{mean!\idxcode{poisson_distribution}}%
\indextext{\idxcode{poisson_distribution}!mean}%
.

\begin{codeblock}
template<class IntType = int>
 class poisson_distribution
{
public:
 // types
 typedef IntType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructors and reset functions
 explicit poisson_distribution(double mean = 1.0);
 explicit poisson_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 double mean() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}



\indexlibrary{\idxcode{poisson_distribution}!constructor}%
\begin{itemdecl}
explicit poisson_distribution(double mean = 1.0);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{mean} $.

\pnum\effects Constructs a \tcode{poisson_distribution} object;
 \tcode{mean}
 corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{poisson_distribution}!\idxcode{mean}}%
\indexlibrary{\idxcode{mean}!\idxcode{poisson_distribution}}%
\begin{itemdecl}
double mean() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{mean} parameter
 with which the object was constructed.
\end{itemdescr}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% exponential_distribution

\rSec4[rand.dist.pois.exp]{Class template \tcode{exponential_distribution}}%
\indexlibrary{\idxcode{exponential_distribution}}%
\indextext{random number distribution!\idxcode{exponential_distribution}}

\pnum
An \tcode{exponential_distribution} random number distribution
produces random numbers $x > 0$
distributed according to
the probability density function%
\indextext{probability density function!\idxcode{exponential_distribution}}%
\indextext{\idxcode{exponential_distribution}!probability density function}
\[%
 p(x\,|\,\lambda)
      = \lambda e^{-\lambda x}
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class exponential_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructors and reset functions
 explicit exponential_distribution(RealType lambda = 1.0);
 explicit exponential_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 RealType lambda() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{exponential_distribution}!constructor}%
\begin{itemdecl}
explicit exponential_distribution(RealType lambda = 1.0);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{lambda} $.

\pnum\effects Constructs a \tcode{exponential_distribution} object;
 \tcode{lambda}
 corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{exponential_distribution}!\idxcode{lambda}}%
\indexlibrary{\idxcode{lambda}!\idxcode{exponential_distribution}}%
\begin{itemdecl}
RealType lambda() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{lambda} parameter
 with which the object was constructed.
\end{itemdescr}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% gamma_distribution

\rSec4[rand.dist.pois.gamma]{Class template \tcode{gamma_distribution}}%
\indexlibrary{\idxcode{gamma_distribution}}%
\indextext{random number distribution!\idxcode{gamma_distribution}}

\pnum
A \tcode{gamma_distribution} random number distribution
produces random numbers $x > 0$
distributed according to
the probability density function%
\indextext{probability density function!\idxcode{gamma_distribution}}%
\indextext{\idxcode{gamma_distribution}!probability density function}
\[%
 p(x\,|\,\alpha,\beta)
      = {     e^{-x/\beta}
        \over {\beta^{\alpha} \cdot \Gamma(\alpha)}
        }
        \, \cdot \, x^{\, \alpha-1}
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class gamma_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructors and reset functions
 explicit gamma_distribution(RealType alpha = 1.0, RealType beta = 1.0);
 explicit gamma_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 RealType alpha() const;
 RealType beta() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{gamma_distribution}!constructor}%
\begin{itemdecl}
explicit gamma_distribution(RealType alpha = 1.0, RealType beta = 1.0);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{alpha} $
 and $ 0 < \tcode{beta} $.

\pnum\effects Constructs a \tcode{gamma_distribution} object;
 \tcode{alpha} and \tcode{beta}
 correspond to the parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{gamma_distribution}!\idxcode{alpha}}%
\indexlibrary{\idxcode{alpha}!\idxcode{gamma_distribution}}%
\begin{itemdecl}
RealType alpha() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{alpha} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{gamma_distribution}!\idxcode{beta}}%
\indexlibrary{\idxcode{beta}!\idxcode{gamma_distribution}}%
\begin{itemdecl}
RealType beta() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{beta} parameter
 with which the object was constructed.
\end{itemdescr}

% ----------------------------------------------------------------------
% Class template weibull_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.pois.weibull]{Class template \tcode{weibull_distribution}}%
\indexlibrary{\idxcode{weibull_distribution}}

\pnum
A \tcode{weibull_distribution} random number distribution
produces random numbers $x \geq 0$
distributed according to
the probability density function%
\indextext{probability density function!\idxcode{weibull_distribution}}%
\indextext{\idxcode{weibull_distribution}!probability density function}
\[%
 p(x\,|\,a,b)
      =       \frac{a}{b}
        \cdot \left(\frac{x}{b}\right)^{a-1}
        \cdot \, \exp\left( -\left(\frac{x}{b}\right)^a\right)
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class weibull_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 explicit weibull_distribution(RealType a = 1.0, RealType b = 1.0)
 explicit weibull_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 RealType a() const;
 RealType b() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}

\indexlibrary{\idxcode{weibull_distribution}!constructor}%
\begin{itemdecl}
explicit weibull_distribution(RealType a = 1.0, RealType b = 1.0);
\end{itemdecl}%

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{a} $ and  $ 0 < \tcode{b} $.

\pnum\effects Constructs a \tcode{weibull_distribution} object;
 \tcode{a} and \tcode{b}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{weibull_distribution}!\idxcode{a}}%
\indexlibrary{\idxcode{a}!\idxcode{weibull_distribution}}%
\begin{itemdecl}
RealType a() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{a} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{weibull_distribution}!\idxcode{b}}%
\indexlibrary{\idxcode{b}!\idxcode{weibull_distribution}}%
\begin{itemdecl}
RealType b() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{b} parameter
 with which the object was constructed.
\end{itemdescr}

% ----------------------------------------------------------------------
% Class template extreme_value_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.pois.extreme]{Class template \tcode{extreme_value_distribution}}
\indexlibrary{\idxcode{extreme_value_distribution}}
\indextext{random number distribution!\idxcode{extreme_value_distribution}}

\pnum
An \tcode{extreme_value_distribution} random number distribution
produces random numbers $x$
distributed according to
the probability density function\footnote{The distribution corresponding to
 this probability density function
 is also known
 (with a possible change of variable)
 as the Gumbel Type I,
 the log-Weibull,
 or the Fisher-Tippett Type I
 distribution.}%
\indextext{probability density function!\idxcode{extreme_value_distribution}}%
\indextext{\idxcode{extreme_value_distribution}!probability density function}
\[%
 p(x\,|\,a,b)
      =       \frac{1}{b}
        \cdot \exp\left(  \frac{a-x}{b}
                       \,-\, \exp\left(\frac{a-x}{b}\right)
                  \right)
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class extreme_value_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 explicit extreme_value_distribution(RealType a = 0.0, RealType b = 1.0);
 explicit extreme_value_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 RealType a() const;
 RealType b() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{extreme_value_distribution}!constructor}%
\begin{itemdecl}
explicit extreme_value_distribution(RealType a = 0.0, RealType b = 1.0);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{b} $.

\pnum\effects Constructs an \tcode{extreme_value_distribution} object;
 \tcode{a} and \tcode{b}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{extreme_value_distribution}!\idxcode{a}}%
\indexlibrary{\idxcode{a}!\idxcode{extreme_value_distribution}}%
\begin{itemdecl}
RealType a() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{a} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{extreme_value_distribution}!\idxcode{b}}%
\indexlibrary{\idxcode{b}!\idxcode{extreme_value_distribution}}%
\begin{itemdecl}
RealType b() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{b} parameter
 with which the object was constructed.
\end{itemdescr}%
\indextext{random number distributions!Poisson|)}%
\indextext{Poisson distributions|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Normal distributions section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\rSec3[rand.dist.norm]{Normal distributions}%
\indextext{normal distributions|(}%
\indextext{random number distributions!normal|(}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% normal_distribution

\rSec4[rand.dist.norm.normal]{Class template \tcode{normal_distribution}}%
\indexlibrary{\idxcode{normal_distribution}}%
\indextext{random number distribution!\idxcode{normal_distribution}}

\pnum
A \tcode{normal_distribution} random number distribution
produces random numbers $x$
distributed according to
the probability density function%
\indextext{probability density function!\idxcode{normal_distribution}}%
\indextext{\idxcode{normal_distribution}!probability density function}
\[%
 p(x\,|\,\mu,\sigma)
      = {1 \over \sigma \sqrt{2\pi}}
        \cdot
        % e^{-(x-\mu)^2 / (2\sigma^2)}
        \exp{\left(- \, \frac{(x - \mu)^2}
                             {2 \sigma^2}
             \right)
            }
\; \mbox{.}
\]
The distribution parameters $\mu$ and $\sigma$
are also known as this distribution's \techterm{mean}%
\indextext{mean!\idxcode{normal_distribution}}%
\indextext{\idxcode{normal_distribution}!mean}
and \techterm{standard deviation}%
\indextext{standard deviation!\idxcode{normal_distribution}}%
\indextext{\idxcode{normal_distribution}!standard deviation}%
.

\begin{codeblock}
template<class RealType = double>
 class normal_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructors and reset functions
 explicit normal_distribution(RealType mean = 0.0, RealType stddev = 1.0);
 explicit normal_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 RealType mean() const;
 RealType stddev() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{normal_distribution}!constructor}%
\begin{itemdecl}
explicit normal_distribution(RealType mean = 0.0, RealType stddev = 1.0);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{stddev} $.

\pnum\effects Constructs a \tcode{normal_distribution} object;
 \tcode{mean} and \tcode{stddev}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{normal_distribution}!\idxcode{mean}}%
\indexlibrary{\idxcode{mean}!\idxcode{normal_distribution}}%
\begin{itemdecl}
RealType mean() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{mean} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{normal_distribution}!\idxcode{stddev}}%
\indexlibrary{\idxcode{stddev}!\idxcode{normal_distribution}}%
\begin{itemdecl}
RealType stddev() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{stddev} parameter
 with which the object was constructed.
\end{itemdescr}

% ----------------------------------------------------------------------
% Class template lognormal_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.norm.lognormal]{Class template \tcode{lognormal_distribution}}%
\indexlibrary{\idxcode{lognormal_distribution}}%
\indextext{random number distribution!\idxcode{lognormal_distribution}}

\pnum
A \tcode{lognormal_distribution} random number distribution
produces random numbers $ x > 0 $
distributed according to
the probability density function%
\indextext{probability density function!\idxcode{lognormal_distribution}}%
\indextext{\idxcode{lognormal_distribution}!probability density function}
\[%
 p(x\,|\,m,s)
      = \frac{1}
             {s x \sqrt{2 \pi}}
        \cdot
        \exp{\left(- \, \frac{(\ln{x} - m)^2}
                             {2 s^2}
             \right)
            }
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class lognormal_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 explicit lognormal_distribution(RealType m = 0.0, RealType s = 1.0);
 explicit lognormal_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 RealType m() const;
 RealType s() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{lognormal_distribution}!constructor}%
\begin{itemdecl}
explicit lognormal_distribution(RealType m = 0.0, RealType s = 1.0);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{s} $.

\pnum\effects Constructs a \tcode{lognormal_distribution} object;
 \tcode{m} and \tcode{s}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{lognormal_distribution}!\idxcode{m}}%
\indexlibrary{\idxcode{m}!\idxcode{lognormal_distribution}}%
\begin{itemdecl}
RealType m() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{m} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{lognormal_distribution}!\idxcode{s}}%
\indexlibrary{\idxcode{s}!\idxcode{lognormal_distribution}}%
\begin{itemdecl}
RealType s() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{s} parameter
 with which the object was constructed.
\end{itemdescr}

% ----------------------------------------------------------------------
% Class template chi_squared_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.norm.chisq]{Class template \tcode{chi_squared_distribution}}%
\indexlibrary{\idxcode{chi_squared_distribution}}%
\indextext{random number distribution!\idxcode{chi_squared_distribution}}

\pnum
A \tcode{chi_squared_distribution} random number distribution
produces random numbers $x>0$
distributed according to
the probability density function%
\indextext{probability density function!\idxcode{chi_squared_distribution}}%
\indextext{\idxcode{chi_squared_distribution}!probability density function}
\[%
 p(x\,|\,n)
      =  \frac{ x^{(n/2)-1} \cdot e^{-x/2}}
              {\Gamma(n/2) \cdot 2^{n/2}}
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class chi_squared_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 explicit chi_squared_distribution(RealType n = 1);
 explicit chi_squared_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 RealType n() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{chi_squared_distribution}!constructor}%
\begin{itemdecl}
explicit chi_squared_distribution(RealType n = 1);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{n} $.

\pnum\effects Constructs a \tcode{chi_squared_distribution} object;
 \tcode{n}
 corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{chi_squared_distribution}!\idxcode{n}}%
\indexlibrary{\idxcode{n}!\idxcode{chi_squared_distribution}}%
\begin{itemdecl}
RealType n() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{n} parameter
 with which the object was constructed.
\end{itemdescr}

% ----------------------------------------------------------------------
% Class template cauchy_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.norm.cauchy]{Class template \tcode{cauchy_distribution}}%
\indexlibrary{\idxcode{cauchy_distribution}}

\pnum
A \tcode{cauchy_distribution} random number distribution
produces random numbers $x$
distributed according to
the probability density function%
\indextext{probability density function!\idxcode{cauchy_distribution}}%
\indextext{\idxcode{cauchy_distribution}!probability density function}
\[%
 p(x\,|\,a,b)
      = \left( \pi b \left( 1 + \left( \frac{x-a}{b}  \right)^2 \;\right)\right)^{-1}
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class cauchy_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 explicit cauchy_distribution(RealType a = 0.0, RealType b = 1.0);
 explicit cauchy_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 RealType a() const;
 RealType b() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{cauchy_distribution}!constructor}%
\begin{itemdecl}
explicit cauchy_distribution(RealType a = 0.0, RealType b = 1.0);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{b} $.

\pnum\effects Constructs a \tcode{cauchy_distribution} object;
 \tcode{a} and \tcode{b}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{cauchy_distribution}!\idxcode{a}}%
\indexlibrary{\idxcode{a}!\idxcode{cauchy_distribution}}%
\begin{itemdecl}
RealType a() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{a} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{cauchy_distribution}!\idxcode{b}}%
\indexlibrary{\idxcode{b}!\idxcode{cauchy_distribution}}%
\begin{itemdecl}
RealType b() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{b} parameter
 with which the object was constructed.
\end{itemdescr}

% ----------------------------------------------------------------------
% Class template fisher_f_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.norm.f]{Class template \tcode{fisher_f_distribution}}%
\indexlibrary{\idxcode{fisher_f_distribution}}%
\indextext{random number distribution!\idxcode{fisher_f_distribution}}

\pnum
A \tcode{fisher_f_distribution} random number distribution
produces random numbers $x\ge0$
distributed according to
the probability density function%
\indextext{probability density function!\idxcode{fisher_f_distribution}}%
\indextext{\idxcode{fisher_f_distribution}!probability density function}
\[%
 p(x\,|\,m,n)
      = \frac{\Gamma\big((m+n)/2\big)}
             {\Gamma(m/2) \; \Gamma(n/2)}
        \cdot
        \left(\frac{m}{n}\right)^{m/2}
        \cdot
        x^{(m/2)-1}
        \cdot
        {\left( 1 + \frac{m x}{n}  \right)}^{-(m+n)/2}
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class fisher_f_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 explicit fisher_f_distribution(RealType m = 1, RealType n = 1);
 explicit fisher_f_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 RealType m() const;
 RealType n() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{fisher_f_distribution}!constructor}%
\begin{itemdecl}
explicit fisher_f_distribution(RealType m = 1, RealType n = 1);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{m} $ and $ 0 < \tcode{n} $.

\pnum\effects Constructs a \tcode{fisher_f_distribution} object;
 \tcode{m} and \tcode{n}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{fisher_f_distribution}!\idxcode{m}}%
\indexlibrary{\idxcode{m}!\idxcode{fisher_f_distribution}}%
\begin{itemdecl}
RealType m() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{m} parameter
 with which the object was constructed.
\end{itemdescr}

\indexlibrary{\idxcode{fisher_f_distribution}!\idxcode{n}}%
\indexlibrary{\idxcode{n}!\idxcode{fisher_f_distribution}}%
\begin{itemdecl}
RealType n() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{n} parameter
 with which the object was constructed.
\end{itemdescr}

% ----------------------------------------------------------------------
% Class template student_t_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.norm.t]{Class template \tcode{student_t_distribution}}%
\indexlibrary{\idxcode{student_t_distribution}}%
\indextext{random number distribution!\idxcode{student_t_distribution}}

\pnum
A \tcode{student_t_distribution} random number distribution
produces random numbers $x$
distributed according to
the probability density function%
\indextext{probability density function!\idxcode{student_t_distribution}}%
\indextext{\idxcode{student_t_distribution}!probability density function}
\[%
 p(x\,|\,n)
      =  \frac{1}
              {\sqrt{n \pi}}
         \cdot \frac{\Gamma\big((n+1)/2\big)}
                    {\Gamma(n/2)}
         \cdot \left( 1+\frac{x^2}{n} \right) ^ {-(n+1)/2}
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class student_t_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 explicit student_t_distribution(RealType n = 1);
 explicit student_t_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 RealType n() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{student_t_distribution}!constructor}%
\begin{itemdecl}
explicit student_t_distribution(RealType n = 1);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 $ 0 < \tcode{n} $.

\pnum\effects Constructs a \tcode{student_t_distribution} object;
 \tcode{n} corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrary{\idxcode{student_t_distribution}!\idxcode{mean}}%
\indexlibrary{\idxcode{mean}!\idxcode{student_t_distribution}}%
\begin{itemdecl}
RealType n() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns The value of the \tcode{n} parameter
 with which the object was constructed.
\end{itemdescr}%
\indextext{random number distributions!normal|)}%
\indextext{normal distributions|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Sampling distributions section
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\rSec3[rand.dist.samp]{Sampling distributions}%
\indextext{sampling distributions|(}%
\indextext{random number distributions!sampling|(}


% ----------------------------------------------------------------------
% Class template discrete_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.samp.discrete]{Class template \tcode{discrete_distribution}}%
\indexlibrary{\idxcode{discrete_distribution}}%
\indextext{random number distribution!\idxcode{discrete_distribution}}

\pnum
A \tcode{discrete_distribution} random number distribution
produces random integers $i$, $0 \leq i < n$,
distributed according to
the discrete probability function%
\indextext{discrete probability function!\idxcode{discrete_distribution}}%
\indextext{\idxcode{discrete_distribution}!discrete probability function}
\[%
 P(i\,|\,p_0,\ldots,p_{n-1})
      = p_i
\; \mbox{.}
\]

\pnum
Unless specified otherwise,
the distribution parameters are calculated as:
 $p_k = {w_k / S} \; \mbox{  for } k = 0, \ldots, n\!-\!1$ ,
in which
the values $w_k$,
commonly known as the \techterm{weights}%
\indextext{\idxcode{discrete_distribution}!weights}%
\indextext{weights!\idxcode{discrete_distribution}}%
, shall be non-negative, non-NaN, and non-infinity.
Moreover, the following relation shall hold:
 $ 0 < S = w_0 + \cdots + w_{n-1} $.

\begin{codeblock}
template<class IntType = int>
 class discrete_distribution
{
public:
 // types
 typedef IntType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 discrete_distribution();
 template<class InputIterator>
   discrete_distribution(InputIterator firstW, InputIterator lastW);
 discrete_distribution(initializer_list<double> wl);
 template<class UnaryOperation>
   discrete_distribution(size_t nw, double xmin, double xmax, UnaryOperation fw);
 explicit discrete_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 vector<double> probabilities() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}

\indexlibrary{\idxcode{discrete_distribution}!constructor}
\begin{itemdecl}
discrete_distribution();
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{discrete_distribution} object
 with $ n = 1 $
 and $ p_0 = 1 $.
 \enternote
   Such an object will always deliver the value $0$.
 \exitnote
\end{itemdescr}


\indexlibrary{\idxcode{discrete_distribution}!constructor}%
\begin{itemdecl}
template<class InputIterator>
  discrete_distribution(InputIterator firstW, InputIterator lastW);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
  \tcode{InputIterator} shall satisfy the requirements
  of an input iterator (Table~\ref{tab:iterator.input.requirements}) type.
  Moreover,
  \tcode{iterator_traits<InputIterator>::value_type}
  shall denote a type that is convertible to \tcode{double}.
 If \tcode{firstW == lastW},
 let $ n = 1 $
 and $ w_0 = 1 $.
 Otherwise,
 $\bigl[\tcode{firstW}, \tcode{lastW}\bigr)$
 shall form a sequence $w$ of length $n > 0$.

\pnum\effects Constructs a \tcode{discrete_distribution} object
 with probabilities given by the formula above.
\end{itemdescr}


\indexlibrary{\idxcode{discrete_distribution}!constructor}%
\begin{itemdecl}
discrete_distribution(initializer_list<double> wl);
\end{itemdecl}

\begin{itemdescr}
\pnum\effects
 Same as \tcode{discrete_distribution(wl.begin(), wl.end())}.
\end{itemdescr}

\indexlibrary{\idxcode{discrete_distribution}!constructor}
\begin{itemdecl}
template<class UnaryOperation>
  discrete_distribution(size_t nw, double xmin, double xmax, UnaryOperation fw);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 Each instance of type \tcode{UnaryOperation}
 shall be a function object~(\ref{function.objects})
 whose return type shall be convertible to \tcode{double}.
 Moreover,
 \tcode{double} shall be convertible
 to the type of \tcode{UnaryOperation}'s sole parameter.
 If $ \tcode{nw} = 0 $, let $ n = 1 $, otherwise let $n = \tcode{nw}$.
 The relation
   $ 0 < \delta = (\tcode{xmax} - \tcode{xmin}) / n $
 shall hold.

\pnum\effects Constructs a \tcode{discrete_distribution} object
 with probabilities given by the formula above,
 using the following values:
 If $\tcode{nw} = 0$,
 let $ w_0 = 1 $.
 Otherwise,
 let $ w_k = \tcode{fw}(\tcode{xmin} + k \cdot \delta + \delta / 2) $
 for $ k = 0, \ldots, n\!-\!1 $.

\pnum\complexity
 The number of invocations of \tcode{fw} shall not exceed $n$.
\end{itemdescr}

\indexlibrary{\idxcode{discrete_distribution}!\idxcode{probabilities}}%
\indexlibrary{\idxcode{probabilities}!\idxcode{discrete_distribution}}%
\begin{itemdecl}
vector<double> probabilities() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns A \tcode{vector<double>}
 whose \tcode{size} member returns $n$
 and whose $ \tcode{operator[]} $ member returns $p_k$
 when invoked with argument $k$ for $k = 0, \ldots, n\!-\!1 $.
\end{itemdescr}


% ----------------------------------------------------------------------
% Class template piecewise_constant_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.samp.pconst]{Class template \tcode{piecewise_constant_distribution}}%
\indexlibrary{\idxcode{piecewise_constant_distribution}}%
\indextext{random number distribution!\idxcode{piecewise_constant_distribution}}

\pnum
A \tcode{piecewise_constant_distribution} random number distribution
produces random numbers $x$,
$ b_0 \leq x < b_n $,
uniformly distributed over each subinterval
$ [ b_i, b_{i+1} ) $
according to the probability density function
\indextext{probability density function!\idxcode{piecewise_constant_distribution}}%
\indextext{\idxcode{piecewise_constant_distribution}!probability density function}
\[%
 p(x\,|\,b_0,\ldots,b_n,\;\rho_0,\ldots,\rho_{n-1})
      = \rho_i
\; \mbox{,}
\mbox{ for } b_i \le x < b_{i+1}
\; \mbox{.}
\]

\pnum
The $n+1$ distribution parameters $b_i$,
also known as this distribution's \techterm{interval boundaries}%
\indextext{\idxcode{piecewise_constant_distribution}!interval boundaries}%
\indextext{interval boundaries!\idxcode{piecewise_constant_distribution}}%
, shall satisfy the relation
 $ b_i < b_{i+1} $
for $i = 0, \ldots, n\!-\!1 $.
Unless specified otherwise,
the remaining $n$ distribution parameters are calculated as:
\[%
 \rho_k = \;
   {w_k \over {S \cdot (b_{k+1}-b_k)}}
   \; \mbox{ for } k = 0, \ldots, n\!-\!1,
\]
in which the values $w_k$,
commonly known as the \techterm{weights}%
\indextext{\idxcode{piecewise_constant_distribution}!weights}%
\indextext{weights!\idxcode{piecewise_constant_distribution}}%
, shall be non-negative, non-NaN, and non-infinity.
Moreover, the following relation shall hold:
 $ 0 < S = w_0 + \cdots + w_{n-1} $.

\begin{codeblock}
template<class RealType = double>
 class piecewise_constant_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 piecewise_constant_distribution();
 template<class InputIteratorB, class InputIteratorW>
   piecewise_constant_distribution(InputIteratorB firstB, InputIteratorB lastB,
                                   InputIteratorW firstW);
 template<class UnaryOperation>
   piecewise_constant_distribution(initializer_list<RealType> bl, UnaryOperation fw);
 template<class UnaryOperation>
   piecewise_constant_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);
 explicit piecewise_constant_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 vector<result_type> intervals() const;
 vector<result_type> densities() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}


\indexlibrary{\idxcode{piecewise_constant_distribution}!constructor}%
\begin{itemdecl}
piecewise_constant_distribution();
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{piecewise_constant_distribution} object
 with $ n = 1 $,
 $\rho_0 = 1 $,
 $ b_0 = 0 $,
 and $ b_1 = 1 $.
\end{itemdescr}


\indexlibrary{\idxcode{piecewise_constant_distribution}!constructor}%
\begin{itemdecl}
template<class InputIteratorB, class InputIteratorW>
 piecewise_constant_distribution(InputIteratorB firstB, InputIteratorB lastB,
                                 InputIteratorW firstW);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
  \tcode{InputIteratorB} and \tcode{InputIteratorW}
  shall each satisfy the requirements
  of an input iterator (Table~\ref{tab:iterator.input.requirements}) type.
  Moreover,
  \tcode{iterator_traits<InputIteratorB>::value_type} and
  \tcode{iterator_traits<InputIteratorW>::value_type}
  shall each denote a type that is convertible to \tcode{double}.
 If \tcode{firstB == lastB}
 or \tcode{++firstB == lastB},
 let $ n = 1 $,
     $ w_0 = 1 $,
     $ b_0 = 0 $,
 and $ b_1 = 1 $.
 Otherwise,
 $\bigl[\tcode{firstB}, \tcode{lastB}\bigr)$
 shall form a sequence $b$ of length $n+1$,
 the length of the sequence $w$ starting from \tcode{firstW}
 shall be at least $n$,
 and any $w_k$ for  $k \geq n$ shall be ignored by the distribution.

\pnum\effects Constructs a \tcode{piecewise_constant_distribution} object
 with parameters as specified above.
\end{itemdescr}


\indexlibrary{\idxcode{piecewise_constant_distribution}!constructor}%
\begin{itemdecl}
template<class UnaryOperation>
 piecewise_constant_distribution(initializer_list<RealType> bl, UnaryOperation fw);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 Each instance of type \tcode{UnaryOperation}
 shall be a function object~(\ref{function.objects})
 whose return type shall be convertible to \tcode{double}.
 Moreover,
 \tcode{double} shall be convertible
 to the type of \tcode{UnaryOperation}'s sole parameter.

\pnum\effects Constructs a \tcode{piecewise_constant_distribution} object
 with parameters taken or calculated
 from the following values:
 If $\tcode{bl.size()} < 2$,
 let $n = 1$,
     $ w_0 = 1 $,
     $ b_0 = 0 $,
 and $ b_1 = 1 $.
 Otherwise,
 let $\bigl[\tcode{bl.begin()}, \tcode{bl.end()}\bigr)$
 form a sequence $ b_0, \ldots, b_n $,
 and
 let $ w_k = \tcode{fw}\bigl(\bigl(b_{k+1} + b_k\bigr) / 2\bigr) $
 for $ k = 0, \ldots, n\!-\!1 $.

\pnum\complexity
 The number of invocations of \tcode{fw} shall not exceed $n$.
\end{itemdescr}


\indexlibrary{\idxcode{piecewise_constant_distribution}!constructor}%
\begin{itemdecl}
template<class UnaryOperation>
 piecewise_constant_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 Each instance of type \tcode{UnaryOperation}
 shall be a function object~(\ref{function.objects})
 whose return type shall be convertible to \tcode{double}.
 Moreover,
 \tcode{double} shall be convertible
 to the type of \tcode{UnaryOperation}'s sole parameter.
 If $ \tcode{nw} = 0 $, let $ n = 1 $, otherwise let $n = \tcode{nw}$.
 The relation $ 0 < \delta = (\tcode{xmax} - \tcode{xmin}) / n $
 shall hold.

\pnum\effects Constructs a \tcode{piecewise_constant_distribution} object
 with parameters taken or calculated
 from the following values:
 Let $ b_k = \tcode{xmin} + k \cdot \delta $ for $ k = 0, \ldots, n $,
 and $ w_k = \tcode{fw}(b_k + \delta / 2) $ for $ k = 0, \ldots, n\!-\!1 $.

\pnum\complexity
 The number of invocations of \tcode{fw} shall not exceed $n$.
\end{itemdescr}

\indexlibrary{\idxcode{piecewise_constant_distribution}!\idxcode{intervals}}%
\indexlibrary{\idxcode{intervals}!\idxcode{piecewise_constant_distribution}}%
\begin{itemdecl}
vector<result_type> intervals() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns A \tcode{vector<result_type>}
 whose \tcode{size} member returns $n + 1$
 and whose $ \tcode{operator[]} $ member returns $b_k$
 when invoked with argument $k$ for $k = 0, \ldots, n $.
\end{itemdescr}

\indexlibrary{\idxcode{piecewise_constant_distribution}!\idxcode{densities}}%
\indexlibrary{\idxcode{densities}!\idxcode{piecewise_constant_distribution}}%
\begin{itemdecl}
vector<result_type> densities() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns A \tcode{vector<result_type>}
 whose \tcode{size} member returns $n$
 and whose $ \tcode{operator[]} $ member returns $\rho_k$
 when invoked with argument $k$ for $k = 0, \ldots, n\!-\!1 $.
\end{itemdescr}


% ----------------------------------------------------------------------
% Class template piecewise_linear_distribution
% ----------------------------------------------------------------------

\rSec4[rand.dist.samp.plinear]{Class template \tcode{piecewise_linear_distribution}}%
\indexlibrary{\idxcode{piecewise_linear_distribution}}%
\indextext{random number distribution!\idxcode{piecewise_linear_distribution}}

\pnum
A \tcode{piecewise_linear_distribution} random number distribution
produces random numbers $x$,
$ b_0 \leq x < b_n $,
distributed over each subinterval
$ [ b_i, b_{i+1} ) $
according to the probability density function
\indextext{probability density function!\idxcode{piecewise_linear_distribution}}%
\indextext{\idxcode{piecewise_linear_distribution}!probability density function}
\[%
 p(x\,|\,b_0,\ldots,b_n,\;\rho_0,\ldots,\rho_n)
      = \rho_i     \cdot {{b_{i+1} - x} \over {b_{i+1} - b_i}}
      + \rho_{i+1} \cdot {{x - b_i} \over {b_{i+1} - b_i}}
\; \mbox{,}
\mbox{ for } b_i \le x < b_{i+1}
\; \mbox{.}
\]

\pnum
The $n+1$ distribution parameters $b_i$,
also known as this distribution's \techterm{interval boundaries}%
\indextext{\idxcode{piecewise_linear_distribution}!interval boundaries}%
\indextext{interval boundaries!\idxcode{piecewise_linear_distribution}}%
, shall satisfy the relation
 $ b_i < b_{i+1} $
for $i = 0, \ldots, n\!-\!1 $.
Unless specified otherwise,
the remaining $n+1$ distribution parameters are calculated as
$ \rho_k = {w_k / S} \; \mbox{ for } k = 0, \ldots, n $,
in which the values $w_k$,
commonly known as the \techterm{weights at boundaries}%
\indextext{\idxcode{piecewise_linear_distribution}!weights at boundaries}%
\indextext{weights at boundaries!\idxcode{piecewise_linear_distribution}}%
, shall be non-negative, non-NaN, and non-infinity.
Moreover, the following relation shall hold:
\[%
 0 < S = \frac{1}{2}
       \cdot \sum_{k=0}^{n-1} (w_k + w_{k+1}) \cdot (b_{k+1} - b_k)
\; \mbox{.}
\]

\begin{codeblock}
template<class RealType = double>
 class piecewise_linear_distribution
{
public:
 // types
 typedef RealType result_type;
 typedef @\textit{unspecified}@ param_type;

 // constructor and reset functions
 piecewise_linear_distribution();
 template<class InputIteratorB, class InputIteratorW>
   piecewise_linear_distribution(InputIteratorB firstB, InputIteratorB lastB,
                                 InputIteratorW firstW);
 template<class UnaryOperation>
   piecewise_linear_distribution(initializer_list<RealType> bl, UnaryOperation fw);
 template<class UnaryOperation>
   piecewise_linear_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);
 explicit piecewise_linear_distribution(const param_type& parm);
 void reset();

 // generating functions
 template<class URNG>
   result_type operator()(URNG& g);
 template<class URNG>
   result_type operator()(URNG& g, const param_type& parm);

 // property functions
 vector<result_type> intervals() const;
 vector<result_type> densities() const;
 param_type param() const;
 void param(const param_type& parm);
 result_type min() const;
 result_type max() const;
};
\end{codeblock}

\indexlibrary{\idxcode{piecewise_linear_distribution}!constructor}
\begin{itemdecl}
piecewise_linear_distribution();
\end{itemdecl}

\begin{itemdescr}
\pnum\effects Constructs a \tcode{piecewise_linear_distribution} object
 with $ n = 1 $,
 $\rho_0 = \rho_1 = 1 $,
 $ b_0 = 0 $,
 and $ b_1 = 1 $.
\end{itemdescr}

\indexlibrary{\idxcode{piecewise_linear_distribution}!constructor}
\begin{itemdecl}
template<class InputIteratorB, class InputIteratorW>
 piecewise_linear_distribution(InputIteratorB firstB, InputIteratorB lastB,
                               InputIteratorW firstW);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
  \tcode{InputIteratorB} and \tcode{InputIteratorW}
  shall each satisfy the requirements
  of an input iterator (Table~\ref{tab:iterator.input.requirements}) type.
  Moreover,
  \tcode{iterator_traits<InputIteratorB>::value_type} and
  \tcode{iterator_traits<InputIteratorW>::value_type}
  shall each denote a type that is convertible to \tcode{double}.
 If \tcode{firstB == lastB}
 or \tcode{++firstB == lastB},
 let $ n = 1 $,
     $ \rho_0 = \rho_1 = 1 $,
     $ b_0 = 0 $,
 and $ b_1 = 1 $.
 Otherwise,
 $\bigl[\tcode{firstB}, \tcode{lastB}\bigr)$
 shall form a sequence $b$ of length $n+1$,
 the length of the sequence $w$ starting from \tcode{firstW}
 shall be at least $n+1$,
 and any $w_k$ for  $k \geq n+1$ shall be ignored by the distribution.

\pnum\effects Constructs a \tcode{piecewise_linear_distribution} object
 with parameters as specified above.
\end{itemdescr}


\indexlibrary{\idxcode{piecewise_linear_distribution}!constructor}%
\begin{itemdecl}
template<class UnaryOperation>
 piecewise_linear_distribution(initializer_list<RealType> bl, UnaryOperation fw);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 Each instance of type \tcode{UnaryOperation}
 shall be a function object~(\ref{function.objects})
 whose return type shall be convertible to \tcode{double}.
 Moreover,
 \tcode{double} shall be convertible
 to the type of \tcode{UnaryOperation}'s sole parameter.

\pnum\effects Constructs a \tcode{piecewise_linear_distribution} object
 with parameters taken or calculated
 from the following values:
 If $\tcode{bl.size()} < 2$,
 let $n = 1$,
     $ \rho_0 = \rho_1 = 1 $,
     $ b_0 = 0 $,
 and $ b_1 = 1 $.
 Otherwise,
 let $\bigl[\tcode{bl.begin(),} \tcode{bl.end()}\bigr)$
 form a sequence $ b_0, \ldots, b_n $,
 and
 let $ w_k = \tcode{fw}(b_k) $
 for $ k = 0, \ldots, n $.

\pnum\complexity
 The number of invocations of \tcode{fw} shall not exceed $n+1$.
\end{itemdescr}


\indexlibrary{\idxcode{piecewise_linear_distribution}!constructor}%
\begin{itemdecl}
template<class UnaryOperation>
 piecewise_linear_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);
\end{itemdecl}

\begin{itemdescr}
\pnum\requires
 Each instance of type \tcode{UnaryOperation}
 shall be a function object~(\ref{function.objects})
 whose return type shall be convertible to \tcode{double}.
 Moreover,
 \tcode{double} shall be convertible
 to the type of \tcode{UnaryOperation}'s sole parameter.
 If $ \tcode{nw} = 0 $, let $ n = 1 $, otherwise let $n = \tcode{nw}$.
 The relation $ 0 < \delta = (\tcode{xmax} - \tcode{xmin}) / n $
 shall hold.

\pnum\effects Constructs a \tcode{piecewise_linear_distribution} object
 with parameters taken or calculated
 from the following values:
 Let $ b_k = \tcode{xmin} + k \cdot \delta $ for $ k = 0, \ldots, n $,
 and $ w_k = \tcode{fw}(b_k) $ for $ k = 0, \ldots, n $.

\pnum\complexity
 The number of invocations of \tcode{fw} shall not exceed $n+1$.
\end{itemdescr}

\indexlibrary{\idxcode{piecewise_linear_distribution}!\idxcode{intervals}}%
\indexlibrary{\idxcode{intervals}!\idxcode{piecewise_linear_distribution}}%
\begin{itemdecl}
vector<result_type> intervals() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns A \tcode{vector<result_type>}
 whose \tcode{size} member returns $n + 1$
 and whose $ \tcode{operator[]} $ member returns $b_k$
 when invoked with argument $k$ for $k = 0, \ldots, n $.
\end{itemdescr}

\indexlibrary{\idxcode{piecewise_linear_distribution}!\idxcode{densities}}%
\indexlibrary{\idxcode{densities}!\idxcode{piecewise_linear_distribution}}%
\begin{itemdecl}
vector<result_type> densities() const;
\end{itemdecl}

\begin{itemdescr}
\pnum\returns A \tcode{vector<result_type>}
 whose \tcode{size} member returns $n$
 and whose $ \tcode{operator[]} $ member returns $\rho_k$
 when invoked with argument $k$ for $ k = 0, \ldots, n $.
\end{itemdescr}%
%
\indextext{random number distributions!sampling|)}%
\indextext{sampling distributions|)}%
\indextext{random number generation!distributions|)}%
\indextext{random number generation|)}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\rSec1[numarray]{Numeric arrays}

\rSec2[valarray.syn]{Header \tcode{<valarray>} synopsis}
\indexlibrary{\idxhdr{valarray}}%
\begin{codeblock}
#include <initializer_list>

namespace std {

  template<class T> class valarray;         // An array of type \tcode{T}
  class slice;                              // a BLAS-like slice out of an array
  template<class T> class slice_array;
  class gslice;                             // a generalized slice out of an array
  template<class T> class gslice_array;
  template<class T> class mask_array;       // a masked array
  template<class T> class indirect_array;   // an indirected array

  template<class T> void swap(valarray<T>&, valarray<T>&) noexcept;

  template<class T> valarray<T> operator* (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator* (const valarray<T>&, const T&);
  template<class T> valarray<T> operator* (const T&, const valarray<T>&);

  template<class T> valarray<T> operator/ (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator/ (const valarray<T>&, const T&);
  template<class T> valarray<T> operator/ (const T&, const valarray<T>&);

  template<class T> valarray<T> operator% (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator% (const valarray<T>&, const T&);
  template<class T> valarray<T> operator% (const T&, const valarray<T>&);

  template<class T> valarray<T> operator+ (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator+ (const valarray<T>&, const T&);
  template<class T> valarray<T> operator+ (const T&, const valarray<T>&);

  template<class T> valarray<T> operator- (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator- (const valarray<T>&, const T&);
  template<class T> valarray<T> operator- (const T&, const valarray<T>&);

  template<class T> valarray<T> operator^ (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator^ (const valarray<T>&, const T&);
  template<class T> valarray<T> operator^ (const T&, const valarray<T>&);

  template<class T> valarray<T> operator& (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator& (const valarray<T>&, const T&);
  template<class T> valarray<T> operator& (const T&, const valarray<T>&);

  template<class T> valarray<T> operator| (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator| (const valarray<T>&, const T&);
  template<class T> valarray<T> operator| (const T&, const valarray<T>&);

  template<class T> valarray<T> operator<<(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator<<(const valarray<T>&, const T&);
  template<class T> valarray<T> operator<<(const T&, const valarray<T>&);

  template<class T> valarray<T> operator>>(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> operator>>(const valarray<T>&, const T&);
  template<class T> valarray<T> operator>>(const T&, const valarray<T>&);

  template<class T> valarray<bool> operator&&(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator&&(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator&&(const T&, const valarray<T>&);

  template<class T> valarray<bool> operator||(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator||(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator||(const T&, const valarray<T>&);

  template<class T>
    valarray<bool> operator==(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator==(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator==(const T&, const valarray<T>&);
  template<class T>
    valarray<bool> operator!=(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator!=(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator!=(const T&, const valarray<T>&);

  template<class T>
    valarray<bool> operator< (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator< (const valarray<T>&, const T&);
  template<class T> valarray<bool> operator< (const T&, const valarray<T>&);
  template<class T>
    valarray<bool> operator> (const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator> (const valarray<T>&, const T&);
  template<class T> valarray<bool> operator> (const T&, const valarray<T>&);
  template<class T>
    valarray<bool> operator<=(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator<=(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator<=(const T&, const valarray<T>&);
  template<class T>
    valarray<bool> operator>=(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<bool> operator>=(const valarray<T>&, const T&);
  template<class T> valarray<bool> operator>=(const T&, const valarray<T>&);

  template<class T> valarray<T> abs  (const valarray<T>&);
  template<class T> valarray<T> acos (const valarray<T>&);
  template<class T> valarray<T> asin (const valarray<T>&);
  template<class T> valarray<T> atan (const valarray<T>&);

  template<class T> valarray<T> atan2(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> atan2(const valarray<T>&, const T&);
  template<class T> valarray<T> atan2(const T&, const valarray<T>&);

  template<class T> valarray<T> cos  (const valarray<T>&);
  template<class T> valarray<T> cosh (const valarray<T>&);
  template<class T> valarray<T> exp  (const valarray<T>&);
  template<class T> valarray<T> log  (const valarray<T>&);
  template<class T> valarray<T> log10(const valarray<T>&);

  template<class T> valarray<T> pow(const valarray<T>&, const valarray<T>&);
  template<class T> valarray<T> pow(const valarray<T>&, const T&);
  template<class T> valarray<T> pow(const T&, const valarray<T>&);

  template<class T> valarray<T> sin  (const valarray<T>&);
  template<class T> valarray<T> sinh (const valarray<T>&);
  template<class T> valarray<T> sqrt (const valarray<T>&);
  template<class T> valarray<T> tan  (const valarray<T>&);
  template<class T> valarray<T> tanh (const valarray<T>&);

  template <class T> @\unspec{1}@ begin(valarray<T>& v);
  template <class T> @\unspec{2}@ begin(const valarray<T>& v);
  template <class T> @\unspec{1}@ end(valarray<T>& v);
  template <class T> @\unspec{2}@ end(const valarray<T>& v);
}
\end{codeblock}

\pnum
The header
\tcode{<valarray>}
defines five
class templates
(\tcode{valarray},
\tcode{slice_array},
\tcode{gslice_array},
\tcode{mask_array},
and
\tcode{indirect_array}),
two classes (\tcode{slice}
and
\tcode{gslice}),
and a series of related
function templates
for representing
and manipulating arrays of values.

\pnum
The
\tcode{valarray}
array classes
are defined to be free of certain forms of aliasing, thus allowing
operations on these classes to be optimized.

\pnum
Any function returning a
\tcode{valarray<T>}
is permitted to return an object of another type, provided all the
const member functions of
\tcode{valarray<T>}
are also applicable to this type.
This return type shall not add
more than two levels of template nesting over the most deeply nested
argument type.\footnote{Clause~\ref{limits} recommends a minimum number
of recursively nested template
instantiations.
This requirement thus indirectly suggests a minimum
allowable complexity for valarray expressions.}

\pnum
Implementations introducing such replacement types shall provide
additional functions and operators as follows:
\begin{itemize}
\item
for every function taking a
\tcode{const valarray<T>\&} other than \tcode{begin} and
\tcode{end}~(\ref{valarray.range}),
identical functions taking the replacement types shall be added;
\item
for every function taking two
\tcode{const valarray<T>\&}
arguments, identical functions taking every combination of
\tcode{const valarray<T>\&}
and replacement types shall be added.
\end{itemize}

\pnum
In particular, an implementation shall allow a
\tcode{valarray<T>}
to be constructed from such replacement types and shall allow assignments
and computed assignments of such types to
\tcode{valarray<T>},
\tcode{slice_array<T>},
\tcode{gslice_array<T>},
\tcode{mask_array<T>}
and
\tcode{indirect_array<T>}
objects.

\pnum
These library functions are permitted to throw a
\tcode{bad_alloc}~(\ref{bad.alloc}) exception if there are not sufficient resources available
to carry out the operation.
Note that the exception is not mandated.

\rSec2[template.valarray]{Class template \tcode{valarray}}

\rSec3[template.valarray.overview]{Class template \tcode{valarray} overview}

\indexlibrary{\idxcode{valarray}}%
\begin{codeblock}
namespace std {
  template<class T> class valarray {
  public:
    typedef T value_type;

    // \ref{valarray.cons} construct/destroy:
    valarray();
    explicit valarray(size_t);
    valarray(const T&, size_t);
    valarray(const T*, size_t);
    valarray(const valarray&);
    valarray(valarray&&) noexcept;
    valarray(const slice_array<T>&);
    valarray(const gslice_array<T>&);
    valarray(const mask_array<T>&);
    valarray(const indirect_array<T>&);
    valarray(initializer_list<T>);
    ~valarray();

    // \ref{valarray.assign} assignment:
    valarray<T>& operator=(const valarray<T>&);
    valarray<T>& operator=(valarray<T>&&) noexcept;
    valarray& operator=(initializer_list<T>);
    valarray<T>& operator=(const T&);
    valarray<T>& operator=(const slice_array<T>&);
    valarray<T>& operator=(const gslice_array<T>&);
    valarray<T>& operator=(const mask_array<T>&);
    valarray<T>& operator=(const indirect_array<T>&);

    // \ref{valarray.access} element access:
    const T&          operator[](size_t) const;
    T&                operator[](size_t);

    // \ref{valarray.sub} subset operations:
    valarray<T>       operator[](slice) const;
    slice_array<T>    operator[](slice);
    valarray<T>       operator[](const gslice&) const;
    gslice_array<T>   operator[](const gslice&);
    valarray<T>       operator[](const valarray<bool>&) const;
    mask_array<T>     operator[](const valarray<bool>&);
    valarray<T>       operator[](const valarray<size_t>&) const;
    indirect_array<T> operator[](const valarray<size_t>&);

    // \ref{valarray.unary} unary operators:
    valarray<T> operator+() const;
    valarray<T> operator-() const;
    valarray<T> operator~() const;
    valarray<bool> operator!() const;

    // \ref{valarray.cassign} computed assignment:
    valarray<T>& operator*= (const T&);
    valarray<T>& operator/= (const T&);
    valarray<T>& operator%= (const T&);
    valarray<T>& operator+= (const T&);
    valarray<T>& operator-= (const T&);
    valarray<T>& operator^= (const T&);
    valarray<T>& operator&= (const T&);
    valarray<T>& operator|= (const T&);
    valarray<T>& operator<<=(const T&);
    valarray<T>& operator>>=(const T&);

    valarray<T>& operator*= (const valarray<T>&);
    valarray<T>& operator/= (const valarray<T>&);
    valarray<T>& operator%= (const valarray<T>&);
    valarray<T>& operator+= (const valarray<T>&);
    valarray<T>& operator-= (const valarray<T>&);
    valarray<T>& operator^= (const valarray<T>&);
    valarray<T>& operator|= (const valarray<T>&);
    valarray<T>& operator&= (const valarray<T>&);
    valarray<T>& operator<<=(const valarray<T>&);
    valarray<T>& operator>>=(const valarray<T>&);

    // \ref{valarray.members} member functions:
    void swap(valarray&) noexcept;

    size_t size() const;

    T sum() const;
    T min() const;
    T max() const;

    valarray<T> shift (int) const;
    valarray<T> cshift(int) const;
    valarray<T> apply(T func(T)) const;
    valarray<T> apply(T func(const T&)) const;
    void resize(size_t sz, T c = T());
  };
}
\end{codeblock}

\pnum
The
class template
\tcode{valarray<T>}
is a
one-dimensional smart array, with elements numbered sequentially from zero.
It is a representation of the mathematical concept
of an ordered set of values.
The illusion of higher dimensionality
may be produced by the familiar idiom of computed indices, together
with the powerful subsetting capabilities provided
by the generalized subscript operators.\footnote{The intent is to specify
an array template that has the minimum functionality
necessary to address aliasing ambiguities and the proliferation of
temporaries.
Thus, the
\tcode{valarray}
template is neither a
matrix class nor a field class.
However, it is a very useful building block for designing such classes.}

\pnum
An implementation is permitted to qualify any of the functions declared in
\tcode{<valarray>}
as
\tcode{inline}.

\rSec3[valarray.cons]{\tcode{valarray} constructors}

\indexlibrary{\idxcode{valarray}!\idxcode{valarray}}%
\begin{itemdecl}
valarray();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs an object of class
\tcode{valarray<T>}\footnote{For convenience, such objects are referred
to as ``arrays'' throughout the
remainder of~\ref{numarray}.}
which has zero length.\footnote{This default constructor is essential,
since arrays of
\tcode{valarray}
may be useful.
After initialization, the length of an empty array can be increased with the
\tcode{resize}
member function.}
\end{itemdescr}

\indexlibrary{\idxcode{valarray}!\idxcode{constructor}}%
\begin{itemdecl}
explicit valarray(size_t);
\end{itemdecl}

\begin{itemdescr}
\pnum
The array created by this constructor has a length equal to the value of the argument.
The elements of the array are value-initialized~(\ref{dcl.init}).
\end{itemdescr}

\indexlibrary{\idxcode{valarray}!\idxcode{constructor}}%
\begin{itemdecl}
valarray(const T&, size_t);
\end{itemdecl}

\begin{itemdescr}
\pnum
The array created by this constructor has a length equal to the second
argument.
The elements of the array are initialized with the value of the first argument.
\end{itemdescr}

\indexlibrary{\idxcode{valarray}!\idxcode{constructor}}%
\begin{itemdecl}
valarray(const T*, size_t);
\end{itemdecl}

\begin{itemdescr}
\pnum
The array created by this constructor has a length equal to the second
argument
\tcode{n}.
The values of the elements of the array are initialized with the
first
\tcode{n}
values pointed to by the first argument.\footnote{This constructor is the
preferred method for converting a C array to a
\tcode{valarray}
object.}
If the value of the second argument is greater than the number of values
pointed to by the first argument, the behavior is undefined.%
\indextext{undefined}
\end{itemdescr}

\indexlibrary{\idxcode{valarray}!\idxcode{constructor}}%
\begin{itemdecl}
valarray(const valarray<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
The array created by this constructor has the same length as the argument
array.
The elements are initialized with the values of the corresponding
elements of the argument array.\footnote{This copy constructor creates
a distinct array rather than an alias.
Implementations in which arrays share storage are permitted, but they
shall implement a copy-on-reference mechanism to ensure that arrays are
conceptually distinct.}
\end{itemdescr}

\indexlibrary{\idxcode{valarray}!\idxcode{constructor}}%
\begin{itemdecl}
valarray(valarray<T>&& v) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
The array created by this constructor has the same length as the argument
array.
The elements are initialized with the values of the corresponding
elements of the argument array.

\pnum
\complexity Constant.
\end{itemdescr}

\indexlibrary{\idxcode{valarray}!\idxcode{constructor}}%
\begin{itemdecl}
valarray(initializer_list<T> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects Same as \tcode{valarray(il.begin(), il.size())}.
\end{itemdescr}

\indexlibrary{\idxcode{valarray}!\idxcode{constructor}}%
\begin{itemdecl}
valarray(const slice_array<T>&);
valarray(const gslice_array<T>&);
valarray(const mask_array<T>&);
valarray(const indirect_array<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
These conversion constructors convert one of the four reference templates
to a
\tcode{valarray}.
\end{itemdescr}

\indexlibrary{\idxcode{valarray}!destructor}%
\begin{itemdecl}
~valarray();
\end{itemdecl}

\begin{itemdescr}
\pnum
The destructor is applied to every element of
\tcode{*this};
an implementation may return all allocated memory.
\end{itemdescr}

\rSec3[valarray.assign]{\tcode{valarray} assignment}

\indexlibrary{\idxcode{operator=}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T>& operator=(const valarray<T>& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
Each element of the
\tcode{*this}
array is assigned the value of the corresponding element of the argument
array.
If the length of \tcode{v} is not equal to the length of \tcode{*this}
, resizes \tcode{*this} to make the two arrays the same length,
as if by calling \tcode{resize(v.size())}, before performing the assignment.

\pnum
\postcondition \tcode{size() == v.size()}.
\end{itemdescr}

\indexlibrary{\idxcode{operator=}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T>& operator=(valarray<T>&& v) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{*this} obtains the value of \tcode{v}.
The value of \tcode{v} after the assignment is not specified.

\pnum
\complexity Linear.
\end{itemdescr}

\indexlibrary{\idxcode{operator=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator=}}%
\begin{itemdecl}
valarray& operator=(initializer_list<T> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{*this = valarray(il)}.

\pnum
\returns \tcode{*this}.
\end{itemdescr}


\indexlibrary{\idxcode{operator=}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T>& operator=(const T&);
\end{itemdecl}

\begin{itemdescr}
\pnum
The scalar assignment operator causes each element of the
\tcode{*this}
array to be assigned the value of the argument.
\end{itemdescr}

\indexlibrary{\idxcode{operator=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator=}}%
\begin{itemdecl}
valarray<T>& operator=(const slice_array<T>&);
valarray<T>& operator=(const gslice_array<T>&);
valarray<T>& operator=(const mask_array<T>&);
valarray<T>& operator=(const indirect_array<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires The length of the array to which the argument refers equals \tcode{size()}.

\pnum
These operators allow the results of a generalized subscripting operation
to be assigned directly to a
\tcode{valarray}.

\pnum
If the value of an element in the left-hand side of a valarray assignment
operator depends on the value of another element in that left-hand side,
the resulting behavior is undefined.
\end{itemdescr}

\rSec3[valarray.access]{\tcode{valarray} element access}

\indexlibrary{\idxcode{operator[]}!\idxcode{valarray}}%
\begin{itemdecl}
const T&  operator[](size_t) const;
T& operator[](size_t);
\end{itemdecl}

\begin{itemdescr}
\pnum
The subscript operator
returns a reference to the corresponding element of the array.

\pnum
Thus, the expression
\tcode{(a[i] = q, a[i]) == q}
evaluates as true for any non-constant
\tcode{valarray<T> a},
any
\tcode{T q},
and for any
\tcode{size_t i}
such that the value of
\tcode{i}
is less than the length of
\tcode{a}.

\pnum
The expression
\tcode{\&a[i+j] == \&a[i] + j}
evaluates as true for all
\tcode{size_t i}
and
\tcode{size_t j}
such that
\tcode{i+j}
is less than the length of the array
\tcode{a}.

\pnum
Likewise, the expression
\tcode{\&a[i] != \&b[j]}
evaluates as
\tcode{true}
for any two arrays
\tcode{a}
and
\tcode{b}
and for any
\tcode{size_t i}
and
\tcode{size_t j}
such that
\tcode{i}
is less than the length of
\tcode{a}
and
\tcode{j}
is less than the length of
\tcode{b}.
This property indicates an absence of aliasing and may be used to
advantage by optimizing compilers.\footnote{Compilers may take advantage
of inlining, constant propagation, loop fusion,
tracking of pointers obtained from
\tcode{operator new},
and other
techniques to generate efficient
\tcode{valarray}s.}

\pnum
The reference returned by the subscript operator for an array shall
be valid until the member function
\tcode{resize(size_t, T)}~(\ref{valarray.members}) is called for that array or until the lifetime of
that array ends, whichever happens first.

\pnum
If the subscript operator
is invoked with a
\tcode{size_t}
argument whose value is not
less than the length of the array, the behavior is undefined.%
\indextext{undefined}
\end{itemdescr}

\rSec3[valarray.sub]{\tcode{valarray} subset operations}

\indexlibrary{\idxcode{operator[]}!\idxcode{valarray}}%
\pnum
The member \tcode{operator[]} is overloaded to provide several ways to select
sequences of elements from among those controlled by \tcode{*this}. Each of these
operations returns a subset of the array. The const-qualified versions return this
subset as a new \tcode{valarray} object. The non-const versions return a class
template object which has reference semantics to the original array, working in
conjunction with various overloads of \tcode{operator=} and other assigning
operators to allow selective replacement (slicing) of the controlled sequence.
In each case the selected element(s) must exist.

\indexlibrary{\idxcode{operator[]}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T> operator[](slice slicearr) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object of class \tcode{valarray<T>} containing those
elements of the controlled sequence designated by \tcode{slicearr}.
\enterexample
\begin{codeblock}
const valarray<char> v0("abcdefghijklmnop", 16);
// \tcode{v0[slice(2, 5, 3)]} returns \tcode{valarray<char>("cfilo", 5)}
\end{codeblock}
\exitexample
\end{itemdescr}

\indexlibrary{\idxcode{operator[]}!\idxcode{valarray}}%
\begin{itemdecl}
slice_array<T> operator[](slice slicearr);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object that holds references to elements of the controlled
sequence selected by \tcode{slicearr}. \enterexample
\begin{codeblock}
valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABCDE", 5);
v0[slice(2, 5, 3)] = v1;
// \tcode{v0 == valarray<char>("abAdeBghCjkDmnEp", 16);}
\end{codeblock}
\exitexample
\end{itemdescr}

\indexlibrary{\idxcode{operator[]}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T> operator[](const gslice& gslicearr) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object of class \tcode{valarray<T>} containing those
elements of the controlled sequence designated by \tcode{gslicearr}.
\enterexample
\begin{codeblock}
const valarray<char> v0("abcdefghijklmnop", 16);
const size_t lv[] = { 2, 3 };
const size_t dv[] = { 7, 2 };
const valarray<size_t> len(lv, 2), str(dv, 2);
// \tcode{v0[gslice(3, len, str)]} returns
// \tcode{valarray<char>("dfhkmo", 6)}
\end{codeblock}
\exitexample
\end{itemdescr}

\indexlibrary{\idxcode{operator[]}!\idxcode{valarray}}%
\begin{itemdecl}
gslice_array<T> operator[](const gslice& gslicearr);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object that holds references to elements of the controlled
sequence selected by \tcode{gslicearr}. \enterexample
\begin{codeblock}
valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABCDE", 5);
const size_t lv[] = { 2, 3 };
const size_t dv[] = { 7, 2 };
const valarray<size_t> len(lv, 2), str(dv, 2);
v0[gslice(3, len, str)] = v1;
// \tcode{v0 == valarray<char>("abcAeBgCijDlEnFp", 16)}
\end{codeblock}
\exitexample
\end{itemdescr}

\indexlibrary{\idxcode{operator[]}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T> operator[](const valarray<bool>& boolarr) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object of class \tcode{valarray<T>} containing those
elements of the controlled sequence designated by \tcode{boolarr}.
\enterexample
\begin{codeblock}
const valarray<char> v0("abcdefghijklmnop", 16);
const bool vb[] = { false, false, true, true, false, true };
// \tcode{v0[valarray<bool>(vb, 6)]} returns
// \tcode{valarray<char>("cdf", 3)}
\end{codeblock}
\exitexample
\end{itemdescr}

\indexlibrary{\idxcode{operator[]}!\idxcode{valarray}}%
\begin{itemdecl}
mask_array<T> operator[](const valarray<bool>& boolarr);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object that holds references to elements of the controlled
sequence selected by \tcode{boolarr}. \enterexample
\begin{codeblock}
valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABC", 3);
const bool vb[] = { false, false, true, true, false, true };
v0[valarray<bool>(vb, 6)] = v1;
// \tcode{v0 == valarray<char>("abABeCghijklmnop", 16)}
\end{codeblock}
\exitexample
\end{itemdescr}

\indexlibrary{\idxcode{operator[]}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T> operator[](const valarray<size_t>& indarr) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object of class \tcode{valarray<T>} containing those
elements of the controlled sequence designated by \tcode{indarr}.
\enterexample
\begin{codeblock}
const valarray<char> v0("abcdefghijklmnop", 16);
const size_t vi[] = { 7, 5, 2, 3, 8 };
// \tcode{v0[valarray<size_t>(vi, 5)]} returns
// \tcode{valarray<char>("hfcdi", 5)}
\end{codeblock}
\exitexample
\end{itemdescr}

\indexlibrary{\idxcode{operator[]}!\idxcode{valarray}}%
\begin{itemdecl}
indirect_array<T> operator[](const valarray<size_t>& indarr);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An object that holds references to elements of the controlled
sequence selected by \tcode{indarr}. \enterexample
\begin{codeblock}
valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABCDE", 5);
const size_t vi[] = { 7, 5, 2, 3, 8 };
v0[valarray<size_t>(vi, 5)] = v1;
// \tcode{v0 == valarray<char>("abCDeBgAEjklmnop", 16)}
\end{codeblock}
\exitexample
\end{itemdescr}

\rSec3[valarray.unary]{\tcode{valarray} unary operators}

\indexlibrary{\idxcode{operator+}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator-}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\~{}}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator"!}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T> operator+() const;
valarray<T> operator-() const;
valarray<T> operator~() const;
valarray<bool> operator!() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
Each of these operators may only be instantiated for a type \tcode{T}
to which the indicated operator can be applied and for which the indicated
operator returns a value which is of type \tcode{T} (\tcode{bool} for
\tcode{operator!}) or which may be unambiguously implicitly converted to type
\tcode{T} (\tcode{bool} for \tcode{operator!}).

\pnum
Each of these operators returns an array whose length is equal to the length
of the array.
Each element of the returned array is initialized with the result of
applying the indicated operator to the corresponding element of the array.
\end{itemdescr}

\rSec3[valarray.cassign]{\tcode{valarray} computed assignment}

\indexlibrary{\idxcode{operator*=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator/=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\%=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator+=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator-=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\^{}=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\&=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator"|=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\shl=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\shr=}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T>& operator*= (const valarray<T>&);
valarray<T>& operator/= (const valarray<T>&);
valarray<T>& operator%= (const valarray<T>&);
valarray<T>& operator+= (const valarray<T>&);
valarray<T>& operator-= (const valarray<T>&);
valarray<T>& operator^= (const valarray<T>&);
valarray<T>& operator&= (const valarray<T>&);
valarray<T>& operator|= (const valarray<T>&);
valarray<T>& operator<<=(const valarray<T>&);
valarray<T>& operator>>=(const valarray<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
Each of these operators may only be instantiated for a type \tcode{T}
to which the indicated operator can be applied.
Each of these operators
performs the indicated operation on each of its elements and the
corresponding element of the argument array.

\pnum
The array is then returned by reference.

\pnum
If the array and the
argument array do not have the same length, the behavior is undefined.%
\indextext{undefined}
The appearance of an array on the left-hand side of a computed assignment
does \tcode{not} invalidate references or pointers.

\pnum
If the value of an element in the left-hand side of a valarray computed
assignment operator depends on the value of another element in that left
hand side, the resulting behavior is undefined.
\end{itemdescr}

\indexlibrary{\idxcode{operator*=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator*=}}%
\indexlibrary{\idxcode{operator/=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator/=}}%
\indexlibrary{\idxcode{operator\%=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\%=}}%
\indexlibrary{\idxcode{operator+=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator+=}}%
\indexlibrary{\idxcode{operator-=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator-=}}%
\indexlibrary{\idxcode{operator\^{}=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\^{}=}}%
\indexlibrary{\idxcode{operator\&=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\&=}}%
\indexlibrary{\idxcode{operator"|=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator"|=}}%
\indexlibrary{\idxcode{operator\shl=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\shl=}}%
\indexlibrary{\idxcode{operator\shr=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\shr=}}%
\begin{itemdecl}
valarray<T>& operator*= (const T&);
valarray<T>& operator/= (const T&);
valarray<T>& operator%= (const T&);
valarray<T>& operator+= (const T&);
valarray<T>& operator-= (const T&);
valarray<T>& operator^= (const T&);
valarray<T>& operator&= (const T&);
valarray<T>& operator|= (const T&);
valarray<T>& operator<<=(const T&);
valarray<T>& operator>>=(const T&);
\end{itemdecl}

\begin{itemdescr}
\pnum
Each of these operators may only be instantiated for a type \tcode{T}
to which the indicated operator can be applied.

\pnum
Each of these operators applies the indicated operation to each element
of the array and the non-array argument.

\pnum
The array is then returned by reference.

\pnum
The appearance of an array on the left-hand side of a computed assignment
does
\textit{not}
invalidate references or pointers to the elements of the array.
\end{itemdescr}

\rSec3[valarray.members]{\tcode{valarray} member functions}

\indexlibrary{\idxcode{swap}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{swap}}%
\begin{itemdecl}
void swap(valarray& v) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{*this} obtains the value of
\tcode{v}. \tcode{v} obtains the value of \tcode{*this}.

\pnum
\complexity Constant.
\end{itemdescr}

\indexlibrary{\idxcode{length}!\idxcode{valarray}}%
\begin{itemdecl}
size_t size() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns The number of elements in the array.

\pnum
\complexity constant time.
\end{itemdescr}

\indexlibrary{\idxcode{sum}!\idxcode{valarray}}%
\begin{itemdecl}
T sum() const;
\end{itemdecl}

\begin{itemdescr}
This function may only be instantiated for a type \tcode{T} to which
\tcode{operator+=}
can be applied.
This function returns the sum of all the elements of the array.

\pnum
If the array has length 0, the behavior is undefined.%
\indextext{undefined}
If the array has length 1,
\tcode{sum()}
returns the value of element 0.
Otherwise, the returned value is calculated by applying
\tcode{operator+=}
to a copy of an element of the array and
all other elements of the array in an unspecified order.%
\indextext{unspecified behavior}
\end{itemdescr}

\indexlibrary{\idxcode{min}!\idxcode{valarray}}%
\begin{itemdecl}
T min() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
This function returns the minimum value contained in
\tcode{*this}.
The value returned for an array of length 0 is undefined.
For an array
of length 1, the value of element 0 is returned.
For all other array
lengths, the determination is made using
\tcode{operator<}.
\end{itemdescr}

\indexlibrary{\idxcode{max}!\idxcode{valarray}}%
\begin{itemdecl}
T max() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
This function returns the maximum value contained in
\tcode{*this}.
The value returned for an array of length 0 is undefined.
For an array
of length 1, the value of element 0 is returned.
For all other array
lengths, the determination is made using
\tcode{operator<}.
\end{itemdescr}

\indexlibrary{\idxcode{shift}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T> shift(int n) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
This function returns an object of class
\tcode{valarray<T>}
of length
\tcode{size()},
each of whose elements
\textit{I}
is
\tcode{(*this)[I + n]}
if
\tcode{I + n}
is non-negative and less than
\tcode{size()},
otherwise
\tcode{T()}.
Thus if element zero is taken as the leftmost element,
a positive value of \tcode{n} shifts the elements left \tcode{n}
places, with zero fill.

\pnum
\enterexample
If the argument has the value -2,
the first two elements of the result will be value-initialized~(\ref{dcl.init}); the third element of the result will be assigned the value
of the first element of the argument; etc.
\exitexample
\indexlibrary{\idxcode{cshift}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T> cshift(int n) const;
\end{itemdecl}

\pnum
This function returns an object of class
\tcode{valarray<T>}
of length
\tcode{size()}
that is a circular shift of \tcode{*this}. If element zero is taken as the leftmost element, a non-negative value of \emph{n} shifts the elements circularly left \emph{n} places and a negative value of \emph{n} shifts the elements circularly right \emph{-n} places.
\end{itemdescr}

\indexlibrary{\idxcode{apply}!\idxcode{valarray}}%
\begin{itemdecl}
valarray<T> apply(T func(T)) const;
valarray<T> apply(T func(const T&)) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
These functions return an array whose length is equal to the array.
Each element of the returned array is assigned
the value returned by applying the argument function to the
corresponding element of the array.

\indexlibrary{\idxcode{resize}!\idxcode{valarray}}%
\begin{itemdecl}
void resize(size_t sz, T c = T());
\end{itemdecl}

\pnum
This member function changes the length of the
\tcode{*this}
array to
\tcode{sz}
and then assigns to each element the value of the second argument.
Resizing invalidates all pointers and references to elements in the array.
\end{itemdescr}

\rSec2[valarray.nonmembers]{\tcode{valarray} non-member operations}

\rSec3[valarray.binary]{\tcode{valarray} binary operators}

\indexlibrary{\idxcode{operator*}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator/}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\%}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator+}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator-}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\^{}}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\&}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator"|}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\shl}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\shr}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\&\&}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator"|"|}!\idxcode{valarray}}%
\begin{itemdecl}
template<class T> valarray<T> operator*
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator/
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator%
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator+
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator-
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator^
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator&
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator|
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator<<
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> operator>>
    (const valarray<T>&, const valarray<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
Each of these operators may only be instantiated for a type \tcode{T}
to which the indicated operator can be applied and for which the indicated
operator returns a value which is of type \tcode{T} or which
can be unambiguously implicitly converted to type \tcode{T}.

\pnum
Each of these operators returns an array whose length is equal to the
lengths of the argument arrays.
Each element of the returned array is
initialized with the result of applying the indicated operator to the
corresponding elements of the argument arrays.

\pnum
If the argument arrays do not have the same length, the behavior is undefined.%
\indextext{undefined}
\end{itemdescr}

\indexlibrary{\idxcode{operator*}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator*}}%
\indexlibrary{\idxcode{operator/}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator/}}%
\indexlibrary{\idxcode{operator\%}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\%}}%
\indexlibrary{\idxcode{operator+}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator+}}%
\indexlibrary{\idxcode{operator=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator=}}%
\indexlibrary{\idxcode{operator\^{}}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\^{}}}%
\indexlibrary{\idxcode{operator\&}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\&}}%
\indexlibrary{\idxcode{operator"|}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator"|}}%
\indexlibrary{\idxcode{operator\shl}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\shl}}%
\indexlibrary{\idxcode{operator\shr}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\shr}}%
\begin{itemdecl}
template<class T> valarray<T> operator* (const valarray<T>&, const T&);
template<class T> valarray<T> operator* (const T&, const valarray<T>&);
template<class T> valarray<T> operator/ (const valarray<T>&, const T&);
template<class T> valarray<T> operator/ (const T&, const valarray<T>&);
template<class T> valarray<T> operator% (const valarray<T>&, const T&);
template<class T> valarray<T> operator% (const T&, const valarray<T>&);
template<class T> valarray<T> operator+ (const valarray<T>&, const T&);
template<class T> valarray<T> operator+ (const T&, const valarray<T>&);
template<class T> valarray<T> operator- (const valarray<T>&, const T&);
template<class T> valarray<T> operator- (const T&, const valarray<T>&);
template<class T> valarray<T> operator^ (const valarray<T>&, const T&);
template<class T> valarray<T> operator^ (const T&, const valarray<T>&);
template<class T> valarray<T> operator& (const valarray<T>&, const T&);
template<class T> valarray<T> operator& (const T&, const valarray<T>&);
template<class T> valarray<T> operator| (const valarray<T>&, const T&);
template<class T> valarray<T> operator| (const T&, const valarray<T>&);
template<class T> valarray<T> operator<<(const valarray<T>&, const T&);
template<class T> valarray<T> operator<<(const T&, const valarray<T>&);
template<class T> valarray<T> operator>>(const valarray<T>&, const T&);
template<class T> valarray<T> operator>>(const T&, const valarray<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
Each of these operators may only be instantiated for a type \tcode{T}
to which the indicated operator can be applied and for which
the indicated operator returns a value which is of type \tcode{T}
or which can be unambiguously implicitly converted to type \tcode{T}.

\pnum
Each of these operators returns an array whose length is equal to the
length of the array argument.
Each element of the returned array is
initialized with the result of applying the indicated operator to the
corresponding element of the array argument and the non-array argument.
\end{itemdescr}

\rSec3[valarray.comparison]{\tcode{valarray} logical operators}

\indexlibrary{\idxcode{operator==}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator<}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator>}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator<=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator>=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator\&\&}!\idxcode{valarray}}%
\indexlibrary{\idxcode{operator"|"|}!\idxcode{valarray}}%
\begin{itemdecl}
template<class T> valarray<bool> operator==
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator!=
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator<
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator>
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator<=
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator>=
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator&&
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<bool> operator||
    (const valarray<T>&, const valarray<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
Each of these operators may only be instantiated for a type \tcode{T}
to which the indicated operator can be applied and for which
the indicated operator returns a value which is of type \tcode{bool}
or which can be unambiguously implicitly converted to type \tcode{bool}.

\pnum
Each of these operators returns a \tcode{bool} array whose length
is equal to the length of the array arguments.
Each element of the returned
array is initialized with the result of applying the indicated
operator to the corresponding elements of the argument arrays.

\pnum
If the two array arguments do not have the same length,
the behavior is undefined.%
\indextext{undefined}
\end{itemdescr}

\indexlibrary{\idxcode{operator==}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator==}}%
\indexlibrary{\idxcode{operator"!=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator"!=}}%
\indexlibrary{\idxcode{operator<}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator<}}%
\indexlibrary{\idxcode{operator<=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator<=}}%
\indexlibrary{\idxcode{operator>}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator>}}%
\indexlibrary{\idxcode{operator>=}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator>=}}%
\indexlibrary{\idxcode{operator\&\&}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator\&\&}}%
\indexlibrary{\idxcode{operator"|"|}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{operator"|"|}}%
\begin{itemdecl}
template<class T> valarray<bool> operator==(const valarray<T>&, const T&);
template<class T> valarray<bool> operator==(const T&, const valarray<T>&);
template<class T> valarray<bool> operator!=(const valarray<T>&, const T&);
template<class T> valarray<bool> operator!=(const T&, const valarray<T>&);
template<class T> valarray<bool> operator< (const valarray<T>&, const T&);
template<class T> valarray<bool> operator< (const T&, const valarray<T>&);
template<class T> valarray<bool> operator> (const valarray<T>&, const T&);
template<class T> valarray<bool> operator> (const T&, const valarray<T>&);
template<class T> valarray<bool> operator<=(const valarray<T>&, const T&);
template<class T> valarray<bool> operator<=(const T&, const valarray<T>&);
template<class T> valarray<bool> operator>=(const valarray<T>&, const T&);
template<class T> valarray<bool> operator>=(const T&, const valarray<T>&);
template<class T> valarray<bool> operator&&(const valarray<T>&, const T&);
template<class T> valarray<bool> operator&&(const T&, const valarray<T>&);
template<class T> valarray<bool> operator||(const valarray<T>&, const T&);
template<class T> valarray<bool> operator||(const T&, const valarray<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
Each of these operators may only be instantiated for a type \tcode{T}
to which the indicated operator can be applied and for which
the indicated operator returns a value which is of type \tcode{bool}
or which can be unambiguously implicitly converted to type \tcode{bool}.

\pnum
Each of these operators returns a \tcode{bool} array whose
length is equal to the length of the array argument.
Each element
of the returned array is initialized with the result of applying the
indicated operator to the corresponding element of the array and the non-array argument.
\end{itemdescr}

\rSec3[valarray.transcend]{\tcode{valarray} transcendentals}

\indexlibrary{\idxcode{abs}}%
\indexlibrary{\idxcode{acos}}%
\indexlibrary{\idxcode{asin}}%
\indexlibrary{\idxcode{atan}}%
\indexlibrary{\idxcode{atan2}}%
\indexlibrary{\idxcode{cos}}%
\indexlibrary{\idxcode{cosh}}%
\indexlibrary{\idxcode{exp}}%
\indexlibrary{\idxcode{log}}%
\indexlibrary{\idxcode{log10}}%
\indexlibrary{\idxcode{pow}}%
\indexlibrary{\idxcode{sin}}%
\indexlibrary{\idxcode{sinh}}%
\indexlibrary{\idxcode{sqrt}}%
\indexlibrary{\idxcode{tan}}%
\indexlibrary{\idxcode{tanh}}%
\begin{itemdecl}
template<class T> valarray<T> abs  (const valarray<T>&);
template<class T> valarray<T> acos (const valarray<T>&);
template<class T> valarray<T> asin (const valarray<T>&);
template<class T> valarray<T> atan (const valarray<T>&);
template<class T> valarray<T> atan2
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> atan2(const valarray<T>&, const T&);
template<class T> valarray<T> atan2(const T&, const valarray<T>&);
template<class T> valarray<T> cos  (const valarray<T>&);
template<class T> valarray<T> cosh (const valarray<T>&);
template<class T> valarray<T> exp  (const valarray<T>&);
template<class T> valarray<T> log  (const valarray<T>&);
template<class T> valarray<T> log10(const valarray<T>&);
template<class T> valarray<T> pow
    (const valarray<T>&, const valarray<T>&);
template<class T> valarray<T> pow  (const valarray<T>&, const T&);
template<class T> valarray<T> pow  (const T&, const valarray<T>&);
template<class T> valarray<T> sin  (const valarray<T>&);
template<class T> valarray<T> sinh (const valarray<T>&);
template<class T> valarray<T> sqrt (const valarray<T>&);
template<class T> valarray<T> tan  (const valarray<T>&);
template<class T> valarray<T> tanh (const valarray<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
Each of these functions may only be instantiated for a type \tcode{T}
to which a unique function with the indicated name can be applied (unqualified).
This function shall return a value which is of type \tcode{T}
or which can be unambiguously implicitly converted to type \tcode{T}.
\end{itemdescr}

\rSec3[valarray.special]{\tcode{valarray} specialized algorithms}

\indexlibrary{\idxcode{swap}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{swap}}%
\begin{itemdecl}
template <class T> void swap(valarray<T>& x, valarray<T>& y) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects \tcode{x.swap(y)}.
\end{itemdescr}


\rSec2[class.slice]{Class \tcode{slice}}

\rSec3[class.slice.overview]{Class \tcode{slice} overview}

\indexlibrary{\idxcode{slice}}%
\begin{codeblock}
namespace std {
  class slice {
  public:
    slice();
    slice(size_t, size_t, size_t);

    size_t start() const;
    size_t size() const;
    size_t stride() const;
  };
}
\end{codeblock}

\pnum
The
\tcode{slice}
class represents a BLAS-like slice from an array.
Such a slice is specified by a starting index, a length, and a
stride.\footnote{BLAS stands for
\textit{Basic Linear Algebra Subprograms.}
\Cpp programs may instantiate this class.
See, for example,
Dongarra, Du Croz, Duff, and Hammerling:
\textit{A set of Level 3 Basic Linear Algebra Subprograms};
Technical Report MCS-P1-0888,
Argonne National Laboratory (USA),
Mathematics and Computer Science Division,
August, 1988.}

\rSec3[cons.slice]{\tcode{slice} constructors}

\indexlibrary{\idxcode{slice}!\idxcode{slice}}%
\begin{itemdecl}
slice();
slice(size_t start, size_t length, size_t stride);
slice(const slice&);
\end{itemdecl}

\begin{itemdescr}
\pnum
The default constructor is equivalent to \tcode{slice(0, 0, 0)}.
A default constructor is provided only to permit the declaration of arrays of slices.
The constructor with arguments for a slice takes a start, length, and stride
parameter.

\pnum
\enterexample
\tcode{slice(3, 8, 2)}
constructs a slice which selects elements 3, 5, 7, ... 17 from an array.
\exitexample
\end{itemdescr}

\rSec3[slice.access]{\tcode{slice} access functions}
\indexlibrary{\idxcode{start}!\idxcode{slice}}%
\indexlibrary{\idxcode{size}!\idxcode{slice}}%
\indexlibrary{\idxcode{stride}!\idxcode{slice}}%
\begin{itemdecl}
size_t start() const;
size_t size() const;
size_t stride() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns The start, length, or stride specified
by a \tcode{slice} object.

\pnum
\complexity constant time.
\end{itemdescr}

\rSec2[template.slice.array]{Class template \tcode{slice_array}}

\rSec3[template.slice.array.overview]{Class template \tcode{slice_array} overview}

\indexlibrary{\idxcode{slice_array}}%
\begin{codeblock}
namespace std {
  template <class T> class slice_array {
  public:
    typedef T value_type;

    void operator=  (const valarray<T>&) const;
    void operator*= (const valarray<T>&) const;
    void operator/= (const valarray<T>&) const;
    void operator%= (const valarray<T>&) const;
    void operator+= (const valarray<T>&) const;
    void operator-= (const valarray<T>&) const;
    void operator^= (const valarray<T>&) const;
    void operator&= (const valarray<T>&) const;
    void operator|= (const valarray<T>&) const;
    void operator<<=(const valarray<T>&) const;
    void operator>>=(const valarray<T>&) const;

    slice_array(const slice_array&);
    ~slice_array();
    const slice_array& operator=(const slice_array&) const;
  void operator=(const T&) const;

    slice_array() = delete;       // as implied by declaring copy constructor above
  };
}
\end{codeblock}

\pnum
The
\tcode{slice_array}
template is a helper template used by the
\tcode{slice}
subscript operator

\begin{codeblock}
slice_array<T> valarray<T>::operator[](slice);
\end{codeblock}

It has reference semantics to a subset of an array specified by a
\tcode{slice}
object.

\pnum
\enterexample
The expression
\tcode{a[slice(1, 5, 3)] = b;}
has the effect of assigning the elements of
\tcode{b}
to a slice of the elements in
\tcode{a}.
For the slice shown, the elements
selected from
\tcode{a}
are 1, 4, ..., 13.
\exitexample

\rSec3[slice.arr.assign]{\tcode{slice_array} assignment}

\indexlibrary{\idxcode{operator=}!\idxcode{slice_array}}%
\begin{itemdecl}
void operator=(const valarray<T>&) const;
const slice_array& operator=(const slice_array&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
These assignment operators have reference semantics,
assigning the values of the argument array elements to selected
elements of the
\tcode{valarray<T>}
object to which the
\tcode{slice_array}
object refers.
\end{itemdescr}

\rSec3[slice.arr.comp.assign]{\tcode{slice_array} computed assignment}

\indexlibrary{\idxcode{operator*=}!\idxcode{slice_array}}%
\indexlibrary{\idxcode{operator/=}!\idxcode{slice_array}}%
\indexlibrary{\idxcode{operator\%=}!\idxcode{slice_array}}%
\indexlibrary{\idxcode{operator+=}!\idxcode{slice_array}}%
\indexlibrary{\idxcode{operator-=}!\idxcode{slice_array}}%
\indexlibrary{\idxcode{operator\^{}=}!\idxcode{slice_array}}%
\indexlibrary{\idxcode{operator\&=}!\idxcode{slice_array}}%
\indexlibrary{\idxcode{operator"|=}!\idxcode{slice_array}}%
\indexlibrary{\idxcode{operator\shl=}!\idxcode{slice_array}}%
\indexlibrary{\idxcode{operator\shr=}!\idxcode{slice_array}}%
\begin{itemdecl}
void operator*= (const valarray<T>&) const;
void operator/= (const valarray<T>&) const;
void operator%= (const valarray<T>&) const;
void operator+= (const valarray<T>&) const;
void operator-= (const valarray<T>&) const;
void operator^= (const valarray<T>&) const;
void operator&= (const valarray<T>&) const;
void operator|= (const valarray<T>&) const;
void operator<<=(const valarray<T>&) const;
void operator>>=(const valarray<T>&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
These computed assignments have reference semantics, applying the
indicated operation to the elements of the argument array
and selected elements of the
\tcode{valarray<T>}
object to which the
\tcode{slice_array}
object refers.
\end{itemdescr}

\rSec3[slice.arr.fill]{\tcode{slice_array} fill function}

\indexlibrary{\idxcode{fill}!\idxcode{slice_array}}%
\begin{itemdecl}
void operator=(const T&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
This function has reference semantics, assigning the value of its argument
to the elements of the
\tcode{valarray<T>}
object to which the
\tcode{slice_array}
object refers.
\end{itemdescr}

\rSec2[class.gslice]{The \tcode{gslice} class}

\rSec3[class.gslice.overview]{The \tcode{gslice} class overview}

\indexlibrary{\idxcode{gslice}}%
\begin{codeblock}
namespace std {
  class gslice {
  public:
    gslice();
    gslice(size_t s, const valarray<size_t>& l, const valarray<size_t>& d);

    size_t           start() const;
    valarray<size_t> size() const;
    valarray<size_t> stride() const;
  };
}
\end{codeblock}

\pnum
This class represents a generalized slice out of an array.
A
\tcode{gslice}
is defined by a starting offset ($s$),
a set of lengths ($l_j$),
and a set of strides ($d_j$).
The number of lengths shall equal the number of strides.

\pnum
A
\tcode{gslice}
represents a mapping from a set of indices ($i_j$),
equal in number to the number of strides, to a single index $k$.
It is useful for building multidimensional array classes using
the
\tcode{valarray}
template, which is one-dimensional.
The set of one-dimensional index values specified by a
\tcode{gslice}
are $$k = s + \sum_ji_jd_j$$
% \$k = s + sum from j \{ i sub j d sub j \}\$
where the multidimensional indices $i_j$ range in value from
0 to $l_{ij} - 1$.

\pnum
\enterexample
The
\tcode{gslice}
specification
\begin{codeblock}
start  = 3
length = {2, 4, 3}
stride = {19, 4, 1}
\end{codeblock}
yields the sequence of one-dimensional indices

$$k = 3 + (0,1) \times 19 + (0,1,2,3) \times 4 + (0,1,2) \times 1$$

which are ordered as shown in the following table:

\begin{tabbing}
\hspace{.5in}\=\hspace{.4in}\=\kill%
\>$(i_0,\quad i_1,\quad i_2,\quad k)\quad =$\\
\>\>$(0,\quad 0,\quad 0,\quad \ 3)$,    \\
\>\>$(0,\quad 0,\quad 1,\quad \ 4)$,    \\
\>\>$(0,\quad 0,\quad 2,\quad \ 5)$,    \\
\>\>$(0,\quad 1,\quad 0,\quad \ 7)$,    \\
\>\>$(0,\quad 1,\quad 1,\quad \ 8)$,    \\
\>\>$(0,\quad 1,\quad 2,\quad \ 9)$,    \\
\>\>$(0,\quad 2,\quad 0,\quad 11)$, \\
\>\>$(0,\quad 2,\quad 1,\quad 12)$, \\
\>\>$(0,\quad 2,\quad 2,\quad 13)$, \\
\>\>$(0,\quad 3,\quad 0,\quad 15)$, \\
\>\>$(0,\quad 3,\quad 1,\quad 16)$, \\
\>\>$(0,\quad 3,\quad 2,\quad 17)$, \\
\>\>$(1,\quad 0,\quad 0,\quad 22)$, \\
\>\>$(1,\quad 0,\quad 1,\quad 23)$, \\
\>\>$\ldots$      \\
\>\>$(1,\quad 3,\quad 2,\quad 36)$
\end{tabbing}

That is, the highest-ordered index turns fastest.
\exitexample

\pnum
It is possible to have degenerate generalized slices in which an address
is repeated.

\pnum
\enterexample
If the stride parameters in the previous
example are changed to \{1, 1, 1\}, the first few elements of the
resulting sequence of indices will be

\begin{tabbing}
\hspace{.9in}\=\kill%
\>$(0,\quad 0,\quad 0,\quad \ 3)$,  \\
\>$(0,\quad 0,\quad 1,\quad \ 4)$,  \\
\>$(0,\quad 0,\quad 2,\quad \ 5)$,  \\
\>$(0,\quad 1,\quad 0,\quad \ 4)$,  \\
\>$(0,\quad 1,\quad 1,\quad \ 5)$,  \\
\>$(0,\quad 1,\quad 2,\quad \ 6)$,  \\
\>$\ldots$
\end{tabbing}
\exitexample

\pnum
If a degenerate slice is used as the argument to the
non-\tcode{const}
version of
\tcode{operator[](const gslice\&)},
the resulting behavior is undefined.
\indextext{undefined}%

\rSec3[gslice.cons]{\tcode{gslice} constructors}

\indexlibrary{\idxcode{gslice}!constructor}%
\begin{itemdecl}
gslice();
gslice(size_t start, const valarray<size_t>& lengths,
         const valarray<size_t>& strides);
gslice(const gslice&);
\end{itemdecl}

\begin{itemdescr}
\pnum
The default constructor is equivalent to
\tcode{gslice(0, valarray<size_t>(), valarray<size_t>())}.
The constructor with arguments builds a
\tcode{gslice}
based on a specification of start, lengths, and strides, as explained
in the previous section.
\end{itemdescr}

\rSec3[gslice.access]{\tcode{gslice} access functions}

\indexlibrary{\idxcode{start}!\idxcode{gslice}}%
\indexlibrary{\idxcode{size}!\idxcode{gslice}}%
\indexlibrary{\idxcode{stride}!\idxcode{gslice}}%
\begin{itemdecl}
size_t           start()  const;
valarray<size_t> size() const;
valarray<size_t> stride() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns The representation of the
start, lengths, or strides specified for the \tcode{gslice}.

\pnum
\complexity \tcode{start()} is constant time. \tcode{size()} and \tcode{stride()}
are linear in the number of strides.
\end{itemdescr}

\rSec2[template.gslice.array]{Class template \tcode{gslice_array}}

\rSec3[template.gslice.array.overview]{Class template \tcode{gslice_array} overview}

\indexlibrary{\idxcode{gslice_array}}%
\begin{codeblock}
namespace std {
  template <class T> class gslice_array {
  public:
    typedef T value_type;

    void operator=  (const valarray<T>&) const;
    void operator*= (const valarray<T>&) const;
    void operator/= (const valarray<T>&) const;
    void operator%= (const valarray<T>&) const;
    void operator+= (const valarray<T>&) const;
    void operator-= (const valarray<T>&) const;
    void operator^= (const valarray<T>&) const;
    void operator&= (const valarray<T>&) const;
    void operator|= (const valarray<T>&) const;
    void operator<<=(const valarray<T>&) const;
    void operator>>=(const valarray<T>&) const;

    gslice_array(const gslice_array&);
    ~gslice_array();
    const gslice_array& operator=(const gslice_array&) const;
    void operator=(const T&) const;

    gslice_array() = delete;      // as implied by declaring copy constructor above
  };
}
\end{codeblock}

\pnum
This template is a helper template used by the
\tcode{slice}
subscript operator

\indexlibrary{\idxcode{gslice_array}}%
\indexlibrary{\idxcode{valarray}}%
\begin{itemdecl}
gslice_array<T> valarray<T>::operator[](const gslice&);
\end{itemdecl}

\begin{itemdescr}
\pnum
It has reference semantics to a subset of an array specified by a
\tcode{gslice}
object.

\pnum
Thus, the expression
\tcode{a[gslice(1, length, stride)] = b}
has the effect of assigning the elements of
\tcode{b}
to a
generalized slice of the elements in
\tcode{a}.
\end{itemdescr}

\rSec3[gslice.array.assign]{\tcode{gslice_array} assignment}

\indexlibrary{\idxcode{operator=}!\idxcode{gslice_array}}%
\begin{itemdecl}
void operator=(const valarray<T>&) const;
const gslice_array& operator=(const gslice_array&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
These assignment operators have reference semantics, assigning the values
of the argument array elements to selected elements of the
\tcode{valarray<T>}
object to which the
\tcode{gslice_array}
refers.
\end{itemdescr}

\rSec3[gslice.array.comp.assign]{\tcode{gslice_array}}

\indexlibrary{\idxcode{operator*=}!\idxcode{gslice_array}}%
\indexlibrary{\idxcode{operator/=}!\idxcode{gslice_array}}%
\indexlibrary{\idxcode{operator\%=}!\idxcode{gslice_array}}%
\indexlibrary{\idxcode{operator+=}!\idxcode{gslice_array}}%
\indexlibrary{\idxcode{operator-=}!\idxcode{gslice_array}}%
\indexlibrary{\idxcode{operator\^{}=}!\idxcode{gslice_array}}%
\indexlibrary{\idxcode{operator\&=}!\idxcode{gslice_array}}%
\indexlibrary{\idxcode{operator"|=}!\idxcode{gslice_array}}%
\indexlibrary{\idxcode{operator\shl=}!\idxcode{gslice_array}}%
\indexlibrary{\idxcode{operator\shr=}!\idxcode{gslice_array}}%
\begin{itemdecl}
void operator*= (const valarray<T>&) const;
void operator/= (const valarray<T>&) const;
void operator%= (const valarray<T>&) const;
void operator+= (const valarray<T>&) const;
void operator-= (const valarray<T>&) const;
void operator^= (const valarray<T>&) const;
void operator&= (const valarray<T>&) const;
void operator|= (const valarray<T>&) const;
void operator<<=(const valarray<T>&) const;
void operator>>=(const valarray<T>&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
These computed assignments have reference semantics, applying the
indicated operation to the elements of the argument array and selected
elements of the
\tcode{valarray<T>}
object to which the
\tcode{gslice_array}
object refers.
\end{itemdescr}

\rSec3[gslice.array.fill]{\tcode{gslice_array} fill function}

\indexlibrary{\idxcode{fill}!\idxcode{gslice_array}}%
\begin{itemdecl}
void operator=(const T&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
This function has reference semantics, assigning the value of its argument
to the elements of the
\tcode{valarray<T>}
object to which the
\tcode{gslice_array}
object refers.
\end{itemdescr}

\rSec2[template.mask.array]{Class template \tcode{mask_array}}

\rSec3[template.mask.array.overview]{Class template \tcode{mask_array} overview}

\indexlibrary{\idxcode{mask_array}}%
\begin{codeblock}
namespace std {
  template <class T> class mask_array {
  public:
    typedef T value_type;

    void operator=  (const valarray<T>&) const;
    void operator*= (const valarray<T>&) const;
    void operator/= (const valarray<T>&) const;
    void operator%= (const valarray<T>&) const;
    void operator+= (const valarray<T>&) const;
    void operator-= (const valarray<T>&) const;
    void operator^= (const valarray<T>&) const;
    void operator&= (const valarray<T>&) const;
    void operator|= (const valarray<T>&) const;
    void operator<<=(const valarray<T>&) const;
    void operator>>=(const valarray<T>&) const;

    mask_array(const mask_array&);
   ~mask_array();
    const mask_array& operator=(const mask_array&) const;
    void operator=(const T&) const;

    mask_array() = delete;        // as implied by declaring copy constructor above
  };
}
\end{codeblock}

\pnum
This template is a helper template used by the mask subscript operator:

\indexlibrary{\idxcode{operator[]}!\idxcode{mask_array}}%
\indexlibrary{\idxcode{mask_array}!\idxcode{operator[]}}%
\begin{itemdecl}
mask_array<T> valarray<T>::operator[](const valarray<bool>&).
\end{itemdecl}

\begin{itemdescr}
\pnum
It has reference semantics to a subset of an array specified by a boolean mask.
Thus, the expression
\tcode{a[mask] = b;}
has the effect of assigning the elements of
\tcode{b}
to the masked
elements in
\tcode{a}
(those for which the corresponding element
in
\tcode{mask}
is
\tcode{true}.)
\end{itemdescr}

\rSec3[mask.array.assign]{\tcode{mask_array} assignment}

\indexlibrary{\idxcode{operator=}!\idxcode{mask_array}}%
\begin{itemdecl}
void operator=(const valarray<T>&) const;
const mask_array& operator=(const mask_array&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
These assignment operators have reference semantics, assigning the values
of the argument array elements to selected elements of the
\tcode{valarray<T>}
object to which it refers.
\end{itemdescr}

\rSec3[mask.array.comp.assign]{\tcode{mask_array} computed assignment}

\indexlibrary{\idxcode{operator*=}!\idxcode{mask_array}}%
\indexlibrary{\idxcode{operator/=}!\idxcode{mask_array}}%
\indexlibrary{\idxcode{operator\%=}!\idxcode{mask_array}}%
\indexlibrary{\idxcode{operator+=}!\idxcode{mask_array}}%
\indexlibrary{\idxcode{operator-=}!\idxcode{mask_array}}%
\indexlibrary{\idxcode{operator\^{}=}!\idxcode{mask_array}}%
\indexlibrary{\idxcode{operator\&=}!\idxcode{mask_array}}%
\indexlibrary{\idxcode{operator"|=}!\idxcode{mask_array}}%
\indexlibrary{\idxcode{operator\shl=}!\idxcode{mask_array}}%
\indexlibrary{\idxcode{operator\shr=}!\idxcode{mask_array}}%
\begin{itemdecl}
void operator*= (const valarray<T>&) const;
void operator/= (const valarray<T>&) const;
void operator%= (const valarray<T>&) const;
void operator+= (const valarray<T>&) const;
void operator-= (const valarray<T>&) const;
void operator^= (const valarray<T>&) const;
void operator&= (const valarray<T>&) const;
void operator|= (const valarray<T>&) const;
void operator<<=(const valarray<T>&) const;
void operator>>=(const valarray<T>&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
These computed assignments have reference semantics, applying the
indicated operation to the elements of the argument array and selected elements
of the
\tcode{valarray<T>}
object to which the mask object refers.
\end{itemdescr}

\rSec3[mask.array.fill]{\tcode{mask_array} fill function}

\indexlibrary{\idxcode{fill}!\idxcode{mask_array}}%
\begin{itemdecl}
void operator=(const T&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
This function has reference semantics, assigning the value of its
argument to the elements of the
\tcode{valarray<T>}
object to which the
\tcode{mask_array}
object refers.
\end{itemdescr}

\rSec2[template.indirect.array]{Class template \tcode{indirect_array}}

\rSec3[template.indirect.array.overview]{Class template \tcode{indirect_array} overview}

\indexlibrary{\idxcode{indirect_array}}%
\begin{codeblock}
namespace std {
  template <class T> class indirect_array {
  public:
    typedef T value_type;

    void operator=  (const valarray<T>&) const;
    void operator*= (const valarray<T>&) const;
    void operator/= (const valarray<T>&) const;
    void operator%= (const valarray<T>&) const;
    void operator+= (const valarray<T>&) const;
    void operator-= (const valarray<T>&) const;
    void operator^= (const valarray<T>&) const;
    void operator&= (const valarray<T>&) const;
    void operator|= (const valarray<T>&) const;
    void operator<<=(const valarray<T>&) const;
    void operator>>=(const valarray<T>&) const;

    indirect_array(const indirect_array&);
   ~indirect_array();
    const indirect_array& operator=(const indirect_array&) const;
    void operator=(const T&) const;

    indirect_array() = delete;        // as implied by declaring copy constructor above
  };
}
\end{codeblock}

\pnum
This template is a helper template used by the indirect subscript operator

\indexlibrary{\idxcode{operator[]}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{indirect_array}!\idxcode{operator[]}}%
\begin{itemdecl}
indirect_array<T> valarray<T>::operator[](const valarray<size_t>&).
\end{itemdecl}

\begin{itemdescr}
\pnum
It has reference semantics to a subset of an array specified by an
\tcode{indirect_array}.
Thus the expression
\tcode{a[\brk{}indirect] = b;}
has the effect of assigning the elements of
\tcode{b}
to the elements in
\tcode{a}
whose indices appear in
\tcode{indirect}.
\end{itemdescr}

\rSec3[indirect.array.assign]{\tcode{indirect_array} assignment}

\indexlibrary{\idxcode{operator=}!\idxcode{indirect_array}}%
\begin{itemdecl}
void operator=(const valarray<T>&) const;
const indirect_array& operator=(const indirect_array&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
These assignment operators have reference semantics, assigning the values
of the argument array elements to selected elements of the
\tcode{valarray<T>}
object to which it refers.

\pnum
If the
\tcode{indirect_array}
specifies an element in the
\tcode{valarray<T>}
object to which it refers more than once, the behavior is undefined.
\indextext{undefined}%

\pnum
\enterexample
\begin{codeblock}
int addr[] = {2, 3, 1, 4, 4};
valarray<size_t> indirect(addr, 5);
valarray<double> a(0., 10), b(1., 5);
a[indirect] = b;
\end{codeblock}
results in undefined behavior since element 4 is specified twice in the
indirection.
\exitexample
\end{itemdescr}

\rSec3[indirect.array.comp.assign]{\tcode{indirect_array} computed assignment}

\indexlibrary{\idxcode{operator*=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator*=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator*=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator/=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator\%=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator+=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator-=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator\^{}=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator\&=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator"|=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator\shl=}!\idxcode{indirect_array}}%
\indexlibrary{\idxcode{operator\shr=}!\idxcode{indirect_array}}%
\begin{itemdecl}
void operator*= (const valarray<T>&) const;
void operator/= (const valarray<T>&) const;
void operator%= (const valarray<T>&) const;
void operator+= (const valarray<T>&) const;
void operator-= (const valarray<T>&) const;
void operator^= (const valarray<T>&) const;
void operator&= (const valarray<T>&) const;
void operator|= (const valarray<T>&) const;
void operator<<=(const valarray<T>&) const;
void operator>>=(const valarray<T>&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
These computed assignments have reference semantics, applying the indicated
operation to the elements of the argument array and selected elements of the
\tcode{valarray<T>}
object to which the
\tcode{indirect_array}
object refers.

\pnum
If the
\tcode{indirect_array}
specifies an element in the
\tcode{valarray<T>}
object to which it refers more than once,
the behavior is undefined.
\indextext{undefined}
\end{itemdescr}

\rSec3[indirect.array.fill]{\tcode{indirect_array} fill function}

\indexlibrary{\idxcode{fill}!\idxcode{indirect_array}}%
\begin{itemdecl}
void operator=(const T&) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
This function has reference semantics, assigning the value of its argument
to the elements of the
\tcode{valarray<T>}
object to which the
\tcode{indirect_array}
object refers.
\end{itemdescr}

\rSec2[valarray.range]{valarray range access}

\pnum
In the \tcode{begin} and \tcode{end} function templates that follow, \unspec{1}
is a type that meets the requirements of a mutable random access
iterator~(\ref{random.access.iterators}) whose \tcode{value_type} is the template
parameter \tcode{T} and whose \tcode{reference} type is \tcode{T\&}. \unspec{2} is a
type that meets the requirements of a constant random access
iterator~(\ref{random.access.iterators}) whose \tcode{value_type} is the template
parameter \tcode{T} and whose \tcode{reference} type is \tcode{const T\&}.

\pnum
The iterators returned by \tcode{begin} and \tcode{end} for an array
are guaranteed to be valid until the member function
\tcode{resize(size_t, T)}~(\ref{valarray.members}) is called for that
array or until the lifetime of that array ends, whichever happens
first.

\indexlibrary{\idxcode{begin}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{begin}}%
\begin{itemdecl}
template <class T> @\unspec{1}@ begin(valarray<T>& v);
template <class T> @\unspec{2}@ begin(const valarray<T>& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An iterator referencing the first value in the numeric array.
\end{itemdescr}

\indexlibrary{\idxcode{end}!\idxcode{valarray}}%
\indexlibrary{\idxcode{valarray}!\idxcode{end}}%
\begin{itemdecl}
template <class T> @\unspec{1}@ end(valarray<T>& v);
template <class T> @\unspec{2}@ end(const valarray<T>& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns An iterator referencing one past the last value in the numeric array.
\end{itemdescr}


\rSec1[numeric.ops]{Generalized numeric operations}

\rSec2[numeric.ops.overview]{Header \tcode{<numeric>} synopsis}

\indexlibrary{\idxhdr{numeric}}%
\begin{codeblock}
namespace std {
  template <class InputIterator, class T>
    T accumulate(InputIterator first, InputIterator last, T init);
  template <class InputIterator, class T, class BinaryOperation>
    T accumulate(InputIterator first, InputIterator last, T init,
                 BinaryOperation binary_op);

  template <class InputIterator1, class InputIterator2, class T>
    T inner_product(InputIterator1 first1, InputIterator1 last1,
                    InputIterator2 first2, T init);
  template <class InputIterator1, class InputIterator2, class T,
            class BinaryOperation1, class BinaryOperation2>
    T inner_product(InputIterator1 first1, InputIterator1 last1,
                    InputIterator2 first2, T init,
                    BinaryOperation1 binary_op1,
                    BinaryOperation2 binary_op2);

  template <class InputIterator, class OutputIterator>
    OutputIterator partial_sum(InputIterator first,
                               InputIterator last,
                               OutputIterator result);
  template <class InputIterator, class OutputIterator,
            class BinaryOperation>
    OutputIterator partial_sum(InputIterator first,
                               InputIterator last,
                               OutputIterator result,
                               BinaryOperation binary_op);

  template <class InputIterator, class OutputIterator>
    OutputIterator adjacent_difference(InputIterator first,
                                       InputIterator last,
                                       OutputIterator result);
  template <class InputIterator, class OutputIterator,
            class BinaryOperation>
    OutputIterator adjacent_difference(InputIterator first,
                                       InputIterator last,
                                       OutputIterator result,
                                       BinaryOperation binary_op);

  template <class ForwardIterator, class T>
    void iota(ForwardIterator first, ForwardIterator last, T value);
}
\end{codeblock}

\pnum
The requirements on the types of algorithms' arguments that are
described in the introduction to Clause~\ref{algorithms} also
apply to the following algorithms.

\rSec2[accumulate]{Accumulate}

\indexlibrary{\idxcode{accumulate}}%
\begin{itemdecl}
template <class InputIterator, class T>
  T accumulate(InputIterator first, InputIterator last, T init);
template <class InputIterator, class T, class BinaryOperation>
  T accumulate(InputIterator first, InputIterator last, T init,
               BinaryOperation binary_op);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Computes its result by initializing the accumulator
\tcode{acc}
with the initial value
\tcode{init}
and then modifies it with
\tcode{acc = acc + *i}
or
\tcode{acc = binary_op(acc, *i)}
for every iterator
\tcode{i}
in the range \range{first}{last}
in order.\footnote{\tcode{accumulate}
is similar to the APL reduction operator and Common Lisp reduce function, but
it avoids the difficulty of defining the result of reduction on an empty
sequence by always requiring an initial value.}

\pnum
\requires
\tcode{T} shall meet the requirements of \tcode{CopyConstructible} (Table~\ref{copyconstructible})
and \tcode{CopyAssignable} (Table~\ref{copyassignable}) types.
In the range
\crange{first}{last},
\tcode{binary_op}
shall neither modify elements nor invalidate iterators or subranges.\footnote{The use of fully closed ranges is intentional
}
\end{itemdescr}

\rSec2[inner.product]{Inner product}
\indexlibrary{\idxcode{inner_product}}%

\indexlibrary{\idxcode{inner_product}}%
\begin{itemdecl}
template <class InputIterator1, class InputIterator2, class T>
  T inner_product(InputIterator1 first1, InputIterator1 last1,
                  InputIterator2 first2, T init);
template <class InputIterator1, class InputIterator2, class T,
    class BinaryOperation1, class BinaryOperation2>
  T inner_product(InputIterator1 first1, InputIterator1 last1,
                  InputIterator2 first2, T init,
                  BinaryOperation1 binary_op1,
                  BinaryOperation2 binary_op2);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Computes its result by initializing the accumulator
\tcode{acc}
with the initial value
\tcode{init}
and then modifying it with
\tcode{acc = acc + (*i1) * (*i2)}
or
\tcode{acc = binary_op1(acc, binary_op2(*i1, *i2))}
for every iterator
\tcode{i1}
in the range \range{first1}{last1}
and iterator
\tcode{i2}
in the range
\range{first2}{first2 + (last1 - first1)}
in order.

\pnum
\requires
\tcode{T} shall meet the requirements of \tcode{CopyConstructible} (Table~\ref{copyconstructible})
and \tcode{CopyAssignable} (Table~\ref{copyassignable}) types.
In the ranges
\crange{first1}{last1}
and
\crange{first2}{first2 + (last1 - first1)}
\tcode{binary_op1}
and
\tcode{binary_op2}
shall neither modify elements nor invalidate iterators or subranges.\footnote{The use of fully closed ranges is intentional
}
\end{itemdescr}

\rSec2[partial.sum]{Partial sum}

\indexlibrary{\idxcode{partial_sum}}%
\begin{itemdecl}
template <class InputIterator, class OutputIterator>
  OutputIterator partial_sum(
    InputIterator first, InputIterator last,
    OutputIterator result);
template
  <class InputIterator, class OutputIterator, class BinaryOperation>
    OutputIterator partial_sum(
      InputIterator first, InputIterator last,
      OutputIterator result, BinaryOperation binary_op);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects For a non-empty range,
the function creates an accumulator \tcode{acc} whose type is \tcode{InputIterator}'s
value type, initializes it with \tcode{*first},
and assigns the result to \tcode{*result}. For every iterator \tcode{i} in \range{first + 1}{last}
in order, \tcode{acc} is then modified by \tcode{acc = acc + *i} or \tcode{acc = binary_op(acc, *i)}
and the result is assigned to \tcode{*(result + (i - first))}.

\pnum
\returns
\tcode{result + (last - first)}.

\pnum
\complexity
Exactly
\tcode{(last - first) - 1}
applications of
the binary operation.

\pnum
\requires
\tcode{InputIterator}'s value type shall be constructible from the type of \tcode{*first}.
The result of the expression \tcode{acc + *i} or \tcode{binary_op(acc, *i)} shall be
implicitly convertible to \tcode{InputIterator}'s value type. \tcode{acc}
shall be writable to the \tcode{result} output iterator.
In the ranges
\crange{first}{last}
and
\mbox{\crange{result}{result + (last - first)}}
\tcode{binary_op}
shall neither modify elements nor invalidate iterators or subranges.\footnote{The use of fully closed ranges is intentional.
}

\pnum
\notes
\tcode{result}
may be equal to
\tcode{first}.
\end{itemdescr}

\rSec2[adjacent.difference]{Adjacent difference}

\indexlibrary{\idxcode{adjacent_difference}}%
\begin{itemdecl}
template <class InputIterator, class OutputIterator>
  OutputIterator adjacent_difference(
    InputIterator first, InputIterator last,
    OutputIterator result);
template <class InputIterator, class OutputIterator, class BinaryOperation>
  OutputIterator adjacent_difference(
    InputIterator first, InputIterator last,
    OutputIterator result,
    BinaryOperation binary_op);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects For a non-empty range,
the function creates an accumulator \tcode{acc} whose type is \tcode{InputIterator}'s
value type, initializes it with \tcode{*first},
and assigns the result to \tcode{*result}. For every iterator \tcode{i} in \range{first + 1}{last}
in order, creates an object \tcode{val} whose type is \tcode{InputIterator}'s value type, initializes it
with *i, computes \tcode{val - acc} or \tcode{binary_op(val, acc)}, assigns the result
to \tcode{*(result + (i - first))}, and move assigns from \tcode{val} to \tcode{acc}.

\pnum
\requires
\tcode{InputIterator}'s value type shall be \tcode{MoveAssignable} (Table~\ref{moveassignable})
and shall be constructible from the type of \tcode{*first}. \tcode{acc} shall be
writable to the \tcode{result} output iterator. The result of the expression \tcode{val - acc}
or \tcode{binary_op(val, acc)} shall be writable to the \tcode{result} output iterator.
In the ranges
\crange{first}{last}
and
\crange{result}{result + (last - first)},
\tcode{binary_op}
shall neither modify elements nor invalidate iterators or
subranges.\footnote{The use of fully closed ranges is intentional.}

\pnum
\notes
\tcode{result}
may be equal to
\tcode{first}.

\pnum
\returns
\tcode{result + (last - first)}.

\pnum
\complexity
Exactly
\tcode{(last - first) - 1}
applications of
the binary operation.
\end{itemdescr}

\rSec2[numeric.iota]{Iota}

\indexlibrary{\idxcode{iota}}%
\begin{itemdecl}
template <class ForwardIterator, class T>
  void iota(ForwardIterator first, ForwardIterator last, T value);
\end{itemdecl}

\begin{itemdescr}
\pnum
\requires \tcode{T} shall be convertible to \tcode{ForwardIterator}'s value
type. The expression \tcode{++val}, where \tcode{val} has type \tcode{T}, shall
be well formed.

\pnum
\effects For each element referred to by the iterator \tcode{i} in the range
\range{first}{last}, assigns \tcode{*i = value} and increments \tcode{value} as
if by \tcode{++value}.

\pnum
\complexity Exactly \tcode{last - first} increments and assignments.
\end{itemdescr}


\rSec1[c.math]{C library}

\pnum
\indexlibrary{\idxhdr{ctgmath}}
The header \tcode{<ctgmath>} simply includes the headers \tcode{<ccomplex>}
and \tcode{<cmath>}.

\pnum
\enternote The overloads provided in C by type-generic macros are already
provided in \tcode{<ccomplex>} and \tcode{<cmath>} by ``sufficient'' additional
overloads.\exitnote

\pnum
Tables~\ref{tab:numerics.hdr.cmath} and~\ref{tab:numerics.hdr.cstdlib}
describe headers \tcode{<cmath>}
and \tcode{<cstdlib>},
respectively.

\begin{libsyntab5}{cmath}{tab:numerics.hdr.cmath}
\cspan{\macros} \\

\tcode{FP_FAST_FMA} &
\tcode{FP_ILOGBNAN} &
\tcode{FP_SUBNORMAL} &
\tcode{HUGE_VALL} &
\tcode{MATH_ERRNO} \\

\tcode{FP_FAST_FMAF} &
\tcode{FP_INFINITE} &
\tcode{FP_ZERO} &
\tcode{INFINITY} &
\tcode{MATH_ERREXCEPT} \\

\tcode{FP_FAST_FMAL} &
\tcode{FP_NAN} &
\tcode{HUGE_VAL}&
\tcode{NAN} &
\tcode{math_errhandling} \\

\tcode{FP_ILOGB0} &
\tcode{FP_NORMAL} &
\tcode{HUGE_VALF} &&\\ \rowsep


\types      & \tcode{double_t}&\tcode{float_t}&   &         \\ \rowsep
\cspan{\mfunctions}                                        \\

\tcode{abs}   &
\tcode{cosh}  &
\tcode{fmod}  &
\tcode{logb}  &
\tcode{remquo} \\

\tcode{acos}  &
\tcode{erf} &
\tcode{frexp} &
\tcode{lrint} &
\tcode{rint} \\

\tcode{acosh} &
\tcode{erfc} &
\tcode{hypot} &
\tcode{lround} &
\tcode{round} \\

\tcode{asin}  &
\tcode{exp2} &
\tcode{ilogb} &
\tcode{modf}  &
\tcode{scalbln} \\

\tcode{asinh} &
\tcode{exp}   &
\tcode{ldexp} &
\tcode{nan} &
\tcode{scalbn} \\

\tcode{atan}  &
\tcode{expm1} &
\tcode{lgamma} &
\tcode{nanf} &
\tcode{sin}   \\

\tcode{atan2} &
\tcode{fabs}  &
\tcode{llrint} &
\tcode{nanl} &
\tcode{sinh}  \\

\tcode{atanh} &
\tcode{fdim} &
\tcode{llround} &
\tcode{nearbyint} &
\tcode{sqrt}  \\

\tcode{cbrt} &
\tcode{floor} &
\tcode{log}   &
\tcode{nextafter} &
\tcode{tan}   \\

\tcode{ceil}  &
\tcode{fma} &
\tcode{log10} &
\tcode{nexttoward} &
\tcode{tanh}  \\

\tcode{copysign} &
\tcode{fmax} &
\tcode{log1p} &
\tcode{pow}   &
\tcode{tgamma} \\

\tcode{cos}   &
\tcode{fmin} &
\tcode{log2} &
\tcode{remainder} &
\tcode{trunc} \\ \rowsep

\cspan{\cfunctions} \\

\tcode{fpclassify} &
\tcode{isgreaterequal} &
\tcode{islessequal} &
\tcode{isnan} &
\tcode{isunordered} \\

\tcode{isfinite} &
\tcode{isinf} &
\tcode{islessgreater} &
\tcode{isnormal} &
\tcode{signbit} \\

\tcode{isgreater} &
\tcode{isless} &&&\\
\end{libsyntab5}

\begin{libsyntab3}{cstdlib}{tab:numerics.hdr.cstdlib}
\macro      & \tcode{RAND_MAX}&         \\ \rowsep
\cspan{\types}  \\
\tcode{div_t} & \tcode{ldiv_t}  & \tcode{lldiv_t} \\ \rowsep
\functions    &         &         \\
\tcode{abs}   & \tcode{ldiv}  & \tcode{rand}  \\
\tcode{div}   & \tcode{llabs} & \tcode{srand} \\
\tcode{labs}  & \tcode{lldiv} &\\
\end{libsyntab3}

\pnum
The contents of these headers are the same as the Standard C library headers
\tcode{<math.h>}
and
\tcode{<stdlib.h>}
respectively, with the following changes:

\pnum
The
\tcode{rand}
function has the semantics specified in the C standard, except that the implementation
may specify that particular library functions may call
\tcode{rand}. It is implementation-defined whether the \tcode{rand} function may introduce data races~(\ref{res.on.data.races}). \enternote The random number generation~(\ref{rand}) facilities in this standard are often preferable to \tcode{rand}. \exitnote

\pnum
In addition to the
\tcode{int}
versions of certain math functions in
\tcode{<cstdlib>},
\Cpp adds
\tcode{long} and \tcode{long long}
overloaded versions of these functions, with the same semantics.

\pnum
The added signatures are:
\indexlibrary{\idxcode{abs}}%
\indexlibrary{\idxcode{div}}%
\begin{codeblock}
long abs(long);                     // \tcode{labs()}
long long abs(long long);           // \tcode{llabs()}
ldiv_t div(long, long);             // \tcode{ldiv()}
lldiv_t div(long long, long long);  // \tcode{lldiv()}
\end{codeblock}

\pnum
In addition to the
\tcode{double}
versions of the math functions in
\tcode{<cmath>},
\Cpp adds
\tcode{float}
and
\tcode{long double}
overloaded versions of these functions, with the same semantics.

\pnum
The added signatures are:

\indexlibrary{\idxcode{abs}}%
\indexlibrary{\idxcode{acos}}%
\indexlibrary{\idxcode{acosh}}%
\indexlibrary{\idxcode{asin}}%
\indexlibrary{\idxcode{asinh}}%
\indexlibrary{\idxcode{atan}}%
\indexlibrary{\idxcode{atanh}}%
\indexlibrary{\idxcode{atan2}}%
\indexlibrary{\idxcode{atan}}%
\indexlibrary{\idxcode{cbrt}}%
\indexlibrary{\idxcode{copysign}}%
\indexlibrary{\idxcode{cos}}%
\indexlibrary{\idxcode{cosh}}%
\indexlibrary{\idxcode{erf}}%
\indexlibrary{\idxcode{erfc}}%
\indexlibrary{\idxcode{exp}}%
\indexlibrary{\idxcode{exp}}%
\indexlibrary{\idxcode{exp2}}%
\indexlibrary{\idxcode{expm1}}%
\indexlibrary{\idxcode{fdim}}%
\indexlibrary{\idxcode{floor}}%
\indexlibrary{\idxcode{fma}}%
\indexlibrary{\idxcode{fmax}}%
\indexlibrary{\idxcode{fmin}}%
\indexlibrary{\idxcode{frexp}}%
\indexlibrary{\idxcode{hypot}}%
\indexlibrary{\idxcode{ilogb}}%
\indexlibrary{\idxcode{lgamma}}%
\indexlibrary{\idxcode{llrint}}%
\indexlibrary{\idxcode{llround}}%
\indexlibrary{\idxcode{log}}%
\indexlibrary{\idxcode{log10}}%
\indexlibrary{\idxcode{log1p}}%
\indexlibrary{\idxcode{log2}}%
\indexlibrary{\idxcode{logb}}%
\indexlibrary{\idxcode{lrint}}%
\indexlibrary{\idxcode{lround}}%
\indexlibrary{\idxcode{mod}}%
\indexlibrary{\idxcode{modf}}%
\indexlibrary{\idxcode{nan}}%
\indexlibrary{\idxcode{nearbyint}}%
\indexlibrary{\idxcode{nextafter}}%
\indexlibrary{\idxcode{nexttoward}}%
\indexlibrary{\idxcode{pow}}%
\indexlibrary{\idxcode{pow}}%
\indexlibrary{\idxcode{remainder}}%
\indexlibrary{\idxcode{remquo}}%
\indexlibrary{\idxcode{rint}}%
\indexlibrary{\idxcode{round}}%
\indexlibrary{\idxcode{scalbln}}%
\indexlibrary{\idxcode{scalbn}}%
\indexlibrary{\idxcode{sin}}%
\indexlibrary{\idxcode{sinh}}%
\indexlibrary{\idxcode{sqrt}}%
\indexlibrary{\idxcode{tan}}%
\indexlibrary{\idxcode{tanh}}%
\indexlibrary{\idxcode{tgamma}}%
\indexlibrary{\idxcode{trunc}}%

\begin{codeblock}
float abs(float);
float acos(float);
float acosh(float);
float asin(float);
float asinh(float);
float atan(float);
float atan2(float, float);
float atanh(float);
float cbrt(float);
float ceil(float);
float copysign(float, float);
float cos(float);
float cosh(float);
float erf(float);
float erfc(float);
float exp(float);
float exp2(float);
float expm1(float);
float fabs(float);
float fdim(float, float);
float floor(float);
float fma(float, float, float);
float fmax(float, float);
float fmin(float, float);
float fmod(float, float);
float frexp(float, int*);
float hypot(float, float);
int ilogb(float);
float ldexp(float, int);
float lgamma(float);
long long llrint(float);
long long llround(float);
float log(float);
float log10(float);
float log1p(float);
float log2(float);
float logb(float);
long lrint(float);
long lround(float);
float modf(float, float*);
float nearbyint(float);
float nextafter(float, float);
float nexttoward(float, long double);
float pow(float, float);
float remainder(float, float);
float remquo(float, float, int *);
float rint(float);
float round(float);
float scalbln(float, long);
float scalbn(float, int);
float sin(float);
float sinh(float);
float sqrt(float);
float tan(float);
float tanh(float);
float tgamma(float);
float trunc(float);

double abs(double);            // fabs()

long double abs(long double);
long double acos(long double);
long double acosh(long double);
long double asin(long double);
long double asinh(long double);
long double atan(long double);
long double atan2(long double, long double);
long double atanh(long double);
long double cbrt(long double);
long double ceil(long double);
long double copysign(long double, long double);
long double cos(long double);
long double cosh(long double);
long double erf(long double);
long double erfc(long double);
long double exp(long double);
long double exp2(long double);
long double expm1(long double);
long double fabs(long double);
long double fdim(long double, long double);
long double floor(long double);
long double fma(long double, long double, long double);
long double fmax(long double, long double);
long double fmin(long double, long double);
long double fmod(long double, long double);
long double frexp(long double, int*);
long double hypot(long double, long double);
int ilogb(long double);
long double ldexp(long double, int);
long double lgamma(long double);
long long llrint(long double);
long long llround(long double);
long double log(long double);
long double log10(long double);
long double log1p(long double);
long double log2(long double);
long double logb(long double);
long lrint(long double);
long lround(long double);
long double modf(long double, long double*);
long double nearbyint(long double);
long double nextafter(long double, long double);
long double nexttoward(long double, long double);
long double pow(long double, long double);
long double remainder(long double, long double);
long double remquo(long double, long double, int *);
long double rint(long double);
long double round(long double);
long double scalbln(long double, long);
long double scalbn(long double, int);
long double sin(long double);
long double sinh(long double);
long double sqrt(long double);
long double tan(long double);
long double tanh(long double);
long double tgamma(long double);
long double trunc(long double);
\end{codeblock}

\pnum
The classification/comparison functions behave the same as the C macros with the
corresponding names defined in 7.12.3, Classification macros, and 7.12.14, Comparison
macros in the C Standard. Each function is overloaded for the three floating-point
types, as follows:

\indexlibrary{\idxcode{signbit}}%
\indexlibrary{\idxcode{fpclassify}}%
\indexlibrary{\idxcode{isfinite}}%
\indexlibrary{\idxcode{isinf}}%
\indexlibrary{\idxcode{isnan}}%
\indexlibrary{\idxcode{isnormal}}%
\indexlibrary{\idxcode{isgreater}}%
\indexlibrary{\idxcode{isgreaterequal}}%
\indexlibrary{\idxcode{isless}}%
\indexlibrary{\idxcode{islessequal}}%
\indexlibrary{\idxcode{islessgreater}}%
\indexlibrary{\idxcode{isunordered}}%
\begin{codeblock}
int fpclassify(float x);
bool isfinite(float x);
bool isinf(float x);
bool isnan(float x);
bool isnormal(float x);
bool signbit(float x);

bool isgreater(float x, float y);
bool isgreaterequal(float x, float y);
bool isless(float x, float y);
bool islessequal(float x, float y);
bool islessgreater(float x, float y);
bool isunordered(float x, float y);

int fpclassify(double x);
bool isfinite(double x);
bool isinf(double x);
bool isnan(double x);
bool isnormal(double x);
bool signbit(double x);

bool isgreater(double x, double y);
bool isgreaterequal(double x, double y);
bool isless(double x, double y);
bool islessequal(double x, double y);
bool islessgreater(double x, double y);
bool isunordered(double x, double y);

int fpclassify(long double x);
bool isfinite(long double x);
bool isinf(long double x);
bool isnan(long double x);
bool isnormal(long double x);
bool signbit(long double x);

bool isgreater(long double x, long double y);
bool isgreaterequal(long double x, long double y);
bool isless(long double x, long double y);
bool islessequal(long double x, long double y);
bool islessgreater(long double x, long double y);
bool isunordered(long double x, long double y);
\end{codeblock}

\pnum
Moreover, there shall be additional overloads sufficient to ensure:
\begin{enumerate}
  \item If any arithmetic argument corresponding to a \tcode{double}
    parameter has type \tcode{long double}, then all arithmetic
    arguments corresponding to \tcode{double} parameters are
    effectively cast to \tcode{long double}.
  \item Otherwise, if any arithmetic argument corresponding to a
    \tcode{double} parameter has type \tcode{double} or an integer
    type, then all arithmetic arguments corresponding to
    \tcode{double} parameters are effectively cast to \tcode{double}.
  \item Otherwise, all arithmetic arguments corresponding to 
    \tcode{double} parameters have type \tcode{float}.
\end{enumerate}

\xref
ISO C 7.5, 7.10.2, 7.10.6.