numerics.tex

%!TEX root = std.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
mathematical constants and functions for floating-point types,
as summarized in \tref{numerics.summary}.

\begin{libsumtab}{Numerics library summary}{numerics.summary}
\ref{numeric.requirements}  & Requirements &           \\ \rowsep
\ref{cfenv}           & Floating-point environment & \tcode{<cfenv>}  \\ \rowsep
\ref{complex.numbers} & Complex numbers & \tcode{<complex>} \\ \rowsep
\ref{bit}   & Bit manipulation & \tcode{<bit>} \\ \rowsep
\ref{rand}  & Random number generation & \tcode{<random>} \\ \rowsep
\ref{numarray}  & Numeric arrays     & \tcode{<valarray>}  \\ \rowsep
\ref{c.math}  & Mathematical functions for floating-point types &
  \tcode{<cmath>}, \tcode{<cstdlib>} \\ \rowsep
\ref{numbers}  & Numbers & \tcode{<numbers>} \\
\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 numeric type.
A \defnadj{numeric}{type} is a cv-unqualified object type \tcode{T}
that meets the
\oldconcept{DefaultConstructible},
\oldconcept{CopyConstructible},
\oldconcept{CopyAssignable}, and
\oldconcept{Destructible}
requirements\iref{utility.arg.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.}

\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} meets additional requirements specified for each such member
or related function.

\pnum
\begin{example}
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.
\end{example}

\rSec1[cfenv]{The floating-point environment}
\rSec2[cfenv.syn]{Header \tcode{<cfenv>} synopsis}

\indexheader{cfenv}%
\indexlibraryglobal{fenv_t}%
\indexlibraryglobal{fexcept_t}%
\indexlibraryglobal{feclearexcept}%
\indexlibraryglobal{fegetexceptflag}%
\indexlibraryglobal{feraiseexcept}%
\indexlibraryglobal{fesetexceptflag}%
\indexlibraryglobal{fetestexcept}%
\indexlibraryglobal{fegetround}%
\indexlibraryglobal{fesetround}%
\indexlibraryglobal{fegetenv}%
\indexlibraryglobal{feholdexcept}%
\indexlibraryglobal{fesetenv}%
\indexlibraryglobal{feupdateenv}%
\indexlibraryglobal{FE_ALL_EXCEPT}%
\indexlibraryglobal{FE_DIVBYZERO}%
\indexlibraryglobal{FE_INEXACT}%
\indexlibraryglobal{FE_INVALID}%
\indexlibraryglobal{FE_OVERFLOW}%
\indexlibraryglobal{FE_UNDERFLOW}%
\indexlibraryglobal{FE_DOWNWARD}%
\indexlibraryglobal{FE_TONEAREST}%
\indexlibraryglobal{FE_TOWARDZERO}%
\indexlibraryglobal{FE_UPWARD}%
\indexlibraryglobal{FE_DFL_ENV}%
\begin{codeblock}
#define FE_ALL_EXCEPT @\seebelow@
#define FE_DIVBYZERO @\seebelow@    // optional
#define FE_INEXACT @\seebelow@      // optional
#define FE_INVALID @\seebelow@      // optional
#define FE_OVERFLOW @\seebelow@     // optional
#define FE_UNDERFLOW @\seebelow@    // optional

#define FE_DOWNWARD @\seebelow@     // optional
#define FE_TONEAREST @\seebelow@    // optional
#define FE_TOWARDZERO @\seebelow@   // optional
#define FE_UPWARD @\seebelow@       // optional

#define FE_DFL_ENV @\seebelow@

namespace std {
  // types
  using fenv_t    = @\textit{object type}@;
  using fexcept_t = @\textit{integer type}@;

  // 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();
  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
The contents and meaning of the header \libheader{cfenv}
are the same as the C standard library header \libheader{fenv.h}.
\begin{note}
This document does not require an implementation to support the
\tcode{FENV_ACCESS} pragma;
it is \impldef{whether pragma \tcode{FENV_ACCESS} is supported}\iref{cpp.pragma}
whether the pragma is supported. As a consequence,
it is \impldef{whether \tcode{<cfenv>} functions can be used to manage floating-point status}
whether these functions can be used to test floating-point status flags,
set floating-point control modes, or run under non-default mode settings.
If the pragma is used to enable control over the floating-point environment,
this document does not specify the effect on
floating-point evaluation in constant expressions.
\end{note}

\pnum
The floating-point environment has thread storage
duration\iref{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{thread} object\iref{thread.thread.class}
or \tcode{jthread} object\iref{thread.jthread.class}
at the time it
constructed the object.
\begin{note}
That is, the child thread gets the floating-point
state of the parent thread at the time of the child's creation.
\end{note}

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

\xrefc{7.6}

\rSec1[complex.numbers]{Complex numbers}

\pnum
The header \libheader{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\iref{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 of type \cv{} \tcode{complex<T>} then:
\begin{itemize}
\item the expression \tcode{reinterpret_cast<\cv{} T(\&)[2]>(z)} is well-formed,
\item \tcode{reinterpret_cast<\cv{} T(\&)[2]>(z)[0]} designates the real part of \tcode{z}, and
\item \tcode{reinterpret_cast<\cv{} T(\&)[2]>(z)[1]} designates the imaginary part of \tcode{z}.
\end{itemize}

Moreover, if \tcode{a} is an expression of type \cv{}~\tcode{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]} designates the real part of \tcode{a[i]}, and
\item \tcode{reinterpret_cast<\cv{} T*>(a)[2*i + 1]} designates the imaginary part of \tcode{a[i]}.
\end{itemize}

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

\indexheader{complex}%
\begin{codeblock}
namespace std {
  // \ref{complex}, class template \tcode{complex}
  template<class T> class complex;

  // \ref{complex.special}, specializations
  template<> class complex<float>;
  template<> class complex<double>;
  template<> class complex<long double>;

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

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

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

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

  template<class T> constexpr complex<T> operator+(const complex<T>&);
  template<class T> constexpr 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, 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> constexpr T norm(const complex<T>&);

  template<class T> constexpr 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& = T());

  // \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>&);

  // \ref{complex.literals}, complex literals
  inline namespace literals {
  inline namespace complex_literals {
    constexpr complex<long double> operator""il(long double);
    constexpr complex<long double> operator""il(unsigned long long);
    constexpr complex<double> operator""i(long double);
    constexpr complex<double> operator""i(unsigned long long);
    constexpr complex<float> operator""if(long double);
    constexpr complex<float> operator""if(unsigned long long);
  }
  }
}
\end{codeblock}

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

\indexlibraryglobal{complex}%
\indexlibrarymember{value_type}{complex}%
\begin{codeblock}
namespace std {
  template<class T> class complex {
  public:
    using value_type = T;

    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;
    constexpr void real(T);
    constexpr T imag() const;
    constexpr void imag(T);

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

    constexpr complex& operator=(const complex&);
    template<class X> constexpr complex& operator= (const complex<X>&);
    template<class X> constexpr complex& operator+=(const complex<X>&);
    template<class X> constexpr complex& operator-=(const complex<X>&);
    template<class X> constexpr complex& operator*=(const complex<X>&);
    template<class X> constexpr complex& 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]{Specializations}

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

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

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

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

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

  template<> class complex<double> {
  public:
    using value_type = double;

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

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

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

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

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

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

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

    constexpr complex& operator= (long double);
    constexpr complex& operator+=(long double);
    constexpr complex& operator-=(long double);
    constexpr complex& operator*=(long double);
    constexpr complex& operator/=(long double);

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

\rSec2[complex.members]{Member functions}

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

\begin{itemdescr}
\pnum
\ensures
\tcode{real() == re \&\& imag() == im} is \tcode{true}.
\end{itemdescr}

\indexlibrarymember{real}{complex}%
\begin{itemdecl}
constexpr T real() const;
\end{itemdecl}

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

\indexlibrarymember{real}{complex}%
\begin{itemdecl}
constexpr void real(T val);
\end{itemdecl}

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

\indexlibrarymember{imag}{complex}%
\begin{itemdecl}
constexpr T imag() const;
\end{itemdecl}

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

\indexlibrarymember{imag}{complex}%
\begin{itemdecl}
constexpr void imag(T val);
\end{itemdecl}

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

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

\indexlibrarymember{operator+=}{complex}%
\begin{itemdecl}
constexpr complex& 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}

\indexlibrarymember{operator-=}{complex}%
\begin{itemdecl}
constexpr complex& 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}

\indexlibrarymember{operator*=}{complex}%
\begin{itemdecl}
constexpr complex& 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}

\indexlibrarymember{operator/=}{complex}%
\begin{itemdecl}
constexpr complex& 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}

\indexlibrarymember{operator+=}{complex}%
\begin{itemdecl}
template<class X> constexpr complex& operator+=(const complex<X>& 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}

\indexlibrarymember{operator-=}{complex}%
\begin{itemdecl}
template<class X> constexpr complex& operator-=(const complex<X>& 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}

\indexlibrarymember{operator*=}{complex}%
\begin{itemdecl}
template<class X> constexpr complex& operator*=(const complex<X>& 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}.

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

\indexlibrarymember{operator/=}{complex}%
\begin{itemdecl}
template<class X> constexpr complex& operator/=(const complex<X>& 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]{Non-member operations}

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

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

\end{itemdescr}

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

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

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

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

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

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

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

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

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

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

\indexlibrarymember{operator==}{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);
\end{itemdecl}

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

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

\indexlibrarymember{operator>>}{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
\expects
The input values are convertible to
\tcode{T}.

\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\iref{istream.formatted}.

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

\pnum
\returns
\tcode{is}.

\pnum
\remarks
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}

\indexlibrarymember{operator<<}{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}
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
\begin{note}
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{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{note}
\end{itemdescr}

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

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

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

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

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

\indexlibrarymember{abs}{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}

\indexlibrarymember{arg}{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}

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

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

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

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

\indexlibrarymember{proj}{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}.
\xrefc{7.3.9.5}
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\expects
\tcode{rho} is non-negative and non-NaN\@. \tcode{theta} is finite.

\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]{Transcendentals}

\indexlibrarymember{acos}{complex}%
\indexlibrarymember{cacos}{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 the C function \tcode{cacos}.
\xrefc{7.3.5.1}
\end{itemdescr}

\indexlibrarymember{asin}{complex}%
\indexlibrarymember{casin}{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 the C function \tcode{casin}.
\xrefc{7.3.5.2}
\end{itemdescr}

\indexlibrarymember{atan}{complex}%
\indexlibrarymember{catan}{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 the C function \tcode{catan}.
\xrefc{7.3.5.3}
\end{itemdescr}

\indexlibrarymember{acosh}{complex}%
\indexlibrarymember{cacosh}{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 the C function \tcode{cacosh}.
\xrefc{7.3.6.1}
\end{itemdescr}

\indexlibrarymember{asinh}{complex}%
\indexlibrarymember{casinh}{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 the C function \tcode{casinh}.
\xrefc{7.3.6.2}
\end{itemdescr}

\indexlibrarymember{atanh}{complex}%
\indexlibrarymember{catanh}{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 the C function \tcode{catanh}.
\xrefc{7.3.6.3}
\end{itemdescr}

\indexlibrarymember{cos}{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}

\indexlibrarymember{cosh}{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}

\indexlibrarymember{exp}{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}

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

\begin{itemdescr}
\pnum
\returns
The complex natural (base-$e$) logarithm of \tcode{x}. For all \tcode{x},
\tcode{imag(log(x))} lies in the interval \crange{$-\pi$}{$\pi$}.
\begin{note}
The semantics of this function are intended to be the same in \Cpp{}
as they are for \tcode{clog} in C.
\end{note}

\pnum
\remarks
The branch cuts are along the negative real axis.
\end{itemdescr}

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

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

\pnum
\remarks
The branch cuts are along the negative real axis.
\end{itemdescr}

\indexlibrarymember{pow}{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
\returns
The complex power of base \tcode{x} raised to the $\tcode{y}^\text{th}$ power,
defined as
\tcode{exp(y * log(x))}.
The value returned for
\tcode{pow(0, 0)}
is \impldef{value of \tcode{pow(0,0)}}.

\pnum
\remarks
The branch cuts are along the negative real axis.
\end{itemdescr}

\indexlibrarymember{sin}{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}

\indexlibrarymember{sinh}{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}

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

\begin{itemdescr}
\pnum
\returns
The complex square root of \tcode{x}, in the range of the right
half-plane.
\begin{note}
The semantics of this function are intended to be the same in \Cpp{}
as they are for \tcode{csqrt} in C.
\end{note}

\pnum
\remarks
The branch cuts are along the negative real axis.
\end{itemdescr}

\indexlibrarymember{tan}{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}

\indexlibrarymember{tanh}{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
\indexlibraryglobal{arg}%
\indexlibraryglobal{conj}%
\indexlibraryglobal{imag}%
\indexlibraryglobal{norm}%
\indexlibraryglobal{real}%
The following function templates shall have additional overloads:
\begin{codeblock}
arg                   norm
conj                  proj
imag                  real
\end{codeblock}
where \tcode{norm}, \tcode{conj}, \tcode{imag}, and \tcode{real} are \tcode{constexpr} overloads.

\pnum
\indextext{overloads!floating-point}%
The additional overloads shall be sufficient to ensure:
\begin{itemize}
        \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{itemize}

\pnum
\indexlibraryglobal{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{itemize}
  \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{itemize}

\rSec2[complex.literals]{Suffixes for complex number literals}

\indextext{literal!complex}%
\pnum
This subclause describes literal suffixes for constructing complex number literals.
The suffixes \tcode{i}, \tcode{il}, and \tcode{if} create complex numbers of
the types \tcode{complex<double>}, \tcode{complex<long double>}, and
\tcode{complex<float>} respectively, with their imaginary part denoted by the
given literal number and the real part being zero.

\indexlibrarymember{operator""""il}{complex}%
\begin{itemdecl}
constexpr complex<long double> operator""il(long double d);
constexpr complex<long double> operator""il(unsigned long long d);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{complex<long double>\{0.0L, static_cast<long double>(d)\}}.
\end{itemdescr}

\indexlibrarymember{operator""""i}{complex}%
\begin{itemdecl}
constexpr complex<double> operator""i(long double d);
constexpr complex<double> operator""i(unsigned long long d);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{complex<double>\{0.0, static_cast<double>(d)\}}.
\end{itemdescr}

\indexlibrarymember{operator""""if}{complex}%
\begin{itemdecl}
constexpr complex<float> operator""if(long double d);
constexpr complex<float> operator""if(unsigned long long d);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
\tcode{complex<float>\{0.0f, static_cast<float>(d)\}}.
\end{itemdescr}


\rSec1[bit]{Bit manipulation}

\rSec2[bit.general]{General}

\pnum
The header \libheaderdef{bit} provides components to access,
manipulate and process both individual bits and bit sequences.

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

\begin{codeblock}
namespace std {
  // \ref{bit.cast}, \tcode{bit_cast}
  template<class To, class From>
    constexpr To bit_cast(const From& from) noexcept;

  // \ref{bit.pow.two}, integral powers of 2
  template<class T>
    constexpr bool ispow2(T x) noexcept;
  template<class T>
    constexpr T ceil2(T x);
  template<class T>
    constexpr T floor2(T x) noexcept;
  template<class T>
    constexpr T log2p1(T x) noexcept;

  // \ref{bit.rotate}, rotating
  template<class T>
    [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
  template<class T>
    [[nodiscard]] constexpr T rotr(T x, int s) noexcept;

  // \ref{bit.count}, counting
  template<class T>
    constexpr int countl_zero(T x) noexcept;
  template<class T>
    constexpr int countl_one(T x) noexcept;
  template<class T>
    constexpr int countr_zero(T x) noexcept;
  template<class T>
    constexpr int countr_one(T x) noexcept;
  template<class T>
    constexpr int popcount(T x) noexcept;

  // \ref{bit.endian}, endian
  enum class endian {
    little = @\seebelow@,
    big    = @\seebelow@,
    native = @\seebelow@
  };
}
\end{codeblock}

\rSec2[bit.cast]{Function template \tcode{bit_cast}}

\indexlibraryglobal{bit_cast}%
\begin{itemdecl}
template<class To, class From>
  constexpr To bit_cast(const From& from) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\begin{itemize}
\item \tcode{sizeof(To) == sizeof(From)} is \tcode{true};
\item \tcode{is_trivially_copyable_v<To>} is \tcode{true}; and
\item \tcode{is_trivially_copyable_v<From>} is \tcode{true}.
\end{itemize}

\pnum
\returns
An object of type \tcode{To}.
Each bit of the value representation of the result
is equal to the corresponding bit in the object representation
of \tcode{from}. Padding bits of the \tcode{To} object are unspecified.
If there is no value of type \tcode{To} corresponding to the
value representation produced, the behavior is undefined.
If there are multiple such values, which value is produced is unspecified.

\pnum
\remarks
This function is \tcode{constexpr} if and only if
\tcode{To}, \tcode{From}, and the types of all subobjects
of \tcode{To} and \tcode{From} are types \tcode{T} such that:
\begin{itemize}
\item \tcode{is_union_v<T>} is \tcode{false};
\item \tcode{is_pointer_v<T>} is \tcode{false};
\item \tcode{is_member_pointer_v<T>} is \tcode{false};
\item \tcode{is_volatile_v<T>} is \tcode{false}; and
\item \tcode{T} has no non-static data members of reference type.
\end{itemize}
\end{itemdescr}

\rSec2[bit.pow.two]{Integral powers of 2}

\indexlibraryglobal{ispow2}%
\begin{itemdecl}
template<class T>
  constexpr bool ispow2(T x) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
\tcode{true} if \tcode{x} is an integral power of two;
\tcode{false} otherwise.

\end{itemdescr}

\indexlibraryglobal{ceil2}%
\begin{itemdecl}
template<class T>
  constexpr T ceil2(T x);
\end{itemdecl}

\begin{itemdescr}
\pnum
Let $N$ be the smallest power of 2 greater than or equal to \tcode{x}.

\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\expects
$N$ is representable as a value of type \tcode{T}.

\pnum
\returns
$N$.

\pnum
\throws
Nothing.

\pnum
\remarks
A function call expression
that violates the precondition in the \expects element
is not a core constant expression\iref{expr.const}.
\end{itemdescr}

\indexlibraryglobal{floor2}%
\begin{itemdecl}
template<class T>
  constexpr T floor2(T x) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
If \tcode{x == 0}, \tcode{0};
otherwise the maximal value \tcode{y}
such that \tcode{ispow2(y)} is \tcode{true} and \tcode{y <= x}.

\end{itemdescr}

\indexlibraryglobal{log2p1}%
\begin{itemdecl}
template<class T>
  constexpr T log2p1(T x) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
If \tcode{x == 0}, \tcode{0};
otherwise one plus the base-2 logarithm of \tcode{x},
with any fractional part discarded.

\end{itemdescr}

\rSec2[bit.rotate]{Rotating}

In the following descriptions,
let \tcode{N} denote \tcode{numeric_limits<T>::digits}.

\begin{itemdecl}
template<class T>
  [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
\end{itemdecl}

\indexlibraryglobal{rotl}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
Let \tcode{r} be \tcode{s \% N}.

\pnum
\returns
If \tcode{r} is \tcode{0}, \tcode{x};
if \tcode{r} is positive, \tcode{(x << r) | (x >> (N - r))};
if \tcode{r} is negative, \tcode{rotr(x, -r)}.
\end{itemdescr}

\begin{itemdecl}
template<class T>
  [[nodiscard]] constexpr T rotr(T x, int s) noexcept;
\end{itemdecl}

\indexlibraryglobal{rotr}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
Let \tcode{r} be \tcode{s \% N}.

\pnum
\returns
If \tcode{r} is \tcode{0}, \tcode{x};
if \tcode{r} is positive, \tcode{(x >> r) | (x << (N - r))};
if \tcode{r} is negative, \tcode{rotl(x, -r)}.
\end{itemdescr}

\rSec2[bit.count]{Counting}

In the following descriptions,
let \tcode{N} denote \tcode{numeric_limits<T>::digits}.

\begin{itemdecl}
template<class T>
  constexpr int countl_zero(T x) noexcept;
\end{itemdecl}

\indexlibraryglobal{countl_zero}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
The number of consecutive \tcode{0} bits in the value of \tcode{x},
starting from the most significant bit.
\begin{note}
Returns \tcode{N} if \tcode{x == 0}.
\end{note}
\end{itemdescr}

\begin{itemdecl}
template<class T>
  constexpr int countl_one(T x) noexcept;
\end{itemdecl}

\indexlibraryglobal{countl_one}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
The number of consecutive \tcode{1} bits in the value of \tcode{x},
starting from the most significant bit.
\begin{note}
Returns \tcode{N} if \tcode{x == numeric_limits<T>::max()}.
\end{note}
\end{itemdescr}

\begin{itemdecl}
template<class T>
  constexpr int countr_zero(T x) noexcept;
\end{itemdecl}

\indexlibraryglobal{countr_zero}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
The number of consecutive \tcode{0} bits in the value of \tcode{x},
starting from the least significant bit.
\begin{note}
Returns \tcode{N} if \tcode{x == 0}.
\end{note}
\end{itemdescr}

\begin{itemdecl}
template<class T>
  constexpr int countr_one(T x) noexcept;
\end{itemdecl}

\indexlibraryglobal{countr_one}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
The number of consecutive \tcode{1} bits in the value of \tcode{x},
starting from the least significant bit.
\begin{note}
Returns \tcode{N} if \tcode{x == numeric_limits<T>::max()}.
\end{note}
\end{itemdescr}

\begin{itemdecl}
template<class T>
  constexpr int popcount(T x) noexcept;
\end{itemdecl}

\indexlibraryglobal{popcount}%
\begin{itemdescr}
\pnum
\constraints
\tcode{T} is an unsigned integer type\iref{basic.fundamental}.

\pnum
\returns
The number of \tcode{1} bits in the value of \tcode{x}.
\end{itemdescr}

\rSec2[bit.endian]{Endian}

\pnum
Two common methods of byte ordering in multibyte scalar types are big-endian
and little-endian in the execution environment. Big-endian is a format for
storage of binary data in which the most significant byte is placed first,
with the rest in descending order. Little-endian is a format for storage of
binary data in which the least significant byte is placed first, with the rest
in ascending order. This subclause describes the endianness of the scalar types
of the execution environment.

\indexlibraryglobal{endian}%
\indexlibrarymember{little}{endian}%
\indexlibrarymember{big}{endian}%
\indexlibrarymember{native}{endian}%
\begin{itemdecl}
enum class endian {
  little = @\seebelow@,
  big    = @\seebelow@,
  native = @\seebelow@
};
\end{itemdecl}

\begin{itemdescr}
\pnum
If all scalar types have size 1 byte, then all of \tcode{endian::little},
\tcode{endian::big}, and \tcode{endian::native} have the same value.
Otherwise, \tcode{endian::little} is not equal to \tcode{endian::big}.
If all scalar types are big-endian, \tcode{endian::native} is
equal to \tcode{endian::big}.
If all scalar types are little-endian, \tcode{endian::native} is
equal to \tcode{endian::little}.
Otherwise, \tcode{endian::native} is not equal
to either \tcode{endian::big} or \tcode{endian::little}.
\end{itemdescr}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%                                                                %%%
%%%                                                                %%%
%%%      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 bit 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:
\term{uniform random bit generators},
\term{random number engines},
\term{random number engine adaptors},
and
\term{random number distributions}.
These categorizations are applicable
to types that meet the corresponding requirements,
to objects instantiated from such types,
and to templates producing such types when instantiated.
\begin{note}
 These entities are specified in such a way
 as to permit the binding
 of any uniform random bit 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)}.
\end{note}

\pnum
\indextext{\idxcode{result_type}!entity characterization based on}%
Each of the entities specified via this subclause
has an associated arithmetic type\iref{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{itemize}
 \item
   as \term{boolean} or equivalently as \term{boolean-valued},
   if \tcode{T} is \tcode{bool};
 \item
   otherwise
   as \term{integral} or equivalently as \term{integer-valued},
   if \tcode{numeric_limits<T>::is_integer} is \tcode{true};
 \item
   otherwise
   as \term{floating-point} or equivalently as \term{real-valued}.
\end{itemize}
\noindent
If integer-valued,
an entity may optionally be further characterized as
\term{signed} or \term{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{itemize}
 \item
   the operator \rightshift{} 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{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Header synopsis subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\rSec2[rand.synopsis]{Header \tcode{<random>} synopsis}

\indexheader{random}
\indextext{random number generation!synopsis|(}

\begin{codeblock}
#include <initializer_list>

namespace std {
  // \ref{rand.req.urng}, uniform random bit generator requirements
  template<class G>
    concept uniform_random_bit_generator = @\seebelow@;

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

  // \ref{rand.eng.mers}, class template \tcode{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 \tcode{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 \tcode{discard_block_engine}
  template<class Engine, size_t p, size_t r>
    class discard_block_engine;

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

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

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

  using default_random_engine = @\seebelow@;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  // \ref{rand.dist.samp.plinear}, class template \tcode{piecewise_linear_distribution}
  template<class RealType = double>
    class piecewise_linear_distribution;
}
\end{codeblock}%
\indextext{random number generation!synopsis|)}%


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Requirements subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  general requirements subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

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

\pnum
Throughout this subclause \ref{rand},
the effect of instantiating a template:
\begin{itemize}
  \item
    that has a template type parameter
    named \tcode{Sseq}
    is undefined unless the corresponding template argument
    is cv-unqualified and
    meets the requirements
    of seed sequence\iref{rand.req.seedseq}.
  \item
    that has a template type parameter
    named \tcode{URBG}
    is undefined unless the corresponding template argument
    is cv-unqualified and
    meets the requirements
    of uniform random bit generator\iref{rand.req.urng}.
  \item
    that has a template type parameter
    named \tcode{Engine}
    is undefined unless the corresponding template argument
    is cv-unqualified and
    meets the requirements
    of random number engine\iref{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 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 long},
      \tcode{unsigned short},
      \tcode{unsigned int},
      \tcode{unsigned long},
      or
      \tcode{unsigned long 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 short},
      \tcode{unsigned int},
      \tcode{unsigned long},
      or
      \tcode{unsigned long long}.
\end{itemize}

\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 meeting 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 meets 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 \term{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.
\begin{note}
 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.
\end{note}

\pnum
A class \tcode{S}
meets the requirements
of a seed sequence
if the expressions shown
in \tref{rand.req.seedseq}
are valid and have the indicated semantics,
and if \tcode{S} also meets all other requirements
of this subclause \ref{rand.req.seedseq}.
In that Table and throughout this subclause:
\begin{itemize}
  \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{itemize}


\begin{libreqtab4d}
  {Seed sequence requirements}
  {rand.req.seedseq}
\\ \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\iref{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 bit generator requirements}%
\indextext{uniform random bit generator!requirements|(}%
\indextext{requirements!uniform random bit generator|(}

\pnum
A \term{uniform random bit 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.
\begin{note}
 The degree to which \tcode{g}'s results
 approximate the ideal
 is often determined statistically.
\end{note}

\begin{codeblock}
template<class G>
  concept uniform_random_bit_generator =
    invocable<G&> && unsigned_integral<invoke_result_t<G&>> &&
    requires {
      { G::min() } -> same_as<invoke_result_t<G&>>;
      { G::max() } -> same_as<invoke_result_t<G&>>;
    };
\end{codeblock}

\pnum
Let \tcode{g} be an object of type \tcode{G}. \tcode{G} models
\libconcept{uniform_random_bit_generator} only if
\begin{itemize}
\item both \tcode{G::min()} and \tcode{G::max()} are constant
  expressions\iref{expr.const},
\item \tcode{G::min() < G::max()},
\item \tcode{G::min() <= g()},
\item \tcode{g() <= G::max()}, and
\item \tcode{g()} has amortized constant complexity.
\end{itemize}

\indextext{requirements!uniform random bit generator|)}%
\indextext{uniform random bit generator!requirements|)}%
\pnum
A class \tcode{G} meets the \term{uniform random bit generator} requirements if
\tcode{G} models \libconcept{uniform_random_bit_generator},
\tcode{invoke_result_t<G\&>} is an unsigned integer type\iref{basic.fundamental},
and
\tcode{G} provides a nested \grammarterm{typedef-name} \tcode{result_type}
that denotes the same type as \tcode{invoke_result_t<G\&>}.


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

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

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

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

\pnum
\tcode{E}'s specification shall define:
\begin{itemize}
 \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 \term{transition algorithm}
   $\mathsf{TA}$
   by which \tcode{e}'s state \state{e}{i}
   is advanced to its \term{successor state}
   \state{e}{i+1};
 and
 \item
   the \term{generation algorithm}
   $\mathsf{GA}$
   by which an engine's state is mapped
   to a value of type \tcode{result_type}.
\end{itemize}

\pnum
A class \tcode{E}
that meets the requirements
of a uniform random bit generator\iref{rand.req.urng}
also meets the requirements
of a \term{random number engine}
if the expressions shown
in \tref{rand.req.eng}
are valid and have the indicated semantics,
and if \tcode{E} also meets all other requirements
of this subclause \ref{rand.req.eng}.
In that Table and throughout this subclause:
\begin{itemize}
  \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
    meeting the requirements of a seed sequence\iref{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{itemize}
where \tcode{charT} and \tcode{traits} are constrained
according to \ref{strings} and \ref{input.output}.

\begin{libreqtab4d}
  {Random number engine requirements}
  {rand.req.eng}
\\ \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{$\text{size of state}$}
  \\ \rowsep
\tcode{E(x)}
\indextext{copy constructor!random number engine requirement}
  &
  & Creates an engine
    that compares equal to \tcode{x}.
  & \bigoh{$\text{size of state}$}
  \\ \rowsep
\tcode{E(s)}%
\indextext{constructor!random number engine requirement}
  &
  & Creates an engine
      with initial state determined by \tcode{s}.
  & \bigoh{$\text{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}
  & \ensures
    \tcode{e == E()}.
  & same as \tcode{E()}
  \\ \rowsep
\tcode{e.seed(s)}%
\indextext{\idxcode{seed}!random number engine requirement}
  & \tcode{void}
  & \ensures
    \tcode{e == E(s)}.
  & same as \tcode{E(s)}
  \\ \rowsep
\tcode{e.seed(q)}%
\indextext{\idxcode{seed}!random number engine requirement}
  & \tcode{void}
  & \ensures
    \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 \ref{rand.req.urng}
  \\ \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{$\text{size of state}$}
  \\ \rowsep
\tcode{x != y}%
\indextext{\idxcode{operator"!=}!random number engine requirement}
  & \tcode{bool}
  & \tcode{!(x == y)}.
  & \bigoh{$\text{size of state}$}
  \\ \rowsep
\tcode{os << x}%
\indextext{\idxcode{operator<<}!random number engine requirement}
  & reference to the type of \tcode{os}
  & With \tcode{os.}\textit{fmtflags} set to
    \tcode{ios_base::dec|ios_base::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.

    \ensures The \tcode{os.}\textit{fmtflags} and fill character are unchanged.
  & \bigoh{$\text{size of state}$}
  \\ \rowsep
\tcode{is >> v}%
\indextext{\idxcode{operator>>}!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_base::failbit)}
    (which may throw \tcode{ios_base::failure}\iref{iostate.flags}).
    If a textual representation written via \tcode{os << x}
    was subsequently read via \tcode{is >> v},
    then \tcode{x == v}
    provided that there have been no intervening invocations
    of \tcode{x} or of \tcode{v}.

    \expects
    \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}.

    \ensures The \tcode{is.}\textit{fmtflags} are unchanged.
  & \bigoh{$\text{size of state}$}
  \\
\end{libreqtab4d}

\pnum
\tcode{E} shall meet the
\oldconcept{CopyConstructible} (\tref{cpp17.copyconstructible})
and \oldconcept{CopyAssignable} (\tref{cpp17.copyassignable}) requirements.
These operations shall each be of complexity
no worse than \bigoh{\text{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 \term{random number engine adaptor}
(commonly shortened to \term{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 \term{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> 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 meet
the following additional requirements:
\begin{itemize}
 \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
   (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{itemize}

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

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

\pnum
A \term{random number distribution}
(commonly shortened to \term{distribution})
\tcode{d} of type \tcode{D}
is a function object
returning values
that are distributed according to
an associated mathematical \term{probability density function}
$p(z)$
or according to
an associated \term{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 \term{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}
meets the requirements
of a \term{random number distribution}
if the expressions shown
in \tref{rand.req.dist}
are valid and have the indicated semantics,
and if \tcode{D} and its associated types
also meet all other requirements
of this subclause \ref{rand.req.dist}.
In that Table and throughout this subclause,
\begin{itemize}
  \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
    meeting the requirements
    of a uniform random bit generator\iref{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{itemize}
where \tcode{charT} and \tcode{traits} are constrained
according to \ref{strings} and \ref{input.output}.

\begin{libreqtab4d}
  {Random number distribution requirements}
  {rand.req.dist}
\\ \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\iref{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}
  & \ensures \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 << x}
\indextext{\idxcode{operator<<}!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}.

    \ensures The \tcode{os.}\textit{fmtflags} and fill character are unchanged.
  &
  \\ \rowsep
\tcode{is >> d}
\indextext{\idxcode{operator>>}!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_base::failbit)}
    (which may throw \tcode{ios_base::failure}\iref{iostate.flags}).

    \expects
    \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}.

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

\pnum
\tcode{D} shall meet the
\oldconcept{CopyConstructible} (\tref{cpp17.copyconstructible})
and \oldconcept{CopyAssignable} (\tref{cpp17.copyassignable}) requirements.

\pnum
The sequence of numbers
produced by repeated invocations of \tcode{d(g)}
shall be independent of any invocation of
\tcode{os << 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 << x}
and that representation is restored
into the same or a different object \tcode{y}
of the same type using \tcode{is >> 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 meet the
\oldconcept{CopyConstructible} (\tref{cpp17.copyconstructible}),
\oldconcept{CopyAssignable} (\tref{cpp17.copyassignable}),
and
\oldconcept{Equality\-Comp\-arable} (\tref{cpp17.equalitycomparable}) requirements.

\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}
using distribution_type =  D;
\end{codeblock}

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


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Engine class templates subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


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

\pnum
Each type instantiated
from a class template specified in this subclause~\ref{rand.eng}
meets the requirements
of a random number engine\iref{rand.req.eng} type.

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

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

\pnum
Every function described in this subclause~\ref{rand.eng}
that has a function parameter \tcode{q} of type \tcode{Sseq\&}
for a template type parameter named \tcode{Sseq}
that is different from type \tcode{seed_seq}
throws what and when the invocation of \tcode{q.generate} throws.

\pnum
Descriptions are provided in this subclause~\ref{rand.eng}
only for engine operations
that are not described in \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 subclause~\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 subclause\iref{rand.eng} and in subclause~\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}}%
\indexlibraryglobal{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}$.

\indexlibraryglobal{linear_congruential_engine}%
\indexlibrarymember{result_type}{linear_congruential_engine}%
\begin{codeblock}
template<class UIntType, UIntType a, UIntType c, UIntType m>
  class linear_congruential_engine {
  public:
    // types
    using result_type = UIntType;

    // 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
    linear_congruential_engine() : linear_congruential_engine(default_seed) {}
    explicit linear_congruential_engine(result_type s);
    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 subclause~\ref{rand.eng.lcong}
\indextext{\idxcode{linear_congruential_engine}!modulus}
is \tcode{numeric_limits<result_type>::max()} plus $1$.
\begin{note}
 $m$ need not be representable
 as a value of type \tcode{result_type}.
\end{note}

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

\indexlibraryctor{linear_congruential_engine}%
\begin{itemdecl}
explicit linear_congruential_engine(result_type s);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
 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}

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

\begin{itemdescr}
\pnum
\effects
 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}}%
\indexlibraryglobal{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 \term{tempered}
(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{itemize}
 \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{itemize}
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{itemize}
 \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{itemize}

\indexlibraryglobal{mersenne_twister_engine}%
\indexlibrarymember{result_type}{mersenne_twister_engine}%
\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
    using result_type = UIntType;

    // 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
    mersenne_twister_engine() : mersenne_twister_engine(default_seed) {}
    explicit mersenne_twister_engine(result_type value);
    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<<w) - 1u},
  \tcode{b <= (1u<<w) - 1u},
  \tcode{c <= (1u<<w) - 1u},
  \tcode{d <= (1u<<w) - 1u},
and
  \tcode{f <= (1u<<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}, \dotsc, X_{i - 1}$,
in that order.

\indexlibraryctor{mersenne_twister_engine}%
\begin{itemdecl}
explicit mersenne_twister_engine(result_type value);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Sets $X_{-n}$ to $\tcode{value} \bmod 2^w$.
Then, iteratively for $i = 1 - n, \dotsc, -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}

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

\begin{itemdescr}
\pnum
\effects
 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,\dotsc,-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}}%
\indexlibraryglobal{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 \term{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{itemize}
 \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{itemize}
\begin{note}
 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$.
\end{note}

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

\indexlibraryglobal{subtract_with_carry_engine}%
\indexlibrarymember{result_type}{subtract_with_carry_engine}%
\begin{codeblock}
template<class UIntType, size_t w, size_t s, size_t r>
  class subtract_with_carry_engine {
  public:
    // types
    using result_type = UIntType;

    // 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
    subtract_with_carry_engine() : subtract_with_carry_engine(default_seed) {}
    explicit subtract_with_carry_engine(result_type value);
    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}, \dotsc, X_{i-1}$,
in that order, followed by $c$.

\indexlibraryctor{subtract_with_carry_engine}%
\begin{itemdecl}
explicit subtract_with_carry_engine(result_type value);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
 Sets the values of
 $X_{-r}, \dotsc, 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, \dotsc, 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}

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

\begin{itemdescr}
\pnum
\effects
 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, \dotsc, -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 subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\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 subclause~\ref{rand.adapt}
meets the requirements
of a random number engine adaptor\iref{rand.req.adapt} type.

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

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

\pnum
Every function described in this subclause~\ref{rand.adapt}
that has a function parameter \tcode{q} of type \tcode{Sseq\&}
for a template type parameter named \tcode{Sseq}
that is different from type \tcode{seed_seq}
throws what and when the invocation of \tcode{q.generate} throws.

\pnum
Descriptions are provided in this subclause~\ref{rand.adapt}
only for adaptor operations
that are not described in subclause~\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 subclause~\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}}%
\indexlibraryglobal{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.

\indexlibraryglobal{discard_block_engine}%
\indexlibrarymember{result_type}{discard_block_engine}%
\begin{codeblock}
template<class Engine, size_t p, size_t r>
  class discard_block_engine {
  public:
    // types
    using result_type = typename Engine::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 subclause~\ref{rand.req.adapt},
each constructor%
\indexlibraryctor{discard_block_engine}
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}}%
\indexlibraryglobal{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{itemize}
 \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{itemize}
\begin{note}
 The relation
 $w = n_0 w_0 + (n - n_0)(w_0 + 1)$
 always holds.
\end{note}

\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}

\indexlibraryglobal{independent_bits_engine}%
\indexlibrarymember{result_type}{independent_bits_engine}%
\begin{codeblock}
template<class Engine, size_t w, class UIntType>
  class independent_bits_engine {
  public:
    // types
    using result_type = UIntType;

    // 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}}%
\indexlibraryglobal{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{itemize}
 \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{itemize}

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

\indexlibraryglobal{shuffle_order_engine}%
\indexlibrarymember{result_type}{shuffle_order_engine}%
\begin{codeblock}
template<class Engine, size_t k>
  class shuffle_order_engine {
  public:
    // types
    using result_type = typename Engine::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 V[k];   // \expos
    result_type Y;      // \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 subclause~\ref{rand.req.adapt},
each constructor%
\indexlibraryctor{shuffle_order_engine}
that is not a copy constructor
initializes $\tcode{V[0]}, \dotsc, \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 subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\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|(}

\indexlibraryglobal{minstd_rand0}%
\indextext{engines with predefined parameters!\idxcode{minstd_rand0}}%
\begin{itemdecl}
using minstd_rand0 =
      linear_congruential_engine<uint_fast32_t, 16'807, 0, 2'147'483'647>;
\end{itemdecl}

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

\indexlibraryglobal{minstd_rand}%
\indextext{engines with predefined parameters!\idxcode{minstd_rand}}%
\begin{itemdecl}
using minstd_rand =
      linear_congruential_engine<uint_fast32_t, 48'271, 0, 2'147'483'647>;
\end{itemdecl}

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

\indexlibraryglobal{mt19937}%
\indextext{engines with predefined parameters!\idxcode{mt19937}}%
\begin{itemdecl}
using mt19937 =
      mersenne_twister_engine<uint_fast32_t, 32, 624, 397, 31,
       0x9908'b0df, 11, 0xffff'ffff, 7, 0x9d2c'5680, 15, 0xefc6'0000, 18, 1'812'433'253>;
\end{itemdecl}

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

\indexlibraryglobal{mt19937_64}%
\indextext{engines with predefined parameters!\idxcode{mt19937_64}}%
\begin{itemdecl}
using mt19937_64 =
      mersenne_twister_engine<uint_fast64_t, 64, 312, 156, 31,
       0xb502'6f5a'a966'19e9, 29, 0x5555'5555'5555'5555, 17,
       0x71d6'7fff'eda6'0000, 37, 0xfff7'eee0'0000'0000, 43, 6'364'136'223'846'793'005>;
\end{itemdecl}

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

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

\begin{itemdescr}
\pnum
\required
 The $10000^\text{th}$ consecutive invocation
 of a default-constructed object
 of type \tcode{ran\-lux24_base}
 produces the value
 $7937952$.
\end{itemdescr}

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

\begin{itemdescr}
\pnum
\required
 The $10000^\text{th}$ consecutive invocation
 of a default-constructed object
 of type \tcode{ran\-lux48_base}
 produces the value
 $61839128582725$.
\end{itemdescr}

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

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

\indexlibraryglobal{ranlux48}%
\indextext{engines with predefined parameters!\idxcode{ranlux48}}%
\begin{itemdecl}
using ranlux48 = discard_block_engine<ranlux48_base, 389, 11>;
\end{itemdecl}

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

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

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

\indexlibraryglobal{default_random_engine}%
\indextext{engines with predefined parameters!\idxcode{default_random_engine}}%
\begin{itemdecl}
using default_random_engine = @\textit{\impldef{type of \tcode{default_random_engine}}}@;
\end{itemdecl}

\begin{itemdescr}
\pnum
\remarks
The choice of engine type
named by this \tcode{typedef}
is \impldef{type of \tcode{default_random_engine}}.
\begin{note}
 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.
\end{note}
\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 subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


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

\pnum
A \tcode{random_device}
uniform random bit generator
produces nondeterministic random numbers.

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

\indexlibraryglobal{random_device}%
\indexlibrarymember{result_type}{random_device}%
\begin{codeblock}
class random_device {
public:
  // types
  using result_type = unsigned int;

  // 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
  random_device() : random_device(@\textit{implementation-defined}@) {}
  explicit random_device(const string& token);

  // 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}


\indexlibraryctor{random_device}%
\begin{itemdecl}
explicit random_device(const string& token);
\end{itemdecl}

\begin{itemdescr}
\pnum
\remarks
 The semantics of the \tcode{token} parameter
 and the token value used by the default constructor are
 \impldef{semantics of \tcode{token} parameter and default token value used by \tcode{random_device} constructors}.%
\footnote{The parameter is intended
   to allow an implementation to differentiate
   between different sources of randomness.}

\pnum
\throws
A value of an \impldef{exception type when \tcode{random_device} constructor fails} type
 derived from \tcode{exception}
 if the \tcode{random_device} could not be initialized.
\end{itemdescr}

\indexlibrarymember{entropy}{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, \dotsc, 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}

\indexlibrarymember{operator()}{random_device}%
\begin{itemdecl}
result_type operator()();
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A nondeterministic random value,
 uniformly distributed
 between \tcode{min()} and \tcode{max()} (inclusive).
 It is \impldef{how \tcode{random_device::operator()} generates values}
 how these values are generated.

\pnum
\throws
A value of an \impldef{exception type when \tcode{random_device::operator()} fails}
 type derived from \tcode{exception}
 if a random number could not be obtained.
\end{itemdescr}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% utilities subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


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

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

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

\indexlibraryglobal{seed_seq}%
\indexlibrarymember{result_type}{seed_seq}%
\begin{codeblock}
class seed_seq {
public:
  // types
  using result_type = uint_least32_t;

  // 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 noexcept;
  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}


\indexlibraryctor{seed_seq}%
\begin{itemdecl}
seed_seq();
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
\tcode{v.empty()} is \tcode{true}.

\pnum
\throws
Nothing.
\end{itemdescr}


\indexlibraryctor{seed_seq}%
\begin{itemdecl}
template<class T>
 seed_seq(initializer_list<T> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{T} is an integer type.

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


\indexlibraryctor{seed_seq}%
\begin{itemdecl}
template<class InputIterator>
  seed_seq(InputIterator begin, InputIterator end);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
  \tcode{iterator_traits<InputIterator>::value_type}
  is an integer type.

\pnum
\expects
  \tcode{InputIterator} meets the
  \oldconcept{InputIterator} requirements\iref{input.iterators}.

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

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

\begin{itemdescr}
\pnum
\mandates
  \tcode{iterator_traits<RandomAccessIterator>::\brk{}value_type}
  is an unsigned integer type capable of accommodating 32-bit quantities.

\pnum
\expects
  \tcode{RandomAccessIterator} meets the
  \oldconcept{RandomAccessIterator} requirements\iref{random.access.iterators}
  and the requirements of a mutable iterator.

\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{itemize}
 \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, \dotsc, m - 1$,
   calculate values
   \begin{eqnarray*}
     r_1 & = &
       1664525 \cdot T(    \tcode{begin[}k\tcode{]}
                      \xor \tcode{begin[}k+p\tcode{]}
                      \xor \tcode{begin[}k-1 \tcode{]}
                      )
     \\
     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$]} by $r_1$,
   increment \tcode{begin[$k+q$]} 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, \dotsc, m + n - 1$,
   calculate values
   \begin{eqnarray*}
     r_3 & = &
       1566083941 \cdot T( \tcode{begin[}k  \tcode{]}
                         + \tcode{begin[}k+p\tcode{]}
                         + \tcode{begin[}k-1\tcode{]}
                         )
     \\
     r_4 & = & r_3 - (k \bmod n)
   \end{eqnarray*}
   and, in order,
   \noindent
   update \tcode{begin[$k+p$]} by xoring it with $r_3$,
   update \tcode{begin[$k+q$]} by xoring it with $r_4$,
   and
   set \tcode{begin[$k$]} to $r_4$.
\end{itemize}

\pnum
\throws
What and when \tcode{RandomAccessIterator} operations of \tcode{begin}
and \tcode{end} throw.
\end{itemdescr}

\indexlibrarymember{size}{seed_seq}%
\begin{itemdecl}
size_t size() const noexcept;
\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}

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

\begin{itemdescr}
\pnum
\mandates
  Values of type \tcode{result_type} are writable\iref{iterator.requirements.general} to \tcode{dest}.

\pnum
\expects
  \tcode{OutputIterator} meets the
  \oldconcept{OutputIterator} requirements\iref{output.iterators}.

\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}

\pnum
\throws
What and when \tcode{OutputIterator} operations of \tcode{dest} throw.
\end{itemdescr}

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

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

\pnum
 Each function instantiated
 from the template
 described in this subclause~\ref{rand.util.canonical}
 maps the result of one or more invocations
 of a supplied uniform random bit 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
\begin{note}
 Obtaining a value in this way
 can be a useful step
 in the process of transforming
 a value generated by a uniform random bit generator
 into a value
 that can be delivered by a random number distribution.
\end{note}

\indexlibraryglobal{generate_canonical}%
\begin{itemdecl}
template<class RealType, size_t bits, class URBG>
 RealType generate_canonical(URBG& 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>::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, \dotsc, 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 subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\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 subclause~\ref{rand.dist}
meets the requirements
of a random number distribution\iref{rand.req.dist} type.

\pnum
Descriptions are provided in this subclause~\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
\impldef{algorithms for producing the standard random number distributions}.

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Uniform distributions subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\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}}%
\indexlibraryglobal{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) \text{ .} \]

\indexlibraryglobal{uniform_int_distribution}%
\indexlibrarymember{result_type}{uniform_int_distribution}%
\begin{codeblock}
template<class IntType = int>
  class uniform_int_distribution {
  public:
    // types
    using result_type = IntType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{uniform_int_distribution}%
\begin{itemdecl}
explicit uniform_int_distribution(IntType a, IntType b = numeric_limits<IntType>::max());
\end{itemdecl}

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

\pnum
\remarks
 \tcode{a} and \tcode{b}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{a}{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}

\indexlibrarymember{b}{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}}%
\indexlibraryglobal{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) \text{ .} \]
\begin{note}
This implies that $p(x\,|\,a,b)$ is undefined when \tcode{a == b}.
\end{note}

\indexlibraryglobal{uniform_real_distribution}%
\indexlibrarymember{result_type}{uniform_real_distribution}%
\begin{codeblock}
template<class RealType = double>
  class uniform_real_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{uniform_real_distribution}%
\begin{itemdecl}
explicit uniform_real_distribution(RealType a, RealType b = 1.0);
\end{itemdecl}

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

\pnum
\remarks
 \tcode{a} and \tcode{b}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{a}{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}

\indexlibrarymember{b}{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 subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\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}}%
\indexlibraryglobal{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}{ll}
                          p     & \text{ if $b = \tcode{true}$, or} \\
                          1 - p & \text{ if $b = \tcode{false}$.}
                          \end{array}\right.
\]

\indexlibraryglobal{bernoulli_distribution}%
\indexlibrarymember{result_type}{bernoulli_distribution}%
\begin{codeblock}
class bernoulli_distribution {
public:
  // types
  using result_type = bool;
  using param_type  = @\unspec@;

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

  // generating functions
  template<class URBG>
    result_type operator()(URBG& g);
  template<class URBG>
    result_type operator()(URBG& 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}


\indexlibraryctor{bernoulli_distribution}%
\begin{itemdecl}
explicit bernoulli_distribution(double p);
\end{itemdecl}

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

\pnum
\remarks
 \tcode{p}
 corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrarymember{p}{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}}%
\indexlibraryglobal{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) = \binom{t}{i} \cdot p^i \cdot (1-p)^{t-i} \text{ .} \]

\indexlibraryglobal{binomial_distribution}%
\indexlibrarymember{result_type}{binomial_distribution}%
\begin{codeblock}
template<class IntType = int>
  class binomial_distribution {
  public:
    // types
    using result_type = IntType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{binomial_distribution}%
\begin{itemdecl}
explicit binomial_distribution(IntType t, double p = 0.5);
\end{itemdecl}

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

\pnum
\remarks
 \tcode{t} and \tcode{p}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{t}{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}

\indexlibrarymember{p}{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}}
\indexlibraryglobal{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} \text{ .} \]

\indexlibraryglobal{geometric_distribution}%
\indexlibrarymember{result_type}{geometric_distribution}%
\begin{codeblock}
template<class IntType = int>
  class geometric_distribution {
  public:
    // types
    using result_type = IntType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{geometric_distribution}%
\begin{itemdecl}
explicit geometric_distribution(double p);
\end{itemdecl}

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

\pnum
\remarks
 \tcode{p}
 corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrarymember{p}{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}}
\indexlibraryglobal{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) = \binom{k+i-1}{i} \cdot p^k \cdot (1-p)^i \text{ .} \]
\begin{note}
This implies that $P(i\,|\,k,p)$ is undefined when \tcode{p == 1}.
\end{note}

\indexlibraryglobal{negative_binomial_distribution}%
\indexlibrarymember{result_type}{negative_binomial_distribution}%
\begin{codeblock}
template<class IntType = int>
  class negative_binomial_distribution {
  public:
    // types
    using result_type = IntType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{negative_binomial_distribution}%
\begin{itemdecl}
explicit negative_binomial_distribution(IntType k, double p = 0.5);
\end{itemdecl}

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

\pnum
\remarks
 \tcode{k} and \tcode{p}
 correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{k}{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}

\indexlibrarymember{p}{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 subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\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}}%
\indexlibraryglobal{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\,!} \text{ .} \]
The distribution parameter $\mu$
is also known as this distribution's \term{mean}%
\indextext{mean!\idxcode{poisson_distribution}}%
\indextext{\idxcode{poisson_distribution}!mean}%
.

\indexlibraryglobal{poisson_distribution}%
\indexlibrarymember{result_type}{poisson_distribution}%
\begin{codeblock}
template<class IntType = int>
  class poisson_distribution
  {
  public:
    // types
    using result_type = IntType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}

\indexlibraryctor{poisson_distribution}%
\begin{itemdecl}
explicit poisson_distribution(double mean);
\end{itemdecl}

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

\pnum
\remarks
\tcode{mean} corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrarymember{mean}{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}}%
\indexlibraryglobal{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} \text{ .} \]

\indexlibraryglobal{exponential_distribution}%
\indexlibrarymember{result_type}{exponential_distribution}%
\begin{codeblock}
template<class RealType = double>
  class exponential_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{exponential_distribution}%
\begin{itemdecl}
explicit exponential_distribution(RealType lambda);
\end{itemdecl}

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

\pnum
\remarks
\tcode{lambda} corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrarymember{lambda}{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}}%
\indexlibraryglobal{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) =
     \frac{e^{-x/\beta}}{\beta^{\alpha} \cdot \Gamma(\alpha)} \, \cdot \, x^{\, \alpha-1}
     \text{ .} \]

\indexlibraryglobal{gamma_distribution}%
\indexlibrarymember{result_type}{gamma_distribution}%
\begin{codeblock}
template<class RealType = double>
  class gamma_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{gamma_distribution}%
\begin{itemdecl}
explicit gamma_distribution(RealType alpha, RealType beta = 1.0);
\end{itemdecl}

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

\pnum
\remarks
\tcode{alpha} and \tcode{beta}
correspond to the parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{alpha}{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}

\indexlibrarymember{beta}{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}}%
\indexlibraryglobal{weibull_distribution}%
\indextext{random number distribution!\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)
     \text{ .} \]

\indexlibraryglobal{weibull_distribution}%
\indexlibrarymember{result_type}{weibull_distribution}%
\begin{codeblock}
template<class RealType = double>
  class weibull_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}

\indexlibraryctor{weibull_distribution}%
\begin{itemdecl}
explicit weibull_distribution(RealType a, RealType b = 1.0);
\end{itemdecl}%

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

\pnum
\remarks
\tcode{a} and \tcode{b}
correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{a}{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}

\indexlibrarymember{b}{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}}
\indexlibraryglobal{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)
     \text{ .} \]

\indexlibraryglobal{extreme_value_distribution}%
\indexlibrarymember{result_type}{extreme_value_distribution}%
\begin{codeblock}
template<class RealType = double>
  class extreme_value_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{extreme_value_distribution}%
\begin{itemdecl}
explicit extreme_value_distribution(RealType a, RealType b = 1.0);
\end{itemdecl}

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

\pnum
\remarks
\tcode{a} and \tcode{b}
correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{a}{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}

\indexlibrarymember{b}{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 subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\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}}%
\indexlibraryglobal{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)
      = \frac{1}{\sigma \sqrt{2\pi}}
        \cdot
        % e^{-(x-\mu)^2 / (2\sigma^2)}
        \exp{\left(- \, \frac{(x - \mu)^2}
                             {2 \sigma^2}
             \right)
            }
 \text{ .}
\]
The distribution parameters $\mu$ and $\sigma$
are also known as this distribution's \term{mean}%
\indextext{mean!\idxcode{normal_distribution}}%
\indextext{\idxcode{normal_distribution}!mean}
and \term{standard deviation}%
\indextext{standard deviation!\idxcode{normal_distribution}}%
\indextext{\idxcode{normal_distribution}!standard deviation}%
.

\indexlibraryglobal{normal_distribution}%
\indexlibrarymember{result_type}{normal_distribution}%
\begin{codeblock}
template<class RealType = double>
  class normal_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{normal_distribution}%
\begin{itemdecl}
explicit normal_distribution(RealType mean, RealType stddev = 1.0);
\end{itemdecl}

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

\pnum
\remarks
\tcode{mean} and \tcode{stddev}
correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{mean}{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}

\indexlibrarymember{stddev}{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}}%
\indexlibraryglobal{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)}
     \text{ .} \]

\indexlibraryglobal{lognormal_distribution}%
\indexlibrarymember{result_type}{lognormal_distribution}%
\begin{codeblock}
template<class RealType = double>
  class lognormal_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{lognormal_distribution}%
\begin{itemdecl}
explicit lognormal_distribution(RealType m, RealType s = 1.0);
\end{itemdecl}

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

\pnum
\remarks
\tcode{m} and \tcode{s}
correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{m}{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}

\indexlibrarymember{s}{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}}%
\indexlibraryglobal{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}} \text{ .} \]

\indexlibraryglobal{chi_squared_distribution}%
\indexlibrarymember{result_type}{chi_squared_distribution}%
\begin{codeblock}
template<class RealType = double>
  class chi_squared_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

    // constructor and reset functions
    chi_squared_distribution() : chi_squared_distribution(1.0) {}
    explicit chi_squared_distribution(RealType n);
    explicit chi_squared_distribution(const param_type& parm);
    void reset();

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{chi_squared_distribution}%
\begin{itemdecl}
explicit chi_squared_distribution(RealType n);
\end{itemdecl}

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

\pnum
\remarks
\tcode{n} corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrarymember{n}{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}}%
\indexlibraryglobal{cauchy_distribution}%
\indextext{random number distribution!\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} \text{ .} \]

\indexlibraryglobal{cauchy_distribution}%
\indexlibrarymember{result_type}{cauchy_distribution}%
\begin{codeblock}
template<class RealType = double>
  class cauchy_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{cauchy_distribution}%
\begin{itemdecl}
explicit cauchy_distribution(RealType a, RealType b = 1.0);
\end{itemdecl}

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

\pnum
\remarks
\tcode{a} and \tcode{b}
correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{a}{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}

\indexlibrarymember{b}{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}}%
\indexlibraryglobal{fisher_f_distribution}%
\indextext{random number distribution!\idxcode{fisher_f_distribution}}%

\pnum
A \tcode{fisher_f_distribution} random number distribution
produces random numbers $x \ge 0$
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}
     \text{ .} \]

\indexlibraryglobal{fisher_f_distribution}%
\indexlibrarymember{result_type}{fisher_distribution}%
\begin{codeblock}
template<class RealType = double>
  class fisher_f_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

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

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{fisher_f_distribution}%
\begin{itemdecl}
explicit fisher_f_distribution(RealType m, RealType n = 1);
\end{itemdecl}

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

\pnum
\remarks
\tcode{m} and \tcode{n}
correspond to the respective parameters of the distribution.
\end{itemdescr}

\indexlibrarymember{m}{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}

\indexlibrarymember{n}{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}}%
\indexlibraryglobal{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}
     \text{ .} \]

\indexlibraryglobal{student_t_distribution}%
\indexlibrarymember{result_type}{student_t_distribution}%
\begin{codeblock}
template<class RealType = double>
  class student_t_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

    // constructor and reset functions
    student_t_distribution() : student_t_distribution(1.0) {}
    explicit student_t_distribution(RealType n);
    explicit student_t_distribution(const param_type& parm);
    void reset();

    // generating functions
    template<class URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{student_t_distribution}%
\begin{itemdecl}
explicit student_t_distribution(RealType n);
\end{itemdecl}

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

\pnum
\remarks
\tcode{n} corresponds to the parameter of the distribution.
\end{itemdescr}

\indexlibrarymember{mean}{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 subclause
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\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}}%
\indexlibraryglobal{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, \dotsc, p_{n-1}) = p_i \text{ .} \]

\pnum
Unless specified otherwise,
the distribution parameters are calculated as:
$p_k = {w_k / S}$ for $k = 0, \dotsc, n - 1$,
in which the values $w_k$,
commonly known as the \term{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 + \dotsb + w_{n - 1}$.

\indexlibraryglobal{discrete_distribution}%
\indexlibrarymember{result_type}{discrete_distribution}%
\begin{codeblock}
template<class IntType = int>
  class discrete_distribution {
  public:
    // types
    using result_type = IntType;
    using param_type  = @\unspec@;

    // 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 URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}

\indexlibraryctor{discrete_distribution}
\begin{itemdecl}
discrete_distribution();
\end{itemdecl}

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


\indexlibraryctor{discrete_distribution}%
\begin{itemdecl}
template<class InputIterator>
  discrete_distribution(InputIterator firstW, InputIterator lastW);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_convertible_v<iterator_traits<InputIterator>::value_type,
double>} is \tcode{true}.

\pnum
\expects
  \tcode{InputIterator} meets the
  \oldconcept{InputIterator} requirements\iref{input.iterators}.
 If \tcode{firstW == lastW},
 let $n = 1$ and $w_0 = 1$.
 Otherwise,
 $\bigl[\tcode{firstW}, \tcode{lastW}\bigr)$
 forms a sequence $w$ of length $n > 0$.

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


\indexlibraryctor{discrete_distribution}%
\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}

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

\begin{itemdescr}
\pnum
\mandates
\tcode{is_invocable_r_v<double, UnaryOperation\&, double>} is \tcode{true}.

\pnum
\expects
 If $\tcode{nw} = 0$, let $n = 1$, otherwise let $n = \tcode{nw}$.
 The relation
   $0 < \delta = (\tcode{xmax} - \tcode{xmin}) / n$
 holds.

\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, \dotsc, n - 1$.

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

\indexlibrarymember{probabilities}{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, \dotsc, n - 1$.
\end{itemdescr}


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

\rSec4[rand.dist.samp.pconst]{Class template \tcode{piecewise_constant_distribution}}%
\indexlibraryglobal{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, \dotsc, b_n, \; \rho_0, \dotsc, \rho_{n-1}) = \rho_i
   \text{ , for $b_i \le x < b_{i+1}$.} \]

\pnum
The $n + 1$ distribution parameters $b_i$,
also known as this distribution's \term{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, \dotsc, n - 1$.
Unless specified otherwise,
the remaining $n$ distribution parameters are calculated as:
\[ \rho_k = \frac{w_k}{S \cdot (b_{k+1}-b_k)} \text{ for } k = 0, \dotsc, n - 1 \text{ ,} \]
in which the values $w_k$,
commonly known as the \term{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 + \dotsb + w_{n-1}$.

\indexlibraryglobal{piecewise_constant_distribution}%
\indexlibrarymember{result_type}{piecewise_constant_distribution}%
\begin{codeblock}
template<class RealType = double>
  class piecewise_constant_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

    // 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 URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}


\indexlibraryctor{piecewise_constant_distribution}%
\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}


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

\begin{itemdescr}
\pnum
\mandates
Both of
\begin{itemize}
\item{\tcode{is_convertible_v<iterator_traits<InputIteratorB>::value_type, double>}}
\item{\tcode{is_convertible_v<iterator_traits<InputIteratorW>::value_type, double>}}
\end{itemize}
are \tcode{true}.

\pnum
\expects
  \tcode{InputIteratorB} and \tcode{InputIteratorW}
   each meet the
  \oldconcept{InputIterator} requirements\iref{input.iterators}.
 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)$
 forms a sequence $b$ of length $n+1$,
 the length of the sequence $w$ starting from \tcode{firstW}
 is at least $n$,
 and any $w_k$ for  $k \geq n$ are ignored by the distribution.

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


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

\begin{itemdescr}
\pnum
\mandates
\tcode{is_invocable_r_v<double, UnaryOperation\&, double>} is \tcode{true}.

\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, \dotsc, b_n$,
 and
 let $w_k = \tcode{fw}\bigl(\bigl(b_{k+1} + b_k\bigr) / 2\bigr)$
 for $k = 0, \dotsc, n - 1$.

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


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

\begin{itemdescr}
\pnum
\mandates
\tcode{is_invocable_r_v<double, UnaryOperation\&, double>} is \tcode{true}.

\pnum
\expects
 If $\tcode{nw} = 0$, let $n = 1$, otherwise let $n = \tcode{nw}$.
 The relation $0 < \delta = (\tcode{xmax} - \tcode{xmin}) / n$
 holds.

\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, \dotsc, n$,
 and $w_k = \tcode{fw}(b_k + \delta / 2) $ for $ k = 0, \dotsc, n - 1$.

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

\indexlibrarymember{intervals}{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, \dotsc, n $.
\end{itemdescr}

\indexlibrarymember{densities}{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, \dotsc, n - 1$.
\end{itemdescr}


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

\rSec4[rand.dist.samp.plinear]{Class template \tcode{piecewise_linear_distribution}}%
\indexlibraryglobal{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, \dotsc, b_n, \; \rho_0, \dotsc, \rho_n)
     = \rho_{i}   \cdot {\frac{b_{i+1} - x}{b_{i+1} - b_i}}
     + \rho_{i+1} \cdot {\frac{x - b_i}{b_{i+1} - b_i}}
     \text{ , for $b_i \le x < b_{i+1}$.} \]

\pnum
The $n + 1$ distribution parameters $b_i$,
also known as this distribution's \term{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, \dotsc, n - 1$.
Unless specified otherwise,
the remaining $n + 1$ distribution parameters are calculated as
$\rho_k = {w_k / S}$ for $k = 0, \dotsc, n$, in which the values $w_k$,
commonly known as the \term{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) \text{ .} \]

\indexlibraryglobal{piecewise_linear_distribution}%
\indexlibrarymember{result_type}{piecewise_linear_distribution}%
\begin{codeblock}
template<class RealType = double>
  class piecewise_linear_distribution {
  public:
    // types
    using result_type = RealType;
    using param_type  = @\unspec@;

    // 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 URBG>
      result_type operator()(URBG& g);
    template<class URBG>
      result_type operator()(URBG& 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}

\indexlibraryctor{piecewise_linear_distribution}
\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}

\indexlibraryctor{piecewise_linear_distribution}
\begin{itemdecl}
template<class InputIteratorB, class InputIteratorW>
 piecewise_linear_distribution(InputIteratorB firstB, InputIteratorB lastB,
                               InputIteratorW firstW);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_invocable_r_v<double, UnaryOperation\&, double>} is \tcode{true}.

\pnum
\expects
  \tcode{InputIteratorB} and \tcode{InputIteratorW}
   each meet the
  \oldconcept{InputIterator} requirements\iref{input.iterators}.
 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)$
 forms a sequence $b$ of length $n+1$,
 the length of the sequence $w$ starting from \tcode{firstW}
 is at least $n+1$,
 and any $w_k$ for $k \geq n + 1$ are ignored by the distribution.

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


\indexlibraryctor{piecewise_linear_distribution}%
\begin{itemdecl}
template<class UnaryOperation>
 piecewise_linear_distribution(initializer_list<RealType> bl, UnaryOperation fw);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_invocable_r_v<double, UnaryOperation\&, double>} is \tcode{true}.

\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, \dotsc, b_n$,
 and
 let $w_k = \tcode{fw}(b_k)$
 for $k = 0, \dotsc, n$.

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


\indexlibraryctor{piecewise_linear_distribution}%
\begin{itemdecl}
template<class UnaryOperation>
 piecewise_linear_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{is_invocable_r_v<double, UnaryOperation\&, double>} is \tcode{true}.

\pnum
\expects
 If $\tcode{nw} = 0$, let $n = 1$, otherwise let $n = \tcode{nw}$.
 The relation $0 < \delta = (\tcode{xmax} - \tcode{xmin}) / n$
 holds.

\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, \dotsc, n$,
 and $w_k = \tcode{fw}(b_k)$ for $k = 0, \dotsc, n$.

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

\indexlibrarymember{intervals}{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, \dotsc, n$.
\end{itemdescr}

\indexlibrarymember{densities}{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, \dotsc, n$.
\end{itemdescr}%
%
\indextext{random number distributions!sampling|)}%
\indextext{sampling distributions|)}%
\indextext{random number generation!distributions|)}%

\rSec2[c.math.rand]{Low-quality random number generation}

\pnum
\begin{note}
The header \libheaderref{cstdlib}
declares the functions described in this subclause.
\end{note}

\indexlibraryglobal{rand}%
\indexlibraryglobal{srand}%
\begin{itemdecl}
int rand();
void srand(unsigned int seed);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
The
\tcode{rand} and \tcode{srand}
functions have the semantics specified in the C standard library.

\pnum
\remarks
The implementation
may specify that particular library functions may call
\tcode{rand}.
It is \impldef{whether \tcode{rand} may introduce a data race}
whether the \tcode{rand} function
may introduce data races\iref{res.on.data.races}.
\begin{note}
\indexlibrary{\idxcode{rand}!discouraged}%
The other random
number generation facilities in this document\iref{rand} are often preferable
to \tcode{rand}, because \tcode{rand}'s underlying algorithm is unspecified.
Use of \tcode{rand} therefore continues to be non-portable, with unpredictable
and oft-questionable quality and performance.
\end{note}
\end{itemdescr}

\xrefc{7.22.2}

\indextext{random number generation|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\rSec1[numarray]{Numeric arrays}

\rSec2[valarray.syn]{Header \tcode{<valarray>} synopsis}
\indexheader{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 typename valarray<T>::value_type&);
  template<class T> valarray<T> operator* (const typename valarray<T>::value_type&,
                                           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 typename valarray<T>::value_type&);
  template<class T> valarray<T> operator/ (const typename valarray<T>::value_type&,
                                           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 typename valarray<T>::value_type&);
  template<class T> valarray<T> operator% (const typename valarray<T>::value_type&,
                                           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 typename valarray<T>::value_type&);
  template<class T> valarray<T> operator+ (const typename valarray<T>::value_type&,
                                           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 typename valarray<T>::value_type&);
  template<class T> valarray<T> operator- (const typename valarray<T>::value_type&,
                                           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 typename valarray<T>::value_type&);
  template<class T> valarray<T> operator^ (const typename valarray<T>::value_type&,
                                           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 typename valarray<T>::value_type&);
  template<class T> valarray<T> operator& (const typename valarray<T>::value_type&,
                                           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 typename valarray<T>::value_type&);
  template<class T> valarray<T> operator| (const typename valarray<T>::value_type&,
                                           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 typename valarray<T>::value_type&);
  template<class T> valarray<T> operator<<(const typename valarray<T>::value_type&,
                                           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 typename valarray<T>::value_type&);
  template<class T> valarray<T> operator>>(const typename valarray<T>::value_type&,
                                           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 typename valarray<T>::value_type&);
  template<class T> valarray<bool> operator&&(const typename valarray<T>::value_type&,
                                              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 typename valarray<T>::value_type&);
  template<class T> valarray<bool> operator||(const typename valarray<T>::value_type&,
                                              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 typename valarray<T>::value_type&);
  template<class T> valarray<bool> operator==(const typename valarray<T>::value_type&,
                                              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 typename valarray<T>::value_type&);
  template<class T> valarray<bool> operator!=(const typename valarray<T>::value_type&,
                                              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 typename valarray<T>::value_type&);
  template<class T> valarray<bool> operator< (const typename valarray<T>::value_type&,
                                              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 typename valarray<T>::value_type&);
  template<class T> valarray<bool> operator> (const typename valarray<T>::value_type&,
                                              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 typename valarray<T>::value_type&);
  template<class T> valarray<bool> operator<=(const typename valarray<T>::value_type&,
                                              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 typename valarray<T>::value_type&);
  template<class T> valarray<bool> operator>=(const typename valarray<T>::value_type&,
                                              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 typename valarray<T>::value_type&);
  template<class T> valarray<T> atan2(const typename valarray<T>::value_type&,
                                      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 typename valarray<T>::value_type&);
  template<class T> valarray<T> pow(const typename valarray<T>::value_type&, 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 \libheader{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{\ref{implimits} 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}\iref{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 compound 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}\iref{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]{Overview}

\indexlibraryglobal{valarray}%
\begin{codeblock}
namespace std {
  template<class T> class valarray {
  public:
    using value_type = T;

    // \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& operator=(const valarray&);
    valarray& operator=(valarray&&) noexcept;
    valarray& operator=(initializer_list<T>);
    valarray& operator=(const T&);
    valarray& operator=(const slice_array<T>&);
    valarray& operator=(const gslice_array<T>&);
    valarray& operator=(const mask_array<T>&);
    valarray& 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          operator[](slice) const;
    slice_array<T>    operator[](slice);
    valarray          operator[](const gslice&) const;
    gslice_array<T>   operator[](const gslice&);
    valarray          operator[](const valarray<bool>&) const;
    mask_array<T>     operator[](const valarray<bool>&);
    valarray          operator[](const valarray<size_t>&) const;
    indirect_array<T> operator[](const valarray<size_t>&);

    // \ref{valarray.unary}, unary operators
    valarray operator+() const;
    valarray operator-() const;
    valarray operator~() const;
    valarray<bool> operator!() const;

    // \ref{valarray.cassign}, compound assignment
    valarray& operator*= (const T&);
    valarray& operator/= (const T&);
    valarray& operator%= (const T&);
    valarray& operator+= (const T&);
    valarray& operator-= (const T&);
    valarray& operator^= (const T&);
    valarray& operator&= (const T&);
    valarray& operator|= (const T&);
    valarray& operator<<=(const T&);
    valarray& operator>>=(const T&);

    valarray& operator*= (const valarray&);
    valarray& operator/= (const valarray&);
    valarray& operator%= (const valarray&);
    valarray& operator+= (const valarray&);
    valarray& operator-= (const valarray&);
    valarray& operator^= (const valarray&);
    valarray& operator|= (const valarray&);
    valarray& operator&= (const valarray&);
    valarray& operator<<=(const valarray&);
    valarray& operator>>=(const valarray&);

    // \ref{valarray.members}, member functions
    void swap(valarray&) noexcept;

    size_t size() const;

    T sum() const;
    T min() const;
    T max() const;

    valarray shift (int) const;
    valarray cshift(int) const;
    valarray apply(T func(T)) const;
    valarray apply(T func(const T&)) const;
    void resize(size_t sz, T c = T());
  };

  template<class T, size_t cnt> valarray(const T(&)[cnt], size_t) -> valarray<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.
For convenience, an object of type \tcode{valarray<T>} is referred
to as an ``array'' throughout the remainder of~\ref{numarray}.
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
temporary objects.
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.}

\rSec3[valarray.cons]{Constructors}

\indexlibraryctor{valarray}%
\begin{itemdecl}
valarray();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a \tcode{valarray}
that 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}

\indexlibraryctor{valarray}%
\begin{itemdecl}
explicit valarray(size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a \tcode{valarray} that has length \tcode{n}.
Each element of the array is value-initialized\iref{dcl.init}.
\end{itemdescr}

\indexlibraryctor{valarray}%
\begin{itemdecl}
valarray(const T& v, size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a \tcode{valarray} that has length \tcode{n}.
Each element of the array is initialized with \tcode{v}.
\end{itemdescr}

\indexlibraryctor{valarray}%
\begin{itemdecl}
valarray(const T* p, size_t n);
\end{itemdecl}

\begin{itemdescr}

\pnum
\expects
\range{p}{p + n} is a valid range.

\effects
Constructs a \tcode{valarray} that has length \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.}
\end{itemdescr}

\indexlibraryctor{valarray}%
\begin{itemdecl}
valarray(const valarray& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a \tcode{valarray} that has the same length as \tcode{v}.
The elements are initialized with the values of the corresponding
elements of \tcode{v}.\footnote{This copy constructor creates
a distinct array rather than an alias.
Implementations in which arrays share storage are permitted, but they
would need to implement a copy-on-reference mechanism to ensure that arrays are
conceptually distinct.}
\end{itemdescr}

\indexlibraryctor{valarray}%
\begin{itemdecl}
valarray(valarray&& v) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Constructs a \tcode{valarray} that has the same length as \tcode{v}.
The elements are initialized with the values of the corresponding
elements of \tcode{v}.

\pnum
\complexity
Constant.
\end{itemdescr}

\indexlibraryctor{valarray}%
\begin{itemdecl}
valarray(initializer_list<T> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{valarray(il.begin(), il.size())}.
\end{itemdescr}

\indexlibraryctor{valarray}%
\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}

\indexlibrarydtor{valarray}%
\begin{itemdecl}
~valarray();
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
The destructor is applied to every element of
\tcode{*this};
an implementation may return all allocated memory.
\end{itemdescr}

\rSec3[valarray.assign]{Assignment}

\indexlibrarymember{operator=}{valarray}%
\begin{itemdecl}
valarray& operator=(const valarray& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Each element of the
\tcode{*this}
array is assigned the value of the corresponding element of \tcode{v}.
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
\ensures
\tcode{size() == v.size()}.

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

\indexlibrarymember{operator=}{valarray}%
\begin{itemdecl}
valarray& operator=(valarray&& 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
\returns
\tcode{*this}.

\pnum
\complexity
Linear.
\end{itemdescr}

\indexlibrarymember{operator=}{valarray}%
\begin{itemdecl}
valarray& operator=(initializer_list<T> il);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to: \tcode{return *this = valarray(il);}
\end{itemdescr}


\indexlibrarymember{operator=}{valarray}%
\begin{itemdecl}
valarray& operator=(const T& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Assigns \tcode{v} to each element of \tcode{*this}.

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

\indexlibrarymember{operator=}{valarray}%
\begin{itemdecl}
valarray& operator=(const slice_array<T>&);
valarray& operator=(const gslice_array<T>&);
valarray& operator=(const mask_array<T>&);
valarray& operator=(const indirect_array<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
The length of the array to which the argument refers equals \tcode{size()}.
The value of an element in the left-hand side of a \tcode{valarray} assignment
operator does not depend on the value of another element in that left-hand side.

\pnum
These operators allow the results of a generalized subscripting operation
to be assigned directly to a
\tcode{valarray}.
\end{itemdescr}

\rSec3[valarray.access]{Element access}

\indexlibrarymember{operator[]}{valarray}%
\begin{itemdecl}
const T&  operator[](size_t n) const;
T& operator[](size_t n);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{n < size()} is \tcode{true}.

\pnum
\returns
A reference to the corresponding element of the array.
\begin{note}
The expression \tcode{(a[i] = q, a[i]) == q}
evaluates to \tcode{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}.
\end{note}

\pnum
\remarks
The expression \tcode{addressof(a[i+j]) == addressof(a[i]) + j}
evaluates to \tcode{true} for all \tcode{size_t i} and \tcode{size_t j}
such that \tcode{i+j < a.size()}.

\pnum
The expression \tcode{addressof(a[i]) != addressof(b[j])}
evaluates to \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 < a.size()}
and \tcode{j < b.size()}.
\begin{note}
This property indicates an absence of aliasing and may be used to
advantage by optimizing compilers. 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.
\end{note}

\pnum
The reference returned by the subscript operator for an array shall
be valid until the member function
\tcode{resize(size_t, T)}\iref{valarray.members} is called for that array or until the lifetime of
that array ends, whichever happens first.
\end{itemdescr}

\rSec3[valarray.sub]{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) shall exist.

\indexlibrarymember{operator[]}{valarray}%
\begin{itemdecl}
valarray operator[](slice slicearr) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A \tcode{valarray} containing those
elements of the controlled sequence designated by \tcode{slicearr}.
\begin{example}
\begin{codeblock}
const valarray<char> v0("abcdefghijklmnop", 16);
// \tcode{v0[slice(2, 5, 3)]} returns \tcode{valarray<char>("cfilo", 5)}
\end{codeblock}
\end{example}
\end{itemdescr}

\indexlibrarymember{operator[]}{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}.
\begin{example}
\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}
\end{example}
\end{itemdescr}

\indexlibrarymember{operator[]}{valarray}%
\begin{itemdecl}
valarray operator[](const gslice& gslicearr) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A \tcode{valarray} containing those
elements of the controlled sequence designated by \tcode{gslicearr}.
\begin{example}
\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}
\end{example}
\end{itemdescr}

\indexlibrarymember{operator[]}{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}.
\begin{example}
\begin{codeblock}
valarray<char> v0("abcdefghijklmnop", 16);
valarray<char> v1("ABCDEF", 6);
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}
\end{example}
\end{itemdescr}

\indexlibrarymember{operator[]}{valarray}%
\begin{itemdecl}
valarray operator[](const valarray<bool>& boolarr) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A \tcode{valarray} containing those
elements of the controlled sequence designated by \tcode{boolarr}.
\begin{example}
\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}
\end{example}
\end{itemdescr}

\indexlibrarymember{operator[]}{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}.
\begin{example}
\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}
\end{example}
\end{itemdescr}

\indexlibrarymember{operator[]}{valarray}%
\begin{itemdecl}
valarray operator[](const valarray<size_t>& indarr) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A \tcode{valarray} containing those
elements of the controlled sequence designated by \tcode{indarr}.
\begin{example}
\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}
\end{example}
\end{itemdescr}

\indexlibrarymember{operator[]}{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}.
\begin{example}
\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}
\end{example}
\end{itemdescr}

\rSec3[valarray.unary]{Unary operators}

\indexlibrarymember{operator+}{valarray}%
\indexlibrarymember{operator-}{valarray}%
\indexlibrarymember{operator\~{}}{valarray}%
\indexlibrarymember{operator"!}{valarray}%
\begin{itemdecl}
valarray operator+() const;
valarray operator-() const;
valarray operator~() const;
valarray<bool> operator!() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The indicated operator can be applied to operands of type \tcode{T}
and returns a value 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
\returns
A \tcode{valarray} whose length is \tcode{size()}.
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]{Compound assignment}

\indexlibrarymember{operator*=}{valarray}%
\indexlibrarymember{operator/=}{valarray}%
\indexlibrarymember{operator\%=}{valarray}%
\indexlibrarymember{operator+=}{valarray}%
\indexlibrarymember{operator-=}{valarray}%
\indexlibrarymember{operator\caret=}{valarray}%
\indexlibrarymember{operator\&=}{valarray}%
\indexlibrarymember{operator"|=}{valarray}%
\indexlibrarymember{operator<<=}{valarray}%
\indexlibrarymember{operator>>=}{valarray}%
\begin{itemdecl}
valarray& operator*= (const valarray& v);
valarray& operator/= (const valarray& v);
valarray& operator%= (const valarray& v);
valarray& operator+= (const valarray& v);
valarray& operator-= (const valarray& v);
valarray& operator^= (const valarray& v);
valarray& operator&= (const valarray& v);
valarray& operator|= (const valarray& v);
valarray& operator<<=(const valarray& v);
valarray& operator>>=(const valarray& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The indicated operator can be applied to two operands of type \tcode{T}.

\pnum
\expects
\tcode{size() == v.size()} is \tcode{true}.

The value of an element in the left-hand side of a valarray compound
assignment operator does not depend on the value of another element in that left
hand side.

\pnum
\effects
Each of these operators
performs the indicated operation on each of the elements of \tcode{*this} and the
corresponding element of \tcode{v}.

\pnum
\returns
\tcode{*this}.

\pnum
\remarks
The appearance of an array on the left-hand side of a compound assignment
does not invalidate references or pointers.
\end{itemdescr}

\indexlibrarymember{operator*=}{valarray}%
\indexlibrarymember{operator/=}{valarray}%
\indexlibrarymember{operator\%=}{valarray}%
\indexlibrarymember{operator+=}{valarray}%
\indexlibrarymember{operator-=}{valarray}%
\indexlibrarymember{operator\caret=}{valarray}%
\indexlibrarymember{operator\&=}{valarray}%
\indexlibrarymember{operator"|=}{valarray}%
\indexlibrarymember{operator<<=}{valarray}%
\indexlibrarymember{operator>>=}{valarray}%
\begin{itemdecl}
valarray& operator*= (const T& v);
valarray& operator/= (const T& v);
valarray& operator%= (const T& v);
valarray& operator+= (const T& v);
valarray& operator-= (const T& v);
valarray& operator^= (const T& v);
valarray& operator&= (const T& v);
valarray& operator|= (const T& v);
valarray& operator<<=(const T& v);
valarray& operator>>=(const T& v);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The indicated operator can be applied to two operands of type \tcode{T}.

\pnum
\effects
Each of these operators applies the indicated operation to each element
of \tcode{*this} and \tcode{v}.

\pnum
\returns
\tcode{*this}

\pnum
\remarks
The appearance of an array on the left-hand side of a compound assignment
does not
invalidate references or pointers to the elements of the array.
\end{itemdescr}

\rSec3[valarray.members]{Member functions}

\indexlibrarymember{swap}{valarray}%
\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}

\indexlibrarymember{size}{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}

\indexlibrarymember{sum}{valarray}%
\begin{itemdecl}
T sum() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
\tcode{operator+=} can be applied to operands of type \tcode{T}.

\pnum
\expects
\tcode{size() > 0} is \tcode{true}.

\pnum
\returns
The sum of all the elements of the array.
If the array has length 1, 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.%
\end{itemdescr}

\indexlibrarymember{min}{valarray}%
\begin{itemdecl}
T min() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{size() > 0} is \tcode{true}.

\pnum
\returns
The minimum value contained in \tcode{*this}.
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}

\indexlibrarymember{max}{valarray}%
\begin{itemdecl}
T max() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
\tcode{size() > 0} is \tcode{true}.

\pnum
\returns
The maximum value contained in \tcode{*this}.
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}

\indexlibrarymember{shift}{valarray}%
\begin{itemdecl}
valarray shift(int n) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A \tcode{valarray} of length \tcode{size()}, each of whose elements
\placeholder{I} is
\tcode{(*this)[\placeholder{I} + n]}
if \tcode{\placeholder{I} + n}
is non-negative and less than
\tcode{size()}, otherwise \tcode{T()}.
\begin{note}
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.
\end{note}

\pnum
\begin{example}
If the argument has the value -2,
the first two elements of the result will be value-initialized\iref{dcl.init}; the third element of the result will be assigned the value
of the first element of the argument; etc.
\end{example}
\end{itemdescr}

\indexlibrarymember{cshift}{valarray}%
\begin{itemdecl}
valarray cshift(int n) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A \tcode{valarray} 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 $n$ shifts
the elements circularly left $n$ places and a negative
value of $n$ shifts the elements circularly right $-n$ places.
\end{itemdescr}

\indexlibrarymember{apply}{valarray}%
\begin{itemdecl}
valarray apply(T func(T)) const;
valarray apply(T func(const T&)) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
A \tcode{valarray} whose length is \tcode{size()}.
Each element of the returned array is assigned
the value returned by applying the argument function to the
corresponding element of \tcode{*this}.
\end{itemdescr}

\indexlibrarymember{resize}{valarray}%
\begin{itemdecl}
void resize(size_t sz, T c = T());
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
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]{Binary operators}

\indexlibrarymember{operator*}{valarray}%
\indexlibrarymember{operator/}{valarray}%
\indexlibrarymember{operator\%}{valarray}%
\indexlibrarymember{operator+}{valarray}%
\indexlibrarymember{operator-}{valarray}%
\indexlibrarymember{operator\caret}{valarray}%
\indexlibrarymember{operator\&}{valarray}%
\indexlibrarymember{operator"|}{valarray}%
\indexlibrarymember{operator<<}{valarray}%
\indexlibrarymember{operator>>}{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
\mandates
The indicated operator can be applied to operands of type \tcode{T} and returns
a value of type \tcode{T} or which can be unambiguously
implicitly converted to \tcode{T}.

\pnum
\expects
The argument arrays have the same length.

\pnum
\returns
A \tcode{valarray} 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.
\end{itemdescr}

\indexlibrarymember{operator*}{valarray}%
\indexlibrarymember{operator/}{valarray}%
\indexlibrarymember{operator\%}{valarray}%
\indexlibrarymember{operator+}{valarray}%
\indexlibrarymember{operator-}{valarray}%
\indexlibrarymember{operator\caret}{valarray}%
\indexlibrarymember{operator\&}{valarray}%
\indexlibrarymember{operator"|}{valarray}%
\indexlibrarymember{operator<<}{valarray}%
\indexlibrarymember{operator>>}{valarray}%
\begin{itemdecl}
template<class T> valarray<T> operator* (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator* (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator/ (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator/ (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator% (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator% (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator+ (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator+ (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator- (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator- (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator^ (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator^ (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator& (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator& (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator| (const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator| (const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator<<(const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator<<(const typename valarray<T>::value_type&,
                                         const valarray<T>&);
template<class T> valarray<T> operator>>(const valarray<T>&,
                                         const typename valarray<T>::value_type&);
template<class T> valarray<T> operator>>(const typename valarray<T>::value_type&,
                                         const valarray<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The indicated operator can be applied to operands of type \tcode{T} and returns
a value of type \tcode{T} or which can be unambiguously
implicitly converted to \tcode{T}.

\pnum
\returns
A \tcode{valarray} 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]{Logical operators}

\indexlibrarymember{operator==}{valarray}%
\indexlibrarymember{operator"!=}{valarray}%
\indexlibrarymember{operator<}{valarray}%
\indexlibrarymember{operator>}{valarray}%
\indexlibrarymember{operator<=}{valarray}%
\indexlibrarymember{operator>=}{valarray}%
\indexlibrarymember{operator\&\&}{valarray}%
\indexlibrarymember{operator"|"|}{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
\mandates
The indicated operator can be applied to operands of type \tcode{T} and returns
a value of type \tcode{bool} or which can be unambiguously
implicitly converted to \tcode{bool}.

\pnum
\expects
The two array arguments have the same length.
\indextext{undefined}

\pnum
\returns
A \tcode{valarray<bool>} 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.
\end{itemdescr}

\indexlibrarymember{operator==}{valarray}%
\indexlibrarymember{operator"!=}{valarray}%
\indexlibrarymember{operator<}{valarray}%
\indexlibrarymember{operator>}{valarray}%
\indexlibrarymember{operator<=}{valarray}%
\indexlibrarymember{operator>=}{valarray}%
\indexlibrarymember{operator\&\&}{valarray}%
\indexlibrarymember{operator"|"|}{valarray}%
\begin{itemdecl}
template<class T> valarray<bool> operator==(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator==(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator!=(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator!=(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator< (const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator< (const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator> (const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator> (const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator<=(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator<=(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator>=(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator>=(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator&&(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator&&(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
template<class T> valarray<bool> operator||(const valarray<T>&,
                                            const typename valarray<T>::value_type&);
template<class T> valarray<bool> operator||(const typename valarray<T>::value_type&,
                                            const valarray<T>&);
\end{itemdecl}

\begin{itemdescr}
\pnum
\mandates
The indicated operator can be applied to operands of type \tcode{T} and returns
a value of type \tcode{bool} or which can be unambiguously
implicitly converted to \tcode{bool}.

\pnum
\returns
A \tcode{valarray<bool>} 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]{Transcendentals}

\indexlibrarymember{abs}{valarray}%
\indexlibrarymember{acos}{valarray}%
\indexlibrarymember{asin}{valarray}%
\indexlibrarymember{atan}{valarray}%
\indexlibrarymember{atan2}{valarray}%
\indexlibrarymember{cos}{valarray}%
\indexlibrarymember{cosh}{valarray}%
\indexlibrarymember{exp}{valarray}%
\indexlibrarymember{log}{valarray}%
\indexlibrarymember{log10}{valarray}%
\indexlibrarymember{pow}{valarray}%
\indexlibrarymember{sin}{valarray}%
\indexlibrarymember{sinh}{valarray}%
\indexlibrarymember{sqrt}{valarray}%
\indexlibrarymember{tan}{valarray}%
\indexlibrarymember{tanh}{valarray}%
\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 typename valarray<T>::value_type&);
template<class T> valarray<T> atan2(const typename valarray<T>::value_type&, 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 typename valarray<T>::value_type&);
template<class T> valarray<T> pow  (const typename valarray<T>::value_type&, 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
\mandates
A unique function with the indicated name can be applied (unqualified)
to an operand of type \tcode{T}.
This function returns a value of type \tcode{T}
or which can be unambiguously implicitly converted to type \tcode{T}.

\end{itemdescr}

\rSec3[valarray.special]{Specialized algorithms}

\indexlibrarymember{swap}{valarray}%
\begin{itemdecl}
template<class T> void swap(valarray<T>& x, valarray<T>& y) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to \tcode{x.swap(y)}.
\end{itemdescr}


\rSec2[class.slice]{Class \tcode{slice}}

\rSec3[class.slice.overview]{Overview}

\indexlibraryglobal{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;

    friend bool operator==(const slice& x, const slice& y);
  };
}
\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]{Constructors}

\indexlibraryctor{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
\begin{example}
\tcode{slice(3, 8, 2)}
constructs a slice which selects elements $3, 5, 7, \dotsc, 17$ from an array.
\end{example}
\end{itemdescr}

\rSec3[slice.access]{Access functions}
\indexlibrarymember{start}{slice}%
\indexlibrarymember{size}{slice}%
\indexlibrarymember{stride}{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}

\rSec3[slice.ops]{Operators}

\indexlibrarymember{stride}{slice}%
\begin{itemdecl}
friend bool operator==(const slice& x, const slice& y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Equivalent to:
\begin{codeblock}
return x.start() == y.start() && x.size() == y.size() && x.stride() == y.stride();
\end{codeblock}
\end{itemdescr}

\rSec2[template.slice.array]{Class template \tcode{slice_array}}

\rSec3[template.slice.array.overview]{Overview}

\indexlibraryglobal{slice_array}%
\indexlibrarymember{value_type}{slice_array}%
\begin{codeblock}
namespace std {
  template<class T> class slice_array {
  public:
    using value_type = T;

    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
This template is a helper template used by the
\tcode{slice} subscript operator
\begin{codeblock}
slice_array<T> valarray<T>::operator[](slice);
\end{codeblock}

\pnum
It has reference semantics to a subset of an array specified by a
\tcode{slice}
object.
\begin{example}
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, \dotsc, 13$.
\end{example}

\rSec3[slice.arr.assign]{Assignment}

\indexlibrarymember{operator=}{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]{Compound assignment}

\indexlibrarymember{operator*=}{slice_array}%
\indexlibrarymember{operator/=}{slice_array}%
\indexlibrarymember{operator\%=}{slice_array}%
\indexlibrarymember{operator+=}{slice_array}%
\indexlibrarymember{operator-=}{slice_array}%
\indexlibrarymember{operator\caret=}{slice_array}%
\indexlibrarymember{operator\&=}{slice_array}%
\indexlibrarymember{operator"|=}{slice_array}%
\indexlibrarymember{operator<<=}{slice_array}%
\indexlibrarymember{operator>>=}{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 compound 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]{Fill function}

\indexlibrarymember{operator=}{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]{Overview}

\indexlibraryglobal{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_j i_j d_j \]
where the multidimensional indices $i_j$ range in value from
0 to $l_{ij} - 1$.

\pnum
\begin{example}
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.
\end{example}

\pnum
It is possible to have degenerate generalized slices in which an address
is repeated.

\pnum
\begin{example}
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}
\end{example}

\pnum
If a degenerate slice is used as the argument to the
non-\tcode{const}
version of
\tcode{operator[](const gslice\&)},
the behavior is undefined.
\indextext{undefined}%

\rSec3[gslice.cons]{Constructors}

\indexlibraryctor{gslice}%
\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 subclause.
\end{itemdescr}

\rSec3[gslice.access]{Access functions}

\indexlibrarymember{start}{gslice}%
\indexlibrarymember{size}{gslice}%
\indexlibrarymember{stride}{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]{Overview}

\indexlibraryglobal{gslice_array}%
\indexlibrarymember{value_type}{gslice_array}%
\begin{codeblock}
namespace std {
  template<class T> class gslice_array {
  public:
    using value_type = T;

    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{gslice}
subscript operator

\indexlibraryglobal{gslice_array}%
\indexlibraryglobal{valarray}%
\begin{itemdecl}
gslice_array<T> valarray<T>::operator[](const gslice&);
\end{itemdecl}

\pnum
It has reference semantics to a subset of an array specified by a
\tcode{gslice}
object.
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}.

\rSec3[gslice.array.assign]{Assignment}

\indexlibrarymember{operator=}{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]{Compound assignment}

\indexlibrarymember{operator*=}{gslice_array}%
\indexlibrarymember{operator/=}{gslice_array}%
\indexlibrarymember{operator\%=}{gslice_array}%
\indexlibrarymember{operator+=}{gslice_array}%
\indexlibrarymember{operator-=}{gslice_array}%
\indexlibrarymember{operator\caret=}{gslice_array}%
\indexlibrarymember{operator\&=}{gslice_array}%
\indexlibrarymember{operator"|=}{gslice_array}%
\indexlibrarymember{operator<<=}{gslice_array}%
\indexlibrarymember{operator>>=}{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 compound 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]{Fill function}

\indexlibrarymember{operator=}{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]{Overview}

\indexlibraryglobal{mask_array}%
\indexlibrarymember{value_type}{mask_array}%
\begin{codeblock}
namespace std {
  template<class T> class mask_array {
  public:
    using value_type = T;

    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:

\indexlibrarymember{operator[]}{mask_array}%
\begin{itemdecl}
mask_array<T> valarray<T>::operator[](const valarray<bool>&).
\end{itemdecl}

\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}).

\rSec3[mask.array.assign]{Assignment}

\indexlibrarymember{operator=}{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]{Compound assignment}

\indexlibrarymember{operator*=}{mask_array}%
\indexlibrarymember{operator/=}{mask_array}%
\indexlibrarymember{operator\%=}{mask_array}%
\indexlibrarymember{operator+=}{mask_array}%
\indexlibrarymember{operator-=}{mask_array}%
\indexlibrarymember{operator\caret=}{mask_array}%
\indexlibrarymember{operator\&=}{mask_array}%
\indexlibrarymember{operator"|=}{mask_array}%
\indexlibrarymember{operator<<=}{mask_array}%
\indexlibrarymember{operator>>=}{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 compound 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]{Fill function}

\indexlibrarymember{operator=}{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]{Overview}

\indexlibraryglobal{indirect_array}%
\indexlibrarymember{value_type}{indirect_array}%
\begin{codeblock}
namespace std {
  template<class T> class indirect_array {
  public:
    using value_type = T;

    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

\indexlibrarymember{operator[]}{indirect_array}%
\begin{itemdecl}
indirect_array<T> valarray<T>::operator[](const valarray<size_t>&).
\end{itemdecl}

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

\rSec3[indirect.array.assign]{Assignment}

\indexlibrarymember{operator=}{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
\begin{example}
\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.
\end{example}
\end{itemdescr}

\rSec3[indirect.array.comp.assign]{Compound assignment}

\indexlibrarymember{operator*=}{indirect_array}%
\indexlibrarymember{operator/=}{indirect_array}%
\indexlibrarymember{operator\%=}{indirect_array}%
\indexlibrarymember{operator+=}{indirect_array}%
\indexlibrarymember{operator-=}{indirect_array}%
\indexlibrarymember{operator\caret=}{indirect_array}%
\indexlibrarymember{operator\&=}{indirect_array}%
\indexlibrarymember{operator"|=}{indirect_array}%
\indexlibrarymember{operator<<=}{indirect_array}%
\indexlibrarymember{operator>>=}{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 compound 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]{Fill function}

\indexlibrarymember{operator=}{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]{\tcode{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
\oldconcept{RandomAccessIterator}\iref{random.access.iterators}
and models \libconcept{contiguous_iterator}\iref{iterator.concept.contiguous},
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
\oldconcept{RandomAccessIterator}
and models \libconcept{contiguous_iterator},
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)}\iref{valarray.members} is called for that
array or until the lifetime of that array ends, whichever happens
first.

\indexlibrarymember{begin}{valarray}%
\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 array.
\end{itemdescr}

\indexlibrarymember{end}{valarray}%
\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 array.
\end{itemdescr}

\rSec1[c.math]{Mathematical functions for floating-point types}

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

\indexheader{cmath}%
\indexlibraryglobal{FP_FAST_FMA}%
\indexlibraryglobal{FP_FAST_FMAF}%
\indexlibraryglobal{FP_FAST_FMAL}%
\indexlibraryglobal{FP_ILOGB0}%
\indexlibraryglobal{FP_ILOGBNAN}%
\indexlibraryglobal{FP_INFINITE}%
\indexlibraryglobal{FP_NAN}%
\indexlibraryglobal{FP_NORMAL}%
\indexlibraryglobal{FP_SUBNORMAL}%
\indexlibraryglobal{FP_ZERO}%
\indexlibraryglobal{HUGE_VAL}%
\indexlibraryglobal{HUGE_VALF}%
\indexlibraryglobal{HUGE_VALL}%
\indexlibraryglobal{INFINITY}%
\indexlibraryglobal{MATH_ERREXCEPT}%
\indexlibraryglobal{MATH_ERRNO}%
\indexlibraryglobal{NAN}%
\indexlibraryglobal{abs}%
\indexlibraryglobal{acos}%
\indexlibraryglobal{acosf}%
\indexlibraryglobal{acosh}%
\indexlibraryglobal{acoshf}%
\indexlibraryglobal{acoshl}%
\indexlibraryglobal{acosl}%
\indexlibraryglobal{asin}%
\indexlibraryglobal{asinf}%
\indexlibraryglobal{asinh}%
\indexlibraryglobal{asinhf}%
\indexlibraryglobal{asinhl}%
\indexlibraryglobal{asinl}%
\indexlibraryglobal{atan}%
\indexlibraryglobal{atan2}%
\indexlibraryglobal{atan2f}%
\indexlibraryglobal{atan2l}%
\indexlibraryglobal{atanf}%
\indexlibraryglobal{atanh}%
\indexlibraryglobal{atanhf}%
\indexlibraryglobal{atanhl}%
\indexlibraryglobal{atanl}%
\indexlibraryglobal{cbrt}%
\indexlibraryglobal{cbrtf}%
\indexlibraryglobal{cbrtl}%
\indexlibraryglobal{ceil}%
\indexlibraryglobal{ceilf}%
\indexlibraryglobal{ceill}%
\indexlibraryglobal{copysign}%
\indexlibraryglobal{copysignf}%
\indexlibraryglobal{copysignl}%
\indexlibraryglobal{cos}%
\indexlibraryglobal{cosf}%
\indexlibraryglobal{cosh}%
\indexlibraryglobal{coshf}%
\indexlibraryglobal{coshl}%
\indexlibraryglobal{cosl}%
\indexlibraryglobal{double_t}%
\indexlibraryglobal{erf}%
\indexlibraryglobal{erfc}%
\indexlibraryglobal{erfcf}%
\indexlibraryglobal{erfcl}%
\indexlibraryglobal{erff}%
\indexlibraryglobal{erfl}%
\indexlibraryglobal{exp}%
\indexlibraryglobal{exp2}%
\indexlibraryglobal{exp2f}%
\indexlibraryglobal{exp2l}%
\indexlibraryglobal{expf}%
\indexlibraryglobal{expl}%
\indexlibraryglobal{expm1}%
\indexlibraryglobal{expm1f}%
\indexlibraryglobal{expm1l}%
\indexlibraryglobal{fabs}%
\indexlibraryglobal{fabsf}%
\indexlibraryglobal{fabsl}%
\indexlibraryglobal{fdim}%
\indexlibraryglobal{fdimf}%
\indexlibraryglobal{fdiml}%
\indexlibraryglobal{float_t}%
\indexlibraryglobal{floor}%
\indexlibraryglobal{floorf}%
\indexlibraryglobal{floorl}%
\indexlibraryglobal{fma}%
\indexlibraryglobal{fmaf}%
\indexlibraryglobal{fmal}%
\indexlibraryglobal{fmax}%
\indexlibraryglobal{fmaxf}%
\indexlibraryglobal{fmaxl}%
\indexlibraryglobal{fmin}%
\indexlibraryglobal{fminf}%
\indexlibraryglobal{fminl}%
\indexlibraryglobal{fmod}%
\indexlibraryglobal{fmodf}%
\indexlibraryglobal{fmodl}%
\indexlibraryglobal{fpclassify}%
\indexlibraryglobal{frexp}%
\indexlibraryglobal{frexpf}%
\indexlibraryglobal{frexpl}%
\indexlibraryglobal{hypot}%
\indexlibraryglobal{hypotf}%
\indexlibraryglobal{hypotl}%
\indexlibraryglobal{ilogb}%
\indexlibraryglobal{ilogbf}%
\indexlibraryglobal{ilogbl}%
\indexlibraryglobal{isfinite}%
\indexlibraryglobal{isgreater}%
\indexlibraryglobal{isgreaterequal}%
\indexlibraryglobal{isinf}%
\indexlibraryglobal{isless}%
\indexlibraryglobal{islessequal}%
\indexlibraryglobal{islessgreater}%
\indexlibraryglobal{isnan}%
\indexlibraryglobal{isnormal}%
\indexlibraryglobal{isunordered}%
\indexlibraryglobal{ldexp}%
\indexlibraryglobal{ldexpf}%
\indexlibraryglobal{ldexpl}%
\indexlibraryglobal{lgamma}%
\indexlibraryglobal{lgammaf}%
\indexlibraryglobal{lgammal}%
\indexlibraryglobal{llrint}%
\indexlibraryglobal{llrintf}%
\indexlibraryglobal{llrintl}%
\indexlibraryglobal{llround}%
\indexlibraryglobal{llroundf}%
\indexlibraryglobal{llroundl}%
\indexlibraryglobal{log}%
\indexlibraryglobal{log10}%
\indexlibraryglobal{log10f}%
\indexlibraryglobal{log10l}%
\indexlibraryglobal{log1p}%
\indexlibraryglobal{log1pf}%
\indexlibraryglobal{log1pl}%
\indexlibraryglobal{log2}%
\indexlibraryglobal{log2f}%
\indexlibraryglobal{log2l}%
\indexlibraryglobal{logb}%
\indexlibraryglobal{logbf}%
\indexlibraryglobal{logbl}%
\indexlibraryglobal{logf}%
\indexlibraryglobal{logl}%
\indexlibraryglobal{lrint}%
\indexlibraryglobal{lrintf}%
\indexlibraryglobal{lrintl}%
\indexlibraryglobal{lround}%
\indexlibraryglobal{lroundf}%
\indexlibraryglobal{lroundl}%
\indexlibraryglobal{math_errhandling}%
\indexlibraryglobal{modf}%
\indexlibraryglobal{modff}%
\indexlibraryglobal{modfl}%
\indexlibraryglobal{nan}%
\indexlibraryglobal{nanf}%
\indexlibraryglobal{nanl}%
\indexlibraryglobal{nearbyint}%
\indexlibraryglobal{nearbyintf}%
\indexlibraryglobal{nearbyintl}%
\indexlibraryglobal{nextafter}%
\indexlibraryglobal{nextafterf}%
\indexlibraryglobal{nextafterl}%
\indexlibraryglobal{nexttoward}%
\indexlibraryglobal{nexttowardf}%
\indexlibraryglobal{nexttowardl}%
\indexlibraryglobal{pow}%
\indexlibraryglobal{powf}%
\indexlibraryglobal{powl}%
\indexlibraryglobal{remainder}%
\indexlibraryglobal{remainderf}%
\indexlibraryglobal{remainderl}%
\indexlibraryglobal{remquo}%
\indexlibraryglobal{remquof}%
\indexlibraryglobal{remquol}%
\indexlibraryglobal{rint}%
\indexlibraryglobal{rintf}%
\indexlibraryglobal{rintl}%
\indexlibraryglobal{round}%
\indexlibraryglobal{roundf}%
\indexlibraryglobal{roundl}%
\indexlibraryglobal{scalbln}%
\indexlibraryglobal{scalblnf}%
\indexlibraryglobal{scalblnl}%
\indexlibraryglobal{scalbn}%
\indexlibraryglobal{scalbnf}%
\indexlibraryglobal{scalbnl}%
\indexlibraryglobal{signbit}%
\indexlibraryglobal{sin}%
\indexlibraryglobal{sinf}%
\indexlibraryglobal{sinh}%
\indexlibraryglobal{sinhf}%
\indexlibraryglobal{sinhl}%
\indexlibraryglobal{sinl}%
\indexlibraryglobal{sqrt}%
\indexlibraryglobal{sqrtf}%
\indexlibraryglobal{sqrtl}%
\indexlibraryglobal{tan}%
\indexlibraryglobal{tanf}%
\indexlibraryglobal{tanh}%
\indexlibraryglobal{tanhf}%
\indexlibraryglobal{tanhl}%
\indexlibraryglobal{tanl}%
\indexlibraryglobal{tgamma}%
\indexlibraryglobal{tgammaf}%
\indexlibraryglobal{tgammal}%
\indexlibraryglobal{trunc}%
\indexlibraryglobal{truncf}%
\indexlibraryglobal{truncl}%
\begin{codeblock}
namespace std {
  using float_t = @\seebelow@;
  using double_t = @\seebelow@;
}

#define HUGE_VAL @\seebelow@
#define HUGE_VALF @\seebelow@
#define HUGE_VALL @\seebelow@
#define INFINITY @\seebelow@
#define NAN @\seebelow@
#define FP_INFINITE @\seebelow@
#define FP_NAN @\seebelow@
#define FP_NORMAL @\seebelow@
#define FP_SUBNORMAL @\seebelow@
#define FP_ZERO @\seebelow@
#define FP_FAST_FMA @\seebelow@
#define FP_FAST_FMAF @\seebelow@
#define FP_FAST_FMAL @\seebelow@
#define FP_ILOGB0 @\seebelow@
#define FP_ILOGBNAN @\seebelow@
#define MATH_ERRNO @\seebelow@
#define MATH_ERREXCEPT @\seebelow@

#define math_errhandling @\seebelow@

namespace std {
  float acos(float x);  // see \ref{library.c}
  double acos(double x);
  long double acos(long double x);  // see \ref{library.c}
  float acosf(float x);
  long double acosl(long double x);

  float asin(float x);  // see \ref{library.c}
  double asin(double x);
  long double asin(long double x);  // see \ref{library.c}
  float asinf(float x);
  long double asinl(long double x);

  float atan(float x);                  // see \ref{library.c}
  double atan(double x);
  long double atan(long double x);      // see \ref{library.c}
  float atanf(float x);
  long double atanl(long double x);

  float atan2(float y, float x);        // see \ref{library.c}
  double atan2(double y, double x);
  long double atan2(long double y, long double x);  // see \ref{library.c}
  float atan2f(float y, float x);
  long double atan2l(long double y, long double x);

  float cos(float x);                   // see \ref{library.c}
  double cos(double x);
  long double cos(long double x);       // see \ref{library.c}
  float cosf(float x);
  long double cosl(long double x);

  float sin(float x);                   // see \ref{library.c}
  double sin(double x);
  long double sin(long double x);       // see \ref{library.c}
  float sinf(float x);
  long double sinl(long double x);

  float tan(float x);                   // see \ref{library.c}
  double tan(double x);
  long double tan(long double x);       // see \ref{library.c}
  float tanf(float x);
  long double tanl(long double x);

  float acosh(float x);                 // see \ref{library.c}
  double acosh(double x);
  long double acosh(long double x);     // see \ref{library.c}
  float acoshf(float x);
  long double acoshl(long double x);

  float asinh(float x);                 // see \ref{library.c}
  double asinh(double x);
  long double asinh(long double x);     // see \ref{library.c}
  float asinhf(float x);
  long double asinhl(long double x);

  float atanh(float x);                 // see \ref{library.c}
  double atanh(double x);
  long double atanh(long double x);     // see \ref{library.c}
  float atanhf(float x);
  long double atanhl(long double x);

  float cosh(float x);                  // see \ref{library.c}
  double cosh(double x);
  long double cosh(long double x);      // see \ref{library.c}
  float coshf(float x);
  long double coshl(long double x);

  float sinh(float x);                  // see \ref{library.c}
  double sinh(double x);
  long double sinh(long double x);      // see \ref{library.c}
  float sinhf(float x);
  long double sinhl(long double x);

  float tanh(float x);                  // see \ref{library.c}
  double tanh(double x);
  long double tanh(long double x);      // see \ref{library.c}
  float tanhf(float x);
  long double tanhl(long double x);

  float exp(float x);                   // see \ref{library.c}
  double exp(double x);
  long double exp(long double x);       // see \ref{library.c}
  float expf(float x);
  long double expl(long double x);

  float exp2(float x);                  // see \ref{library.c}
  double exp2(double x);
  long double exp2(long double x);      // see \ref{library.c}
  float exp2f(float x);
  long double exp2l(long double x);

  float expm1(float x);                 // see \ref{library.c}
  double expm1(double x);
  long double expm1(long double x);     // see \ref{library.c}
  float expm1f(float x);
  long double expm1l(long double x);

  float frexp(float value, int* exp);   // see \ref{library.c}
  double frexp(double value, int* exp);
  long double frexp(long double value, int* exp);   // see \ref{library.c}
  float frexpf(float value, int* exp);
  long double frexpl(long double value, int* exp);

  int ilogb(float x);                   // see \ref{library.c}
  int ilogb(double x);
  int ilogb(long double x);             // see \ref{library.c}
  int ilogbf(float x);
  int ilogbl(long double x);

  float ldexp(float x, int exp);        // see \ref{library.c}
  double ldexp(double x, int exp);
  long double ldexp(long double x, int exp);    // see \ref{library.c}
  float ldexpf(float x, int exp);
  long double ldexpl(long double x, int exp);

  float log(float x);                   // see \ref{library.c}
  double log(double x);
  long double log(long double x);       // see \ref{library.c}
  float logf(float x);
  long double logl(long double x);

  float log10(float x);                 // see \ref{library.c}
  double log10(double x);
  long double log10(long double x);     // see \ref{library.c}
  float log10f(float x);
  long double log10l(long double x);

  float log1p(float x);                 // see \ref{library.c}
  double log1p(double x);
  long double log1p(long double x);     // see \ref{library.c}
  float log1pf(float x);
  long double log1pl(long double x);

  float log2(float x);                  // see \ref{library.c}
  double log2(double x);
  long double log2(long double x);      // see \ref{library.c}
  float log2f(float x);
  long double log2l(long double x);

  float logb(float x);                  // see \ref{library.c}
  double logb(double x);
  long double logb(long double x);      // see \ref{library.c}
  float logbf(float x);
  long double logbl(long double x);

  float modf(float value, float* iptr); // see \ref{library.c}
  double modf(double value, double* iptr);
  long double modf(long double value, long double* iptr);   // see \ref{library.c}
  float modff(float value, float* iptr);
  long double modfl(long double value, long double* iptr);

  float scalbn(float x, int n);         // see \ref{library.c}
  double scalbn(double x, int n);
  long double scalbn(long double x, int n);     // see \ref{library.c}
  float scalbnf(float x, int n);
  long double scalbnl(long double x, int n);

  float scalbln(float x, long int n);   // see \ref{library.c}
  double scalbln(double x, long int n);
  long double scalbln(long double x, long int n);   // see \ref{library.c}
  float scalblnf(float x, long int n);
  long double scalblnl(long double x, long int n);

  float cbrt(float x);                  // see \ref{library.c}
  double cbrt(double x);
  long double cbrt(long double x);      // see \ref{library.c}
  float cbrtf(float x);
  long double cbrtl(long double x);

  // \ref{c.math.abs}, absolute values
  int abs(int j);
  long int abs(long int j);
  long long int abs(long long int j);
  float abs(float j);
  double abs(double j);
  long double abs(long double j);

  float fabs(float x);                  // see \ref{library.c}
  double fabs(double x);
  long double fabs(long double x);      // see \ref{library.c}
  float fabsf(float x);
  long double fabsl(long double x);

  float hypot(float x, float y);        // see \ref{library.c}
  double hypot(double x, double y);
  long double hypot(long double x, long double y);  // see \ref{library.c}
  float hypotf(float x, float y);
  long double hypotl(long double x, long double y);

  // \ref{c.math.hypot3}, three-dimensional hypotenuse
  float hypot(float x, float y, float z);
  double hypot(double x, double y, double z);
  long double hypot(long double x, long double y, long double z);

  float pow(float x, float y);          // see \ref{library.c}
  double pow(double x, double y);
  long double pow(long double x, long double y);    // see \ref{library.c}
  float powf(float x, float y);
  long double powl(long double x, long double y);

  float sqrt(float x);                  // see \ref{library.c}
  double sqrt(double x);
  long double sqrt(long double x);      // see \ref{library.c}
  float sqrtf(float x);
  long double sqrtl(long double x);

  float erf(float x);                   // see \ref{library.c}
  double erf(double x);
  long double erf(long double x);       // see \ref{library.c}
  float erff(float x);
  long double erfl(long double x);

  float erfc(float x);                  // see \ref{library.c}
  double erfc(double x);
  long double erfc(long double x);      // see \ref{library.c}
  float erfcf(float x);
  long double erfcl(long double x);

  float lgamma(float x);                // see \ref{library.c}
  double lgamma(double x);
  long double lgamma(long double x);    // see \ref{library.c}
  float lgammaf(float x);
  long double lgammal(long double x);

  float tgamma(float x);                // see \ref{library.c}
  double tgamma(double x);
  long double tgamma(long double x);    // see \ref{library.c}
  float tgammaf(float x);
  long double tgammal(long double x);

  float ceil(float x);                  // see \ref{library.c}
  double ceil(double x);
  long double ceil(long double x);      // see \ref{library.c}
  float ceilf(float x);
  long double ceill(long double x);

  float floor(float x);                 // see \ref{library.c}
  double floor(double x);
  long double floor(long double x);     // see \ref{library.c}
  float floorf(float x);
  long double floorl(long double x);

  float nearbyint(float x);             // see \ref{library.c}
  double nearbyint(double x);
  long double nearbyint(long double x); // see \ref{library.c}
  float nearbyintf(float x);
  long double nearbyintl(long double x);

  float rint(float x);                  // see \ref{library.c}
  double rint(double x);
  long double rint(long double x);      // see \ref{library.c}
  float rintf(float x);
  long double rintl(long double x);

  long int lrint(float x);              // see \ref{library.c}
  long int lrint(double x);
  long int lrint(long double x);        // see \ref{library.c}
  long int lrintf(float x);
  long int lrintl(long double x);

  long long int llrint(float x);        // see \ref{library.c}
  long long int llrint(double x);
  long long int llrint(long double x);  // see \ref{library.c}
  long long int llrintf(float x);
  long long int llrintl(long double x);

  float round(float x);                 // see \ref{library.c}
  double round(double x);
  long double round(long double x);     // see \ref{library.c}
  float roundf(float x);
  long double roundl(long double x);

  long int lround(float x);             // see \ref{library.c}
  long int lround(double x);
  long int lround(long double x);       // see \ref{library.c}
  long int lroundf(float x);
  long int lroundl(long double x);

  long long int llround(float x);       // see \ref{library.c}
  long long int llround(double x);
  long long int llround(long double x); // see \ref{library.c}
  long long int llroundf(float x);
  long long int llroundl(long double x);

  float trunc(float x);                 // see \ref{library.c}
  double trunc(double x);
  long double trunc(long double x);     // see \ref{library.c}
  float truncf(float x);
  long double truncl(long double x);

  float fmod(float x, float y);         // see \ref{library.c}
  double fmod(double x, double y);
  long double fmod(long double x, long double y);   // see \ref{library.c}
  float fmodf(float x, float y);
  long double fmodl(long double x, long double y);

  float remainder(float x, float y);    // see \ref{library.c}
  double remainder(double x, double y);
  long double remainder(long double x, long double y);  // see \ref{library.c}
  float remainderf(float x, float y);
  long double remainderl(long double x, long double y);

  float remquo(float x, float y, int* quo);     // see \ref{library.c}
  double remquo(double x, double y, int* quo);
  long double remquo(long double x, long double y, int* quo);   // see \ref{library.c}
  float remquof(float x, float y, int* quo);
  long double remquol(long double x, long double y, int* quo);

  float copysign(float x, float y);     // see \ref{library.c}
  double copysign(double x, double y);
  long double copysign(long double x, long double y);   // see \ref{library.c}
  float copysignf(float x, float y);
  long double copysignl(long double x, long double y);

  double nan(const char* tagp);
  float nanf(const char* tagp);
  long double nanl(const char* tagp);

  float nextafter(float x, float y);    // see \ref{library.c}
  double nextafter(double x, double y);
  long double nextafter(long double x, long double y);  // see \ref{library.c}
  float nextafterf(float x, float y);
  long double nextafterl(long double x, long double y);

  float nexttoward(float x, long double y);     // see \ref{library.c}
  double nexttoward(double x, long double y);
  long double nexttoward(long double x, long double y);     // see \ref{library.c}
  float nexttowardf(float x, long double y);
  long double nexttowardl(long double x, long double y);

  float fdim(float x, float y);         // see \ref{library.c}
  double fdim(double x, double y);
  long double fdim(long double x, long double y);   // see \ref{library.c}
  float fdimf(float x, float y);
  long double fdiml(long double x, long double y);

  float fmax(float x, float y);         // see \ref{library.c}
  double fmax(double x, double y);
  long double fmax(long double x, long double y);   // see \ref{library.c}
  float fmaxf(float x, float y);
  long double fmaxl(long double x, long double y);

  float fmin(float x, float y);         // see \ref{library.c}
  double fmin(double x, double y);
  long double fmin(long double x, long double y);   // see \ref{library.c}
  float fminf(float x, float y);
  long double fminl(long double x, long double y);

  float fma(float x, float y, float z); // see \ref{library.c}
  double fma(double x, double y, double z);
  long double fma(long double x, long double y, long double z); // see \ref{library.c}
  float fmaf(float x, float y, float z);
  long double fmal(long double x, long double y, long double z);

  // \ref{c.math.lerp}, linear interpolation
  constexpr float lerp(float a, float b, float t);
  constexpr double lerp(double a, double b, double t);
  constexpr long double lerp(long double a, long double b, long double t);

  // \ref{c.math.fpclass}, classification / comparison functions
  int fpclassify(float x);
  int fpclassify(double x);
  int fpclassify(long double x);

  bool isfinite(float x);
  bool isfinite(double x);
  bool isfinite(long double x);

  bool isinf(float x);
  bool isinf(double x);
  bool isinf(long double x);

  bool isnan(float x);
  bool isnan(double x);
  bool isnan(long double x);

  bool isnormal(float x);
  bool isnormal(double x);
  bool isnormal(long double x);

  bool signbit(float x);
  bool signbit(double x);
  bool signbit(long double x);

  bool isgreater(float x, float y);
  bool isgreater(double x, double y);
  bool isgreater(long double x, long double y);

  bool isgreaterequal(float x, float y);
  bool isgreaterequal(double x, double y);
  bool isgreaterequal(long double x, long double y);

  bool isless(float x, float y);
  bool isless(double x, double y);
  bool isless(long double x, long double y);

  bool islessequal(float x, float y);
  bool islessequal(double x, double y);
  bool islessequal(long double x, long double y);

  bool islessgreater(float x, float y);
  bool islessgreater(double x, double y);
  bool islessgreater(long double x, long double y);

  bool isunordered(float x, float y);
  bool isunordered(double x, double y);
  bool isunordered(long double x, long double y);

  // \ref{sf.cmath}, mathematical special functions

  // \ref{sf.cmath.assoc.laguerre}, associated Laguerre polynomials
  double       assoc_laguerre(unsigned n, unsigned m, double x);
  float        assoc_laguerref(unsigned n, unsigned m, float x);
  long double  assoc_laguerrel(unsigned n, unsigned m, long double x);

  // \ref{sf.cmath.assoc.legendre}, associated Legendre functions
  double       assoc_legendre(unsigned l, unsigned m, double x);
  float        assoc_legendref(unsigned l, unsigned m, float x);
  long double  assoc_legendrel(unsigned l, unsigned m, long double x);

  // \ref{sf.cmath.beta}, beta function
  double       beta(double x, double y);
  float        betaf(float x, float y);
  long double  betal(long double x, long double y);

  // \ref{sf.cmath.comp.ellint.1}, complete elliptic integral of the first kind
  double       comp_ellint_1(double k);
  float        comp_ellint_1f(float k);
  long double  comp_ellint_1l(long double k);

  // \ref{sf.cmath.comp.ellint.2}, complete elliptic integral of the second kind
  double       comp_ellint_2(double k);
  float        comp_ellint_2f(float k);
  long double  comp_ellint_2l(long double k);

  // \ref{sf.cmath.comp.ellint.3}, complete elliptic integral of the third kind
  double       comp_ellint_3(double k, double nu);
  float        comp_ellint_3f(float k, float nu);
  long double  comp_ellint_3l(long double k, long double nu);

  // \ref{sf.cmath.cyl.bessel.i}, regular modified cylindrical Bessel functions
  double       cyl_bessel_i(double nu, double x);
  float        cyl_bessel_if(float nu, float x);
  long double  cyl_bessel_il(long double nu, long double x);

  // \ref{sf.cmath.cyl.bessel.j}, cylindrical Bessel functions of the first kind
  double       cyl_bessel_j(double nu, double x);
  float        cyl_bessel_jf(float nu, float x);
  long double  cyl_bessel_jl(long double nu, long double x);

  // \ref{sf.cmath.cyl.bessel.k}, irregular modified cylindrical Bessel functions
  double       cyl_bessel_k(double nu, double x);
  float        cyl_bessel_kf(float nu, float x);
  long double  cyl_bessel_kl(long double nu, long double x);

  // \ref{sf.cmath.cyl.neumann}, cylindrical Neumann functions;
  // cylindrical Bessel functions of the second kind
  double       cyl_neumann(double nu, double x);
  float        cyl_neumannf(float nu, float x);
  long double  cyl_neumannl(long double nu, long double x);

  // \ref{sf.cmath.ellint.1}, incomplete elliptic integral of the first kind
  double       ellint_1(double k, double phi);
  float        ellint_1f(float k, float phi);
  long double  ellint_1l(long double k, long double phi);

  // \ref{sf.cmath.ellint.2}, incomplete elliptic integral of the second kind
  double       ellint_2(double k, double phi);
  float        ellint_2f(float k, float phi);
  long double  ellint_2l(long double k, long double phi);

  // \ref{sf.cmath.ellint.3}, incomplete elliptic integral of the third kind
  double       ellint_3(double k, double nu, double phi);
  float        ellint_3f(float k, float nu, float phi);
  long double  ellint_3l(long double k, long double nu, long double phi);

  // \ref{sf.cmath.expint}, exponential integral
  double       expint(double x);
  float        expintf(float x);
  long double  expintl(long double x);

  // \ref{sf.cmath.hermite}, Hermite polynomials
  double       hermite(unsigned n, double x);
  float        hermitef(unsigned n, float x);
  long double  hermitel(unsigned n, long double x);

  // \ref{sf.cmath.laguerre}, Laguerre polynomials
  double       laguerre(unsigned n, double x);
  float        laguerref(unsigned n, float x);
  long double  laguerrel(unsigned n, long double x);

  // \ref{sf.cmath.legendre}, Legendre polynomials
  double       legendre(unsigned l, double x);
  float        legendref(unsigned l, float x);
  long double  legendrel(unsigned l, long double x);

  // \ref{sf.cmath.riemann.zeta}, Riemann zeta function
  double       riemann_zeta(double x);
  float        riemann_zetaf(float x);
  long double  riemann_zetal(long double x);

  // \ref{sf.cmath.sph.bessel}, spherical Bessel functions of the first kind
  double       sph_bessel(unsigned n, double x);
  float        sph_besself(unsigned n, float x);
  long double  sph_bessell(unsigned n, long double x);

  // \ref{sf.cmath.sph.legendre}, spherical associated Legendre functions
  double       sph_legendre(unsigned l, unsigned m, double theta);
  float        sph_legendref(unsigned l, unsigned m, float theta);
  long double  sph_legendrel(unsigned l, unsigned m, long double theta);

  // \ref{sf.cmath.sph.neumann}, spherical Neumann functions;
  // spherical Bessel functions of the second kind
  double       sph_neumann(unsigned n, double x);
  float        sph_neumannf(unsigned n, float x);
  long double  sph_neumannl(unsigned n, long double x);
}
\end{codeblock}

\pnum
The contents and meaning of the header \libheader{cmath}
are the same as the C standard library header \libheader{math.h},
with the addition of
a three-dimensional hypotenuse function~(\ref{c.math.hypot3}) and
the mathematical special functions described in \ref{sf.cmath}.
\begin{note}
Several functions have additional overloads in this document,
but they have the same behavior as in the C standard library\iref{library.c}.
\end{note}

\pnum
For each set of overloaded functions within \libheader{cmath},
with the exception of \tcode{abs},
there shall be additional overloads sufficient to ensure:
\begin{enumerate}
  \item If any argument of arithmetic type
    corresponding to a \tcode{double} parameter
    has type \tcode{long double},
    then all arguments of arithmetic type\iref{basic.fundamental}
    corresponding to \tcode{double} parameters
    are effectively cast to \tcode{long double}.
  \item Otherwise, if any argument of arithmetic type
    corresponding to a \tcode{double} parameter
    has type \tcode{double}
    or an integer type,
    then all arguments of arithmetic type
    corresponding to \tcode{double} parameters
    are effectively cast to \tcode{double}.
  \item Otherwise, all arguments of arithmetic type
    corresponding to \tcode{double} parameters
    have type \tcode{float}.
\end{enumerate}
\begin{note}
\tcode{abs} is exempted from these rules in order to stay compatible with C.
\end{note}

\xref
ISO C 7.12

\rSec2[c.math.abs]{Absolute values}

\pnum
\begin{note}
The headers \libheaderref{cstdlib} and
\libheaderref{cmath}
declare the functions described in this subclause.
\end{note}

\indexlibraryglobal{abs}%
\begin{itemdecl}
int abs(int j);
long int abs(long int j);
long long int abs(long long int j);
float abs(float j);
double abs(double j);
long double abs(long double j);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
The \tcode{abs}
functions have the semantics specified in the C standard library
for the functions \tcode{abs}, \tcode{labs}, \tcode{llabs},
\tcode{fabsf}, \tcode{fabs}, and \tcode{fabsl}.

\pnum
\remarks
If \tcode{abs()} is called with an argument of type \tcode{X}
for which \tcode{is_unsigned_v<X>} is \tcode{true} and
if \tcode{X} cannot be converted to \tcode{int}
by integral promotion\iref{conv.prom}, the program is ill-formed.
\begin{note}
Arguments that can be promoted to \tcode{int} are permitted for compatibility with C.
\end{note}
\end{itemdescr}

\xrefc{7.12.7.2, 7.22.6.1}

\rSec2[c.math.hypot3]{Three-dimensional hypotenuse}

\indexlibrary{\idxcode{hypot}!3-argument form}%
\begin{itemdecl}
float hypot(float x, float y, float z);
double hypot(double x, double y, double z);
long double hypot(long double x, long double y, long double z);
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
$\sqrt{x^2+y^2+z^2}$.
\end{itemdescr}

\rSec2[c.math.lerp]{Linear interpolation}

\indexlibraryglobal{lerp}%
\begin{itemdecl}
constexpr float lerp(float a, float b, float t);
constexpr double lerp(double a, double b, double t);
constexpr long double lerp(long double a, long double b, long double t);
\end{itemdecl}
\begin{itemdescr}
\pnum
\returns
$a+t(b-a)$.

\pnum
\remarks
Let \tcode{r} be the value returned.
If \tcode{isfinite(a) \&\& isfinite(b)}, then:
\begin{itemize}
\item If \tcode{t == 0}, then \tcode{r == a}.
\item If \tcode{t == 1}, then \tcode{r == b}.
\item If \tcode{t >= 0 \&\& t <= 1}, then \tcode{isfinite(r)}.
\item If \tcode{isfinite(t) \&\& a == b}, then \tcode{r == a}.
\item If \tcode{isfinite(t) || !isnan(t) \&\& b-a != 0}, then \tcode{!isnan(r)}.
\end{itemize}
Let \tcode{\placeholder{CMP}(x,y)} be \tcode{1} if \tcode{x > y},
\tcode{-1} if \tcode{x < y}, and \tcode{0} otherwise.
For any \tcode{t1} and \tcode{t2}, the product of
\tcode{\placeholder{CMP}(lerp(a, b, t2), lerp(a, b, t1))},
\tcode{\placeholder{CMP}(t2, t1)}, and
\tcode{\placeholder{CMP}(b, a)}
is non-negative.
\end{itemdescr}

\rSec2[c.math.fpclass]{Classification / comparison functions}

\pnum
The classification / comparison functions behave the same as the C macros with the
corresponding names defined in the C standard library.
Each function is overloaded for the three floating-point types.

\xref
ISO C 7.12.3, 7.12.4

\rSec2[sf.cmath]{Mathematical special functions}%
\indextext{mathematical special functions|(}%

\pnum
\indextext{NaN}\indextext{domain error}%
If any argument value
to any of the functions specified in this subclause
is a NaN (Not a Number),
the function shall return a NaN
but it shall not report a domain error.
Otherwise,
the function shall report a domain error
for just those argument values
for which:
\begin{itemize}
  \item
  the function description's \returns clause
  explicitly specifies a domain
  and those argument values fall
  outside the specified domain,
  or

  \item
  the corresponding mathematical function value
  has a nonzero imaginary component,
  or

  \item
  the corresponding mathematical function
  is not mathematically defined.\footnote{%
    A mathematical function
    is mathematically defined
    for a given set of argument values
    (a)
      if it is explicitly defined
      for that set of argument values,
      or
    (b)
      if its limiting value exists
      and does not depend
      on the direction of approach.}
\end{itemize}

\pnum
Unless otherwise specified,
each function is defined
for all finite values,
for negative infinity,
and for positive infinity.

\rSec3[sf.cmath.assoc.laguerre]{Associated Laguerre polynomials}%
\indexlibraryglobal{assoc_laguerre}%
\indexlibraryglobal{assoc_laguerref}%
\indexlibraryglobal{assoc_laguerrel}%
\indextext{Laguerre polynomials!$\mathsf{L}_n^m$}%
\indextext{L nm@$\mathsf{L}_n^m$ (associated Laguerre polynomials)}%
\begin{itemdecl}
double       assoc_laguerre(unsigned n, unsigned m, double x);
float        assoc_laguerref(unsigned n, unsigned m, float x);
long double  assoc_laguerrel(unsigned n, unsigned m, long double x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute
the associated Laguerre polynomials
of their respective arguments
\tcode{n}, \tcode{m}, and \tcode{x}.

\pnum
\returns
\[ \mathsf{L}_n^m(x) =
   (-1)^m \frac{\mathsf{d} ^ m}{\mathsf{d}x ^ m} \, \mathsf{L}_{n+m}(x)
   \text{ ,\quad for $x \ge 0$,} \]
where
$n$ is \tcode{n},
$m$ is \tcode{m}, and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling associated Laguerre polynomials with \tcode{n >= 128} or \tcode{m >= 128}}
if \tcode{n >= 128} or if \tcode{m >= 128}.
\end{itemdescr}

\rSec3[sf.cmath.assoc.legendre]{Associated Legendre functions}%
\indexlibraryglobal{assoc_legendre}%
\indexlibraryglobal{assoc_legendref}%
\indexlibraryglobal{assoc_legendrel}%
\indextext{Legendre polynomials!$\mathsf{P}_\ell^m$}%
\indextext{P lm@$\mathsf{P}_\ell^m$ (associated Legendre polynomials)}%
\begin{itemdecl}
double       assoc_legendre(unsigned l, unsigned m, double x);
float        assoc_legendref(unsigned l, unsigned m, float x);
long double  assoc_legendrel(unsigned l, unsigned m, long double x);
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects
These functions compute
the associated Legendre functions
of their respective arguments
\tcode{l}, \tcode{m}, and \tcode{x}.

\pnum
\returns
\[ \mathsf{P}_\ell^m(x) = (1 - x^2) ^ {m/2} \:
   \frac{\mathsf{d} ^ m}{\mathsf{d}x ^ m} \, \mathsf{P}_\ell(x)
   \text{ ,\quad for $|x| \le 1$,} \]
where
$l$ is \tcode{l},
$m$ is \tcode{m}, and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling associated Legendre polynomials with \tcode{l >= 128}}
if \tcode{l >= 128}.
\end{itemdescr}

\rSec3[sf.cmath.beta]{Beta function}%
\indexlibraryglobal{beta}%
\indexlibraryglobal{betaf}%
\indexlibraryglobal{betal}%
\indextext{Eulerian integral of the first kind|see{\tcode{beta}}}%
\indextext{beta functions $\mathsf{B}$}%
\begin{itemdecl}
double       beta(double x, double y);
float        betaf(float x, float y);
long double  betal(long double x, long double y);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute
the beta function
of their respective arguments
\tcode{x} and \tcode{y}.

\pnum
\returns
\[ \mathsf{B}(x, y) = \frac{\Gamma(x) \, \Gamma(y)}{\Gamma(x + y)}
   \text{ ,\quad for $x > 0$,\, $y > 0$,} \]
where
$x$ is \tcode{x} and
$y$ is \tcode{y}.
\end{itemdescr}

\rSec3[sf.cmath.comp.ellint.1]{Complete elliptic integral of the first kind}%
\indexlibraryglobal{comp_ellint_1}%
\indexlibraryglobal{comp_ellint_1f}%
\indexlibraryglobal{comp_ellint_1l}%
\indextext{elliptic integrals!complete $\mathsf{K}$}%
\indextext{K complete@$\mathsf{K}$ (complete elliptic integrals)}%
\begin{itemdecl}
double       comp_ellint_1(double k);
float        comp_ellint_1f(float k);
long double  comp_ellint_1l(long double k);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute
the complete elliptic integral of the first kind
of their respective arguments
\tcode{k}.

\pnum
\returns
\[ \mathsf{K}(k) = \mathsf{F}(k, \pi / 2) \text{ ,\quad for $|k| \le 1$,} \]
where
$k$ is \tcode{k}.

\pnum
See also \ref{sf.cmath.ellint.1}.
\end{itemdescr}

\rSec3[sf.cmath.comp.ellint.2]{Complete elliptic integral of the second kind}%
\indexlibraryglobal{comp_ellint_2}%
\indexlibraryglobal{comp_ellint_2f}%
\indexlibraryglobal{comp_ellint_2l}%
\indextext{elliptic integrals!complete $\mathsf{E}$}%
\indextext{E complete@$\mathsf{E}$ (complete elliptic integrals)}%
\begin{itemdecl}
double       comp_ellint_2(double k);
float        comp_ellint_2f(float k);
long double  comp_ellint_2l(long double k);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute
the complete elliptic integral of the second kind
of their respective arguments
\tcode{k}.

\pnum
\returns
\[ \mathsf{E}(k) = \mathsf{E}(k, \pi / 2) \text{ ,\quad for $|k| \le 1$,} \]
where
$k$ is \tcode{k}.

\pnum
See also \ref{sf.cmath.ellint.2}.
\end{itemdescr}

\rSec3[sf.cmath.comp.ellint.3]{Complete elliptic integral of the third kind}%
\indexlibraryglobal{comp_ellint_3}%
\indexlibraryglobal{comp_ellint_3f}%
\indexlibraryglobal{comp_ellint_3l}%
\indextext{elliptic integrals!complete $\mathsf{\Pi}$}%
\indextext{Pi complete@$\mathsf{\Pi}$ (complete elliptic integrals)}%
\begin{itemdecl}
double       comp_ellint_3(double k, double nu);
float        comp_ellint_3f(float k, float nu);
long double  comp_ellint_3l(long double k, long double nu);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute
the complete elliptic integral of the third kind
of their respective arguments
\tcode{k} and \tcode{nu}.

\pnum
\returns
\[ \mathsf{\Pi}(\nu, k) = \mathsf{\Pi}(\nu, k, \pi / 2) \text{ ,\quad for $|k| \le 1$,} \]
where
$k$ is \tcode{k} and
$\nu$ is \tcode{nu}.

\pnum
See also \ref{sf.cmath.ellint.3}.
\end{itemdescr}

\rSec3[sf.cmath.cyl.bessel.i]{Regular modified cylindrical Bessel functions}%
\indexlibraryglobal{cyl_bessel_i}%
\indexlibraryglobal{cyl_bessel_if}%
\indexlibraryglobal{cyl_bessel_il}%
\indextext{Bessel functions!$\mathsf{I}_\nu$}%
\indextext{I nu@$\mathsf{I}_\nu$ (Bessell functions)}%
\begin{itemdecl}
double       cyl_bessel_i(double nu, double x);
float        cyl_bessel_if(float nu, float x);
long double  cyl_bessel_il(long double nu, long double x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute
the regular modified cylindrical Bessel functions
of their respective arguments
\tcode{nu} and \tcode{x}.

\pnum
\returns
\[ \mathsf{I}_\nu(x) =
     \mathrm{i}^{-\nu} \mathsf{J}_\nu(\mathrm{i}x) =
     \sum_{k=0}^\infty \frac{(x/2)^{\nu+2k}}{k! \: \Gamma(\nu+k+1)}
     \text{ ,\quad for $x \ge 0$,} \]
where
$\nu$ is \tcode{nu} and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling regular modified cylindrical Bessel functions with \tcode{nu >= 128}}
if \tcode{nu >= 128}.

\pnum
See also \ref{sf.cmath.cyl.bessel.j}.
\end{itemdescr}

\rSec3[sf.cmath.cyl.bessel.j]{Cylindrical Bessel functions of the first kind}%
\indexlibraryglobal{cyl_bessel_j}%
\indexlibraryglobal{cyl_bessel_jf}%
\indexlibraryglobal{cyl_bessel_jl}%
\indextext{Bessel functions!$\mathsf{J}_\nu$}%
\indextext{J nu@$\mathsf{J}_\nu$ (Bessell functions)}%
\begin{itemdecl}
double       cyl_bessel_j(double nu, double x);
float        cyl_bessel_jf(float nu, float x);
long double  cyl_bessel_jl(long double nu, long double x);
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects
These functions compute
the cylindrical Bessel functions of the first kind
of their respective arguments
\tcode{nu} and \tcode{x}.

\pnum
\returns
\[ \mathsf{J}_\nu(x) =
   \sum_{k=0}^\infty \frac{(-1)^k (x/2)^{\nu+2k}}{k! \: \Gamma(\nu+k+1)}
   \text{ ,\quad for $x \ge 0$,} \]
where
$\nu$ is \tcode{nu} and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling cylindrical Bessel functions of the first kind with \tcode{nu >= 128}}
if \tcode{nu >= 128}.
\end{itemdescr}

\rSec3[sf.cmath.cyl.bessel.k]{Irregular modified cylindrical Bessel functions}%
\indexlibraryglobal{cyl_bessel_k}%
\indexlibraryglobal{cyl_bessel_kf}%
\indexlibraryglobal{cyl_bessel_kl}%
\indextext{Bessel functions!$\mathsf{K}_\nu$}%
\indextext{K nu@$\mathsf{K}_\nu$ (Bessell functions)}%
\begin{itemdecl}
double       cyl_bessel_k(double nu, double x);
float        cyl_bessel_kf(float nu, float x);
long double  cyl_bessel_kl(long double nu, long double x);
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects
These functions compute
the irregular modified cylindrical Bessel functions
of their respective arguments
\tcode{nu} and \tcode{x}.

\pnum
\returns
\[%
  \mathsf{K}_\nu(x) =
  (\pi/2)\mathrm{i}^{\nu+1} (            \mathsf{J}_\nu(\mathrm{i}x)
			    + \mathrm{i} \mathsf{N}_\nu(\mathrm{i}x)
			    )
  =
  \left\{
  \begin{array}{cl}
  \displaystyle
  \frac{\pi}{2}
  \frac{\mathsf{I}_{-\nu}(x) - \mathsf{I}_{\nu}(x)}
       {\sin \nu\pi },
  & \mbox{for $x \ge 0$ and non-integral $\nu$}
  \\
  \\
  \displaystyle
  \frac{\pi}{2}
  \lim_{\mu \rightarrow \nu} \frac{\mathsf{I}_{-\mu}(x) - \mathsf{I}_{\mu}(x)}
                                  {\sin \mu\pi },
  & \mbox{for $x \ge 0$ and integral $\nu$}
  \end{array}
  \right.
\]
where
$\nu$ is \tcode{nu} and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling irregular modified cylindrical Bessel functions with \tcode{nu >= 128}}
if \tcode{nu >= 128}.

\pnum
See also \ref{sf.cmath.cyl.bessel.i}, \ref{sf.cmath.cyl.bessel.j}, \ref{sf.cmath.cyl.neumann}.
\end{itemdescr}

\rSec3[sf.cmath.cyl.neumann]{Cylindrical Neumann functions}%
\indexlibraryglobal{cyl_neumann}%
\indexlibraryglobal{cyl_neumannf}%
\indexlibraryglobal{cyl_neumannl}%
\indextext{Bessel functions!$\mathsf{N}_\nu$}%
\indextext{Neumann functions!$\mathsf{N}_\nu$}%
\indextext{N nu@$\mathsf{N}_\nu$ (Neumann functions)}%
\begin{itemdecl}
double       cyl_neumann(double nu, double x);
float        cyl_neumannf(float nu, float x);
long double  cyl_neumannl(long double nu, long double x);
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects
These functions compute the cylindrical Neumann functions,
also known as the cylindrical Bessel functions of the second kind,
of their respective arguments
\tcode{nu} and \tcode{x}.

\pnum
\returns
\[%
  \mathsf{N}_\nu(x) =
  \left\{
  \begin{array}{cl}
  \displaystyle
  \frac{\mathsf{J}_\nu(x) \cos \nu\pi - \mathsf{J}_{-\nu}(x)}
       {\sin \nu\pi },
  & \mbox{for $x \ge 0$ and non-integral $\nu$}
  \\
  \\
  \displaystyle
  \lim_{\mu \rightarrow \nu} \frac{\mathsf{J}_\mu(x) \cos \mu\pi - \mathsf{J}_{-\mu}(x)}
                                {\sin \mu\pi },
  & \mbox{for $x \ge 0$ and integral $\nu$}
  \end{array}
  \right.
\]
where
$\nu$ is \tcode{nu} and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling cylindrical Neumann functions with \tcode{nu >= 128}}
if \tcode{nu >= 128}.

\pnum
See also \ref{sf.cmath.cyl.bessel.j}.
\end{itemdescr}

\rSec3[sf.cmath.ellint.1]{Incomplete elliptic integral of the first kind}%
\indexlibraryglobal{ellint_1}%
\indexlibraryglobal{ellint_1f}%
\indexlibraryglobal{ellint_1l}%
\indextext{elliptic integrals!incomplete $\mathsf{F}$}%
\indextext{F incomplete@$\mathsf{F}$ (incomplete elliptic integrals)}%
\begin{itemdecl}
double       ellint_1(double k, double phi);
float        ellint_1f(float k, float phi);
long double  ellint_1l(long double k, long double phi);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute
the incomplete elliptic integral of the first kind
of their respective arguments
\tcode{k} and \tcode{phi} (\tcode{phi} measured in radians).

\pnum
\returns
\[ \mathsf{F}(k, \phi) =
     \int_0^\phi \! \frac{\mathsf{d}\theta}{\sqrt{1 - k^2 \sin^2 \theta}}
     \text{ ,\quad for $|k| \le 1$,} \]
where
$k$ is \tcode{k} and
$\phi$ is \tcode{phi}.
\end{itemdescr}

\rSec3[sf.cmath.ellint.2]{Incomplete elliptic integral of the second kind}%
\indexlibraryglobal{ellint_2}%
\indexlibraryglobal{ellint_2f}%
\indexlibraryglobal{ellint_2l}%
\indextext{elliptic integrals!incomplete $\mathsf{E}$}%
\indextext{E incomplete@$\mathsf{E}$ (incomplete elliptic integrals)}%
\begin{itemdecl}
double       ellint_2(double k, double phi);
float        ellint_2f(float k, float phi);
long double  ellint_2l(long double k, long double phi);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute
the incomplete elliptic integral of the second kind
of their respective arguments
\tcode{k} and \tcode{phi} (\tcode{phi} measured in radians).

\pnum
\returns
\[ \mathsf{E}(k, \phi) = \int_0^\phi \! \sqrt{1 - k^2 \sin^2 \theta} \, \mathsf{d}\theta
   \text{ ,\quad for $|k| \le 1$,} \]
where
$k$ is \tcode{k} and
$\phi$ is \tcode{phi}.
\end{itemdescr}

\rSec3[sf.cmath.ellint.3]{Incomplete elliptic integral of the third kind}%
\indexlibraryglobal{ellint_3}%
\indexlibraryglobal{ellint_3f}%
\indexlibraryglobal{ellint_3l}%
\indextext{elliptic integrals!incomplete $\mathsf{\Pi}$}%
\indextext{Pi incomplete@$\mathsf{\Pi}$ (incomplete elliptic integrals)}%
\begin{itemdecl}
double       ellint_3(double k, double nu, double phi);
float        ellint_3f(float k, float nu, float phi);
long double  ellint_3l(long double k, long double nu, long double phi);
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects
These functions compute
the incomplete elliptic integral of the third kind
of their respective arguments
\tcode{k}, \tcode{nu}, and \tcode{phi} (\tcode{phi} measured in radians).

\pnum
\returns
\[ \mathsf{\Pi}(\nu, k, \phi) = \int_0^\phi \!
   \frac{ \mathsf{d}\theta }{ (1 - \nu \, \sin^2 \theta) \sqrt{1 - k^2 \sin^2 \theta} } \text{ ,\quad for $|k| \le 1$,} \]
where
$\nu$ is \tcode{nu},
$k$ is \tcode{k}, and
$\phi$ is \tcode{phi}.
\end{itemdescr}

\rSec3[sf.cmath.expint]{Exponential integral}%
\indexlibraryglobal{expint}%
\indexlibraryglobal{expintf}%
\indexlibraryglobal{expintl}%
\indextext{exponential integrals $\mathsf{Ei}$}%
\indextext{Ei@$\mathsf{Ei}$ (exponential integrals)}%
\begin{itemdecl}
double       expint(double x);
float        expintf(float x);
long double  expintl(long double x);
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects
These functions compute the exponential integral
of their respective arguments
\tcode{x}.

\pnum
\returns
\[%
  \mathsf{Ei}(x) =
  - \int_{-x}^\infty \frac{e^{-t}}
                          {t     } \, \mathsf{d}t
\;
\]
where
$x$ is \tcode{x}.

\end{itemdescr}

\rSec3[sf.cmath.hermite]{Hermite polynomials}%
\indexlibraryglobal{hermite}%
\indexlibraryglobal{hermitef}%
\indexlibraryglobal{hermitel}%
\indextext{Hermite polynomials $\mathsf{H}_n$}%
\indextext{H n@$\mathsf{H}_n$ (Hermite polynomials)}%
\begin{itemdecl}
double       hermite(unsigned n, double x);
float        hermitef(unsigned n, float x);
long double  hermitel(unsigned n, long double x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute the Hermite polynomials
of their respective arguments
\tcode{n} and \tcode{x}.

\pnum
\returns
\[%
  \mathsf{H}_n(x) =
  (-1)^n e^{x^2} \frac{ \mathsf{d} ^n}
		      { \mathsf{d}x^n} \, e^{-x^2}
\;
\]
where
$n$ is \tcode{n} and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling Hermite polynomials with \tcode{n >= 128}}
if \tcode{n >= 128}.
\end{itemdescr}

\rSec3[sf.cmath.laguerre]{Laguerre polynomials}%
\indexlibraryglobal{laguerre}%
\indexlibraryglobal{laguerref}%
\indexlibraryglobal{laguerrel}%
\indextext{Laguerre polynomials!$\mathsf{L}_n$}%
\indextext{L n@$\mathsf{L}_n$ (Laguerre polynomials)}%
\begin{itemdecl}
double       laguerre(unsigned n, double x);
float        laguerref(unsigned n, float x);
long double  laguerrel(unsigned n, long double x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute the Laguerre polynomials
of their respective arguments
\tcode{n} and \tcode{x}.

\pnum
\returns
\[ \mathsf{L}_n(x) =
     \frac{e^x}{n!} \frac{\mathsf{d}^n}{\mathsf{d}x^n} \, (x^n e^{-x})
     \text{ ,\quad for $x \ge 0$,} \]
where
$n$ is \tcode{n} and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling Laguerre polynomials with \tcode{n >= 128}}
if \tcode{n >= 128}.
\end{itemdescr}

\rSec3[sf.cmath.legendre]{Legendre polynomials}%
\indexlibraryglobal{legendre}%
\indexlibraryglobal{legendref}%
\indexlibraryglobal{legendrel}%
\indextext{Legendre polynomials!$\mathsf{P}_\ell$}%
\indextext{P l@$\mathsf{P}_\ell$ (Legendre polynomials)}%
\begin{itemdecl}
double       legendre(unsigned l, double x);
float        legendref(unsigned l, float x);
long double  legendrel(unsigned l, long double x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute the Legendre polynomials of their
respective arguments
\tcode{l} and \tcode{x}.

\pnum
\returns
\[ \mathsf{P}_\ell(x) =
     \frac{1}{2^\ell \, \ell!}
     \frac{\mathsf{d}^\ell}{\mathsf{d}x^\ell} \, (x^2 - 1) ^ \ell
     \text{ ,\quad for $|x| \le 1$,} \]
where
$l$ is \tcode{l} and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling Legendre polynomials with \tcode{l >= 128}}
if \tcode{l >= 128}.
\end{itemdescr}

\rSec3[sf.cmath.riemann.zeta]{Riemann zeta function}%
\indexlibraryglobal{riemann_zeta}%
\indexlibraryglobal{riemann_zetaf}%
\indexlibraryglobal{riemann_zetal}%
\indextext{zeta functions $\zeta$}%
\begin{itemdecl}
double       riemann_zeta(double x);
float        riemann_zetaf(float x);
long double  riemann_zetal(long double x);
\end{itemdecl}

\begin{itemdescr}

\pnum
\effects
These functions compute the Riemann zeta function
of their respective arguments
\tcode{x}.

\pnum
\returns
\[%
  \mathsf{\zeta}(x) =
  \left\{
  \begin{array}{cl}
  \displaystyle
  \sum_{k=1}^\infty k^{-x},
  & \mbox{for $x > 1$}
  \\
  \\
  \displaystyle
  \frac{1}
	{1 - 2^{1-x}}
  \sum_{k=1}^\infty (-1)^{k-1} k^{-x},
  & \mbox{for $0 \le x \le 1$}
  \\
  \\
  \displaystyle
  2^x \pi^{x-1} \sin(\frac{\pi x}{2}) \, \Gamma(1-x) \, \zeta(1-x),
  & \mbox{for $x < 0$}
  \end{array}
  \right.
\;
\]
where
$x$ is \tcode{x}.
\end{itemdescr}

\rSec3[sf.cmath.sph.bessel]{Spherical Bessel functions of the first kind}%
\indexlibraryglobal{sph_bessel}%
\indexlibraryglobal{sph_besself}%
\indexlibraryglobal{sph_bessell}%
\indextext{Bessel functions!$\mathsf{j}_n$}%
\indextext{j n@$\mathsf{j}_n$ (spherical Bessel functions)}%
\begin{itemdecl}
double       sph_bessel(unsigned n, double x);
float        sph_besself(unsigned n, float x);
long double  sph_bessell(unsigned n, long double x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute
the spherical Bessel functions of the first kind
of their respective arguments
\tcode{n} and \tcode{x}.

\pnum
\returns
\[ \mathsf{j}_n(x) = (\pi/2x)^{1\!/\!2} \mathsf{J}_{n + 1\!/\!2}(x) \text{ ,\quad for $x \ge 0$,} \]
where
$n$ is \tcode{n} and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling spherical Bessel functions with \tcode{n >= 128}}
if \tcode{n >= 128}.

\pnum
See also \ref{sf.cmath.cyl.bessel.j}.
\end{itemdescr}

\rSec3[sf.cmath.sph.legendre]{Spherical associated Legendre functions}%
\indexlibraryglobal{sph_legendre}%
\indexlibraryglobal{sph_legendref}%
\indexlibraryglobal{sph_legendrel}%
\indextext{spherical harmonics $\mathsf{Y}_\ell^m$}%
\indextext{Legendre functions $\mathsf{Y}_\ell^m$}%
\indextext{Y lm@$\mathsf{Y}_\ell^m$ (spherical associated Legendre functions)}%
\begin{itemdecl}
double       sph_legendre(unsigned l, unsigned m, double theta);
float        sph_legendref(unsigned l, unsigned m, float theta);
long double  sph_legendrel(unsigned l, unsigned m, long double theta);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute the spherical associated Legendre functions
of their respective arguments
\tcode{l}, \tcode{m}, and \tcode{theta} (\tcode{theta} measured in radians).

\pnum
\returns
\[ \mathsf{Y}_\ell^m(\theta, 0) \]
where
\[ \mathsf{Y}_\ell^m(\theta, \phi) =
     (-1)^m \left[\frac{(2 \ell + 1)}{4 \pi} \frac{(\ell - m)!}{(\ell + m)!}\right]^{1/2}
     \mathsf{P}_\ell^m (\cos\theta) e^{i m \phi}
     \text{ ,\quad for $|m| \le \ell$,}
\]
and
$l$ is \tcode{l},
$m$ is \tcode{m}, and
$\theta$ is \tcode{theta}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling spherical associated Legendre functions with \tcode{l >= 128}}
if \tcode{l >= 128}.

\pnum
See also \ref{sf.cmath.assoc.legendre}.
\end{itemdescr}

\rSec3[sf.cmath.sph.neumann]{Spherical Neumann functions}%
\indexlibraryglobal{sph_neumann}%
\indexlibraryglobal{sph_neumannf}%
\indexlibraryglobal{sph_neumannl}%
\indextext{Bessel functions!$\mathsf{n}_n$}%
\indextext{Neumann functions!$\mathsf{n}_n$}%
\indextext{n n spherical@$\mathsf{n}_n$ (spherical Neumann functions)}%
\begin{itemdecl}
double       sph_neumann(unsigned n, double x);
float        sph_neumannf(unsigned n, float x);
long double  sph_neumannl(unsigned n, long double x);
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
These functions compute the spherical Neumann functions,
also known as the spherical Bessel functions of the second kind,
of their respective arguments
\tcode{n} and \tcode{x}.

\pnum
\returns
\[ \mathsf{n}_n(x) = (\pi/2x)^{1\!/\!2} \mathsf{N}_{n + 1\!/\!2}(x)
   \text{ ,\quad for $x \ge 0$,} \]
where
$n$ is \tcode{n} and
$x$ is \tcode{x}.

\pnum
\remarks
The effect of calling each of these functions
is \impldef{effect of calling spherical Neumann functions with \tcode{n >= 128}}
if \tcode{n >= 128}.

\pnum
See also \ref{sf.cmath.cyl.neumann}.
\end{itemdescr}

\indextext{mathematical special functions|)}

\rSec1[numbers]{Numbers}

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

\indexheader{numbers}%
\begin{codeblock}
namespace std::numbers {
  template<class T> inline constexpr T e_v          = @\unspec@;
  template<class T> inline constexpr T log2e_v      = @\unspec@;
  template<class T> inline constexpr T log10e_v     = @\unspec@;
  template<class T> inline constexpr T pi_v         = @\unspec@;
  template<class T> inline constexpr T inv_pi_v     = @\unspec@;
  template<class T> inline constexpr T inv_sqrtpi_v = @\unspec@;
  template<class T> inline constexpr T ln2_v        = @\unspec@;
  template<class T> inline constexpr T ln10_v       = @\unspec@;
  template<class T> inline constexpr T sqrt2_v      = @\unspec@;
  template<class T> inline constexpr T sqrt3_v      = @\unspec@;
  template<class T> inline constexpr T inv_sqrt3_v  = @\unspec@;
  template<class T> inline constexpr T egamma_v     = @\unspec@;
  template<class T> inline constexpr T phi_v        = @\unspec@;

  template<floating_point T> inline constexpr T e_v<T>          = @\seebelow@;
  template<floating_point T> inline constexpr T log2e_v<T>      = @\seebelow@;
  template<floating_point T> inline constexpr T log10e_v<T>     = @\seebelow@;
  template<floating_point T> inline constexpr T pi_v<T>         = @\seebelow@;
  template<floating_point T> inline constexpr T inv_pi_v<T>     = @\seebelow@;
  template<floating_point T> inline constexpr T inv_sqrtpi_v<T> = @\seebelow@;
  template<floating_point T> inline constexpr T ln2_v<T>        = @\seebelow@;
  template<floating_point T> inline constexpr T ln10_v<T>       = @\seebelow@;
  template<floating_point T> inline constexpr T sqrt2_v<T>      = @\seebelow@;
  template<floating_point T> inline constexpr T sqrt3_v<T>      = @\seebelow@;
  template<floating_point T> inline constexpr T inv_sqrt3_v<T>  = @\seebelow@;
  template<floating_point T> inline constexpr T egamma_v<T>     = @\seebelow@;
  template<floating_point T> inline constexpr T phi_v<T>        = @\seebelow@;

  inline constexpr double e          = e_v<double>;
  inline constexpr double log2e      = log2e_v<double>;
  inline constexpr double log10e     = log10e_v<double>;
  inline constexpr double pi         = pi_v<double>;
  inline constexpr double inv_pi     = inv_pi_v<double>;
  inline constexpr double inv_sqrtpi = inv_sqrtpi_v<double>;
  inline constexpr double ln2        = ln2_v<double>;
  inline constexpr double ln10       = ln10_v<double>;
  inline constexpr double sqrt2      = sqrt2_v<double>;
  inline constexpr double sqrt3      = sqrt3_v<double>;
  inline constexpr double inv_sqrt3  = inv_sqrt3_v<double>;
  inline constexpr double egamma     = egamma_v<double>;
  inline constexpr double phi        = phi_v<double>;
}
\end{codeblock}

\rSec2[math.constants]{Mathematical constants}

\pnum
The library-defined partial specializations
of mathematical constant variable templates
are initialized with the nearest representable values of
$\mathrm{e}$,
$\log_{2} \mathrm{e}$,
$\log_{10} \mathrm{e}$,
$\pi$,
$\frac{1}{\pi}$,
$\frac{1}{\sqrt{\pi}}$,
$\ln 2$,
$\ln 10$,
$\sqrt{2}$,
$\sqrt{3}$,
$\frac{1}{\sqrt{3}}$,
the Euler-Mascheroni $\gamma$ constant, and
the golden ratio $\phi$ constant $\frac{1+\sqrt{5}}{2}$,
respectively.

\pnum
Pursuant to \ref{namespace.std},
a program may partially or explicitly specialize
a mathematical constant variable template
provided that the specialization depends on a program-defined type.

\pnum
A program that instantiates a primary template
of a mathematical constant variable template is ill-formed.