______________________________________________________________________

  26   Numerics library                         [lib.numerics]

  ______________________________________________________________________

1 This clause describes components that C++ programs may use to  perform
  seminumerical operations.

2 The  following subclauses describe components for complex number types
  (_lib.complex_), numeric arrays (_lib.numarray_), generalized  numeric
  algorithms (_lib.numeric.ops_), and facilities included from the ISO C
  library (_lib.c.math_).

  26.1  Complex numbers                                    [lib.complex]

1 Headers:

  --<complex>

2 Table 1:

                    Table 1--Header <complex> synopsis

  +----------------------------------------------------------------------------+
  |                Type                                 Name(s)                |
  +----------------------------------------------------------------------------+
  |Macro:                                 __STD_COMPLEX                        |
  +----------------------------------------------------------------------------+
  |Classes:                               double_complex                       |
  |float_complex                          long_double_complex                  |
  +----------------------------------------------------------------------------+
  |Operator functions:                                                         |
  |operator!= (double_complex) [3]        operator-= (float_complex)           |
  |operator!= (float_complex) [3]         operator-= (long_double_complex)     |
  |operator!= (long_double_complex) [3]   operator/  (double_complex) [3]      |
  |operator*  (double_complex) [3]        operator/  (float_complex) [3]       |
  |operator*  (float_complex) [3]         operator/  (long_double_complex) [3] |
  |operator*  (long_double_complex) [3]   operator/= (double_complex)          |
  |operator*= (double_complex)            operator/= (float_complex)           |
  |operator*= (float_complex)             operator/= (long_double_complex)     |
  |operator*= (long_double_complex)       operator<< (double_complex)          |
  |operator+  (double_complex) [4]        operator<< (float_complex)           |
  |operator+  (float_complex) [4]         operator<< (long_double_complex)     |
  |operator+  (long_double_complex) [4]   operator== (double_complex) [3]      |
  |operator+= (double_complex)            operator== (float_complex) [3]       |
  |operator+= (float_complex)             operator== (long_double_complex) [3] |
  |operator+= (long_double_complex)       operator>> (double_complex)          |
  |operator-  (double_complex) [4]        operator>> (float_complex)           |
  |operator-  (float_complex) [4]         operator>> (long_double_complex)     |
  |operator-  (long_double_complex) [4]                                        |
  |operator-= (double_complex)                                                 |
  +----------------------------------------------------------------------------+

        +---------------------------------------------------------+
        |           Type                        Name(s)           |
        +---------------------------------------------------------+
        |Functions:                                               |
        |abs  (double_complex)         norm (double_complex)      |
        |abs  (float_complex)          norm (float_complex)       |
        |abs  (long_double_complex)    norm (long_double_complex) |
        |arg  (double_complex)         polar(double_complex)      |
        |arg  (float_complex)          polar(float_complex)       |
        |arg  (long_double_complex)    polar(long_double_complex) |
        |conj  (double_complex)        pow  (double_complex)      |
        |conj  (float_complex)         pow  (float_complex)       |
        |conj  (long_double_complex)   pow  (long_double_complex) |
        |cos  (double_complex)         real (double_complex)      |
        |cos  (float_complex)          real (float_complex)       |
        |cos  (long_double_complex)    real (long_double_complex) |
        |cosh (double_complex)         sin  (double_complex)      |
        |cosh (float_complex)          sin  (float_complex)       |
        |cosh (long_double_complex)    sin  (long_double_complex) |
        |exp  (double_complex)         sinh (double_complex)      |
        |exp  (float_complex)          sinh (float_complex)       |
        |exp  (long_double_complex)    sinh (long_double_complex) |
        |imag (double_complex)         sqrt (double_complex)      |
        |imag (float_complex)          sqrt (float_complex)       |
        |imag (long_double_complex)    sqrt (long_double_complex) |
        |log  (double_complex)         _double_complex            |
        |log  (float_complex)          _float_complex             |
        |log  (long_double_complex)                               |
        +---------------------------------------------------------+

3 The header <complex> defines a macro, three types, and numerous  func­
  tions for representing and manipulating complex numbers.

4 The macro is:
          __STD_COMPLEX

5 whose definition is unspecified.

  26.1.1  Complex numbers types                      [lib.complex.types]

  26.1.1.1  Class float_complex                      [lib.float.complex]
      class float_complex {
      public:
          float_complex(float re_arg = 0, im_arg = 0);
          float_complex& operator+=(float_complex rhs);
          float_complex& operator-=(float_complex rhs);
          float_complex& operator*=(float_complex rhs);
          float_complex& operator/=(float_complex rhs);
      private:
  //      float re, im;   exposition only
      };

1 The  class float_complex describes an object that can store the Carte­
  sian components, of type float, of a complex number.

2 For the sake of exposition, the maintained data is presented here as:

  --float re, the real component;

  --float im, the imaginary component.

  26.1.1.1.1  float_complex constructor         [lib.float.complex.cons]
      float_complex(float re_arg = 0, im_arg = 0);

1 Constructs an object of class float_complex, initializing re to re_arg
  and im to im_arg.

  26.1.1.1.2  operator+=                                   [lib.op+=.fc]
      float_complex& operator+=(float_complex rhs);

1 Adds  the  complex value rhs to the complex value *this and stores the
  sum in *this.  The function returns *this.

  26.1.1.1.3  operator-=                                   [lib.op-=.fc]
      float_complex& operator-=(float_complex rhs);

1 Subtracts the complex value rhs  from  the  complex  value  *this  and
  stores the difference in *this.  The function returns *this.

  26.1.1.1.4  operator*=                                   [lib.op*=.fc]
      float_complex& operator*=(float_complex rhs);

1 Multiplies the complex value rhs by the complex value *this and stores
  the product in *this.  The function returns *this.

  26.1.1.1.5  operator/=                                   [lib.op/=.fc]
      float_complex& operator/=(float_complex rhs);

1 Divides the complex value rhs into the complex value *this and  stores
  the quotient in *this.  The function returns *this.

  26.1.1.2  float_complex operations             [lib.float.complex.ops]

  26.1.1.2.1  _float_complex                      [lib.float.complex.dc]
      float_complex _float_complex(const double_complex& rhs);
      float_complex _float_complex(const long_double_complex& rhs);

1 Returns float_complex((float)real(rhs), (float)imag(rhs)).

  26.1.1.2.2  operator+                                  [lib.op+.fc.fc]
      float_complex operator+(float_complex lhs);

1 Returns float_complex(lhs).
      float_complex operator+(float_complex lhs, float_complex rhs);
      float_complex operator+(float_complex lhs, float rhs);
      float_complex operator+(float lhs, float_complex rhs);

2 Returns float_complex(lhs) += rhs.

  26.1.1.2.3  operator-                                  [lib.op-.fc.fc]
      float_complex operator-(float_complex lhs);

1 Returns float_complex(-real(lhs),-imag(lhs)).
      float_complex operator-(float_complex lhs, float_complex rhs);
      float_complex operator-(float_complex lhs, float rhs);
      float_complex operator-(float lhs, float_complex rhs);

2 Returns float_complex(lhs) -= rhs.

  26.1.1.2.4  operator*                                  [lib.op*.fc.fc]
      float_complex operator*(float_complex lhs, float_complex rhs);
      float_complex operator*(float_complex lhs, float rhs);
      float_complex operator*(float lhs, float_complex rhs);

1 Returns float_complex(lhs) *= rhs.

  26.1.1.2.5  operator/                                  [lib.op/.fc.fc]
      float_complex operator/(float_complex lhs, float_complex rhs);
      float_complex operator/(float_complex lhs, float rhs);
      float_complex operator/(float lhs, float_complex rhs);

1 Returns float_complex(lhs) /= rhs.

  26.1.1.2.6  operator==                                [lib.op==.fc.fc]
      bool operator==(float_complex lhs, float_complex >rhs);

1 Returns real(lhs) == real(rhs) && imag(lhs) == imag(rhs).
      bool operator==(float_complex lhs, float rhs);

2 Returns real(lhs) == rhs && imag(lhs) == 0.
      bool operator==(float lhs, float_complex rhs);

3 Returns lhs == real(rhs) && imag(rhs) == 0.

  26.1.1.2.7  operator!=                                [lib.op!=.fc.fc]
      bool operator!=(float_complex lhs, float_complex rhs);

1 Returns real(lhs) != real(rhs) || imag(lhs) != imag(rhs).
      bool operator!=(float_complex lhs, float rhs);

2 Returns real(lhs) != rhs || imag(lhs) != 0.
      bool operator!=(float lhs, float_complex rhs);

3 Returns lhs != real(rhs) || imag(rhs) != 0.

  26.1.1.2.8  operator>>                                    [lib.ext.fc]
      istream& operator>>(istream& is, float_complex& x);

1 Evaluates the expression:

      is >> ch && ch == '('
      && is >> re >> ch && ch == ','
      && is >> im >> ch && ch == ')';

2 where  ch  is an object of type char and re and im are objects of type
  float.    If   the   result   is   nonzero,   the   function   assigns
  float_complex(re, im) to x.

3 Returns is.

  26.1.1.2.9  operator<<                                    [lib.ins.fc]
      ostream& operator<<(ostream& os, float_complex x);

1 Returns os << '(' << real(x) << ',' << imag(x) << ')'.

  26.1.1.3  Class double_complex                    [lib.double.complex]
      class double_complex {
      public:
          double_complex(re_arg = 0, im_arg = 0);
          double_complex(const float_complex& rhs);
          double_complex& operator+=(double_complex rhs);
          double_complex& operator-=(double_complex rhs);
          double_complex& operator*=(double_complex rhs);
          double_complex& operator/=(double_complex rhs);
      private:
  //    double re, im;    exposition only
      };

1 The class double_complex describes an object that can store the Carte­
  sian components, of type double, of a complex number.

2 For the sake of exposition, the maintained data is presented here as:

  --double re, the real component;

  --double im, the imaginary component.

  26.1.1.3.1  double_complex constructors      [lib.double.complex.cons]
      double_complex(double re_arg = 0, im_arg = 0);

1 Constructs  an  object  of  class  double_complex,  initializing re to
  re_arg and im to im_arg.
      double_complex(float_complex& rhs);

2 Constructs an object of class double_complex, initializing re to (dou­
  ble)real(rhs) and im to (double)imag(rhs).

  26.1.1.3.2  operator+=                                   [lib.op+=.dc]
      double_complex& operator+=(double_complex rhs);

1 Adds  the  complex value rhs to the complex value *this and stores the
  sum in *this.

2 Returns *this.

  26.1.1.3.3  operator-=                                   [lib.op-=.dc]
      double_complex& operator-=(double_complex rhs);

1 Subtracts  the  complex  value  rhs  from  the complex value *this and
  stores the difference in *this.

2 Returns *this.

  26.1.1.3.4  operator*=                                   [lib.op*=.dc]
      double_complex& operator*=(double_complex rhs);

1 Multiplies the complex value rhs by the complex value *this and stores
  the product in *this.

2 Returns *this.

  26.1.1.3.5  operator/=                                   [lib.op/=.dc]
      double_complex& operator/=(double_complex rhs);

1 Divides  the complex value rhs into the complex value *this and stores
  the quotient in *this.

2 Returns *this.

  26.1.1.4  double_complex operations           [lib.double.complex.ops]

  26.1.1.4.1  _double_complex                   [lib.double.complex.ldc]
      double_complex _double_complex(const long_double_complex& rhs);

1 Returns double_complex((double)real(rhs), (double)imag(rhs)).

  26.1.1.4.2  operator+                                  [lib.op+.dc.dc]
      double_complex operator+(double_complex lhs);

1 Returns double_complex(lhs).
      double_complex operator+(double_complex lhs, double_complex rhs);
      double_complex operator+(double_complex lhs, double rhs);
      double_complex operator+(double lhs, double_complex rhs);

2 Returns double_complex(lhs) += rhs.

  26.1.1.4.3  operator-                                  [lib.op-.dc.dc]
      double_complex operator-(double_complex lhs);

1 Returns double_complex(-real(lhs),-imag(lhs)).
      double_complex operator-(double_complex lhs, double_complex rhs);
      double_complex operator-(double_complex lhs, double rhs);
      double_complex operator-(double lhs, double_complex rhs);

2 Returns double_complex(lhs) -= rhs.

  26.1.1.4.4  operator*                                  [lib.op*.dc.dc]
      double_complex operator*(double_complex lhs, double_complex rhs);
      double_complex operator*(double_complex lhs, double rhs);
      double_complex operator*(double lhs, double_complex rhs);

1 Returns double_complex(lhs) *= rhs.

  26.1.1.4.5  operator/                                  [lib.op/.dc.dc]
      double_complex operator/(double_complex lhs, double_complex rhs);
      double_complex operator/(double_complex lhs, double rhs);
      double_complex operator/(double lhs, double_complex rhs);

1 Returns double_complex(lhs) /= rhs.

  26.1.1.4.6  operator==                                [lib.op==.dc.dc]
      bool operator==(double_complex lhs, double_complex rhs);

1 Returns real(lhs) == real(rhs) && imag(lhs) == imag(rhs).
      bool operator==(double_complex lhs, double rhs);

2 Returns real(lhs) == rhs && imag(lhs) == 0.
      bool operator==(double lhs, double_complex rhs);

3 Returns lhs == real(rhs) && imag(rhs) == 0.

  26.1.1.4.7  operator!=                                [lib.op!=.dc.dc]
      bool operator!=(double_complex lhs, double_complex rhs);

1 Returns real(lhs) != real(rhs) || imag(lhs) != imag(rhs).
      bool operator!=(double_complex lhs, double rhs);

2 Returns real(lhs) != rhs || imag(lhs) != 0.
      bool operator!=(double lhs, double_complex rhs);

3 Returns lhs != real(rhs) || imag(rhs) != 0.

  26.1.1.4.8  operator>>                                    [lib.ext.dc]
      istream& operator>>(istream& is, double_complex& x);

1 Evaluates the expression:
      is >> ch && ch == '('
      && is >> re >> ch && ch == ','
      && is >> im >> ch && ch == ')';

2 where ch is an object of type char and re and im are objects  of  type
  double.    If  the  result  is  nonzero,  the  function  assigns  dou­
  ble_complex(re, im) to x.

3 The function returns is.

  26.1.1.4.9  operator<<                                    [lib.ins.dc]
      ostream& operator<<(ostream& os, double_complex x);

1 Returns os << '(' << real(x) << ',' << imag(x) << ')'.

  26.1.1.5  Class long_double_complex          [lib.long.double.complex]
      class long_double_complex {
      public:
          long_double_complex(re_arg = 0, im_arg = 0);
          long_double_complex(const float_complex& rhs);
          long_double_complex(const double_complex& rhs);
          long_double_complex& operator+=(long_double_complex rhs);
          long_double_complex& operator-=(long_double_complex rhs);
          long_double_complex& operator*=(long_double_complex rhs);
          long_double_complex& operator/=(long_double_complex rhs);
      private:
  //      long double re, im;     exposition only
      };

1 The class long_double_complex describes an object that can  store  the
  Cartesian components, of type long double, of a complex number.

2 For the sake of exposition, the maintained data is presented here as:

  --long double re, the real component;

  --long double im, the imaginary component.

  26.1.1.5.1  long_double_complex         [lib.long.double.complex.cons]
       constructors
      long_double_complex(long double re_arg = 0, im_arg = 0);

1 Constructs an object of class long_double_complex, initializing re  to
  re_arg and im to im_arg.
      long_double_complex(float_complex& rhs);

2 Constructs  an object of class long_double_complex, initializing re to
  (long double)real(rhs) and im to (long double)imag(rhs).
      long_double_complex(double_complex& rhs);

3 Constructs an object of class long_double_complex, initializing re  to
  (long double)real(rhs) and im to (long double)imag(rhs).

  26.1.1.5.2  operator+=                                  [lib.op+=.ldc]
      long_double_complex& operator+=(long_double_complex rhs);

1 Adds  the  complex value rhs to the complex value *this and stores the
  sum in *this.

2 Returns *this.

  26.1.1.5.3  operator-=                                  [lib.op-=.ldc]
      long_double_complex& operator-=(long_double_complex rhs);

1 Subtracts  the  complex  value  rhs  from  the complex value *this and
  stores the difference in *this.

2 Returns *this.

  26.1.1.5.4  operator*=                                  [lib.op*=.ldc]
      long_double_complex& operator*=(long_double_complex rhs);

1 Multiplies the complex value rhs by the complex value *this and stores
  the product in *this.

2 Returns *this.

  26.1.1.5.5  operator/=                                  [lib.op/=.ldc]
      long_double_complex& operator/=(long_double_complex rhs);

1 Divides  the complex value rhs into the complex value *this and stores
  the quotient in *this.

2 Returns *this.

  26.1.1.6  long_double_complex            [lib.long.double.complex.ops]
       operations

  26.1.1.6.1  operator+                                [lib.op+.ldc.ldc]
      long_double_complex operator+(long_double_complex lhs);

1 Returns long_double_complex(lhs).
      long_double_complex operator+(long_double_complex lhs,
                                    long_double_complex rhs);
      long_double_complex operator+(long_double_complex lhs,
                                    long double rhs);
      long_double_complex operator+(long double lhs,
                                    long_double_complex rhs);

2 Returns long_double_complex(lhs) += rhs.

  26.1.1.6.2  operator-                                [lib.op-.ldc.ldc]
      long_double_complex operator-(long_double_complex lhs);

1 Returns long_double_complex(-real(lhs),-imag(lhs)).
      long_double_complex operator-(long_double_complex lhs,
                                    long_double_complex rhs);
      long_double_complex operator-(long_double_complex lhs,
                                    long double rhs);
      long_double_complex operator-(long double lhs,
                                    long_double_complex rhs);

2 Returns long_double_complex(lhs) -= rhs.

  26.1.1.6.3  operator*                                [lib.op*.ldc.ldc]
      long_double_complex operator*(long_double_complex lhs,
                                    long_double_complex rhs);

1 Returns long_double_complex(lhs) *= rhs.
      long_double_complex operator*(long_double_complex lhs,
                                    long double rhs);

2 Returns long_double_complex(lhs) *= long_double_complex(rhs).
      long_double_complex operator*(long double lhs,
                                    long_double_complex rhs);

3 Returns long_double_complex(lhs) *= rhs.

  26.1.1.6.4  operator/                                [lib.op/.ldc.ldc]
      long_double_complex operator/(long_double_complex lhs,
                                    long_double_complex rhs);
      long_double_complex operator/(long_double_complex lhs,
                                    long double rhs);
      long_double_complex operator/(long double lhs,
                                    long_double_complex rhs);

1 Returns long_double_complex(lhs) /= rhs.
      bool operator==(long_double_complex lhs, long_double_complex rhs);

2 Returns real(lhs) == real(rhs) && imag(lhs) == imag(rhs).
      bool operator==(long_double_complex lhs, long double rhs);

3 Returns real(lhs) == rhs && imag(lhs) == 0.
      bool operator==(long double lhs, long_double_complex rhs);

4 Returns lhs == real(rhs) && imag(rhs) == 0.

  26.1.1.6.5  operator!=                              [lib.op!=.ldc.ldc]
      bool operator!=(long_double_complex lhs, long_double_complex rhs);

1 Returns real(lhs) != real(rhs) || imag(lhs) != imag(rhs).
      bool operator!=(long_double_complex lhs, long double rhs);

2 Returns real(lhs) != rhs || imag(lhs) != 0.
      bool operator!=(long double lhs, long_double_complex rhs);

3 Returns lhs != real(rhs) || imag(rhs) != 0.

  26.1.1.6.6  operator>>                                   [lib.ext.ldc]
      istream& operator>>(istream& is, long_double_complex& x);

1 Evaluates the expression:
      is >> ch && ch == '('
      && is >> re >> ch && ch == ','
      && is >> im >> ch && ch == ')';

2 where  ch  is an object of type char and re and im are objects of type
  long  double.   If  the  result  is  nonzero,  the  function   assigns

  long_double_complex(re, im) to x.

3 The function returns is.

  26.1.1.6.7  operator<<                                   [lib.ins.ldc]
      ostream& operator<<(ostream& os, long_double_complex x);

1 Returns os << '(' << real(x) << ',' << imag(x) << ')'.

  26.1.2  Complex number operations                    [lib.complex.ops]

  26.1.2.1  abs                                                [lib.abs]
      float       abs(float_complex x);
      double      abs(double_complex x);
      long double abs(long_double_complex x);

1 Returns the magnitude of x.

  26.1.2.2  arg                                                [lib.arg]
      float       arg(float_complex x);
      double      arg(double_complex x);
      long double arg(long_double_complex x);

1 Returns the phase angle of x.

  26.1.2.3  conj                                              [lib.conj]
      float_complex       conj(float_complex x);
      double_complex      conj(double_complex x);
      long_double_complex conj(long_double_complex x);

1 Returns the conjugate of x.

  26.1.2.4  cos                                                [lib.cos]
      float_complex       cos(float_complex x);
      double_complex      cos(double_complex x);
      long_double_complex cos(long_double_complex x);

1 Returns the cosine of x.

  26.1.2.5  cosh                                              [lib.cosh]
      float_complex       cosh(float_complex x);
      double_complex      cosh(double_complex x);
      long_double_complex cosh(long_double_complex x);

1 Returns the hyperbolic cosine of x.

  26.1.2.6  exp                                                [lib.exp]
      float_complex       exp(float_complex x);
      double_complex      exp(double_complex x);
      long_double_complex exp(long_double_complex x);

1 Returns the exponential of x.

  26.1.2.7  imag                                              [lib.imag]
      float       imag(float_complex x);
      double      imag(double_complex x);
      long double imag(long_double_complex x);

1 Returns the imaginary part of x.

  26.1.2.8  log                                                [lib.log]
      float_complex       log(float_complex x);
      double_complex      log(double_complex x);
      long_double_complex log(long_double_complex x);

1 Returns the logarithm of x.

  26.1.2.9  norm                                              [lib.norm]
      float       norm(float_complex x);
      double      norm(double_complex x);
      long double norm(long_double_complex x);

1 Returns the squared magnitude of x.

  26.1.2.10  polar                                     [lib.polar.ld.ld]
      float_complex polar(float rho, float theta);
      double_complex polar(double rho, double theta);
      long_double_complex polar(long double rho, long double theta);

1 Returns the complex value corresponding to a complex number whose mag­
  nitude is rho and whose phase angle is theta.

  26.1.2.11  pow                                               [lib.pow]
      float_complex       pow(float_complex x, float_complex y);
      float_complex       pow(float_complex x, float_complex y);
      float_complex       pow(float_complex x, float y);
      float_complex       pow(float_complex x, int y);
      float_complex       pow(float x, float_complex y);
      double_complex      pow(double_complex x, double_complex y);
      double_complex      pow(double_complex x, double y);
      double_complex      pow(double_complex x, int y);
      double_complex      pow(double x, double_complex y);
      long_double_complex pow(long_double_complex x, long_double_complex y);
      long_double_complex pow(long_double_complex x, long double y);
      long_double_complex pow(long_double_complex x, int y);
      long_double_complex pow(long double x, long_double_complex y);

1 Returns x raised to the power y.

  26.1.2.12  real                                             [lib.real]
      float       real(float_complex x);
      double      real(double_complex x);
      long double real(long_double_complex x);

1 Returns the real part of x.

  26.1.2.13  sin                                               [lib.sin]
      float_complex       sin(float_complex x);
      double_complex      sin(double_complex x);
      long_double_complex sin(long_double_complex x);

1 Returns the sine of x.

  26.1.2.14  sinh                                             [lib.sinh]
      float_complex       sinh(float_complex x);
      double_complex      sinh(double_complex x);
      long_double_complex sinh(long_double_complex x);

1 Returns the hyperbolic sine of x.

  26.1.2.15  sqrt                                             [lib.sqrt]
      float_complex       sqrt(float_complex x);
      double_complex      sqrt(double_complex x);
      long_double_complex sqrt(long_double_complex x);

1 Returns the square root of x.

  26.2  Numeric arrays                                    [lib.numarray]

1 Headers:

  --<valarray>

2 Table 2:

                   Table 2--Header <valarray> synopsis

  +------------------------------------------------------------------------+
  |          Type                                Name(s)                   |
  +------------------------------------------------------------------------+
  |Template classes:                                                       |
  |mask_array                  slice_array                 valarray        |
  +------------------------------------------------------------------------+
  |Template operators:                                                     |
  |operator!= (valarray) [3]   operator<< (valarray) [3]                   |
  |operator%  (valarray) [3]   operator<<=(valarray) [2]                   |
  |operator%= (valarray) [2]   operator<= (valarray) [3]                   |
  |operator&  (valarray) [3]   operator== (valarray) [3]                   |
  |operator&& (valarray) [3]   operator>  (valarray) [3]                   |
  |operator&= (valarray) [2]   operator>= (valarray) [3]                   |
  |operator*  (valarray) [3]   operator>> (valarray) [3]                   |
  |operator*= (valarray) [2]   operator>>=(valarray) [2]                   |
  |operator+  (valarray) [3]   operator^  (valarray) [3]                   |
  |operator+= (valarray) [2]   operator^= (valarray) [2]                   |
  |operator-  (valarray) [3]   operator|  (valarray) [3]                   |
  |operator-= (valarray) [2]   operator|= (valarray) [2]                   |
  |operator/  (valarray) [3]   operator|| (valarray) [3]                   |
  |operator/= (valarray) [2]                                               |
  |operator<  (valarray) [3]                                               |
  +------------------------------------------------------------------------+
  |Template functions:                                                     |
  |abs  (valarray)             cosh (valarray)             sinh (valarray) |
  |acos (valarray)             exp  (valarray)             sqrt (valarray) |
  |asin (valarray)             log  (valarray)             tan  (valarray) |
  |atan (valarray)             log10(valarray)             tanh (valarray) |
  |atan2(valarray) [3]         pow  (valarray) [3]                         |
  |cos  (valarray)             sin  (valarray)                             |
  +------------------------------------------------------------------------+
  |Classes:                    gslice                      slice           |
  +------------------------------------------------------------------------+

3 The  header  <valarray>  defines  five  template  classes   (valarray,
  slice_array,   gslice_array,   mask_array,  and  indirect_array),  two
  classes (slice and gslice), and a series of  related  function  signa­
  tures for representing and manipulating arrays of values.1)

4 The valarray array classes are defined to be free of certain forms  of
  aliasing, thus allowing operations on these classes to be optimized.

  _________________________
  1)   If   any   of  the  names  valarray,  slice_array,  gslice_array,
  mask_array, indirect_array, slice or  gslice  are  introduced  into  a
  translation  unit  by any means other than inclusion of the <valarray>
  header file, the resulting behavior is undefined.

5 These  library functions are permitted to throw an bad_alloc exception
  if there are not sufficient resources available to carry out the oper­
  ation.  Note that the exception is not mandated.

  +-------                 BEGIN BOX 1                -------+
  The  descriptions  of valarray and the associated classes which follow
  lack any discussion of possible exceptions.
  +-------                  END BOX 1                 -------+

6 The templates and classes defined in  <valarray>  have  the  following
  public interfaces:
      template <class T> class valarray;       // An array of type 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

  26.2.1  Template class valarray<T>             [lib.template.valarray]
      template<class T> class valarray {
      public:
          inline valarray();
          inline valarray(enum Uninitialized, size_t);
          valarray(const T&, size_t);
          valarray(const T*, size_t);
          valarray(const valarray&);
          valarray(const slice_array<T>&);
          valarray(const gslice_array<T>&);
          valarray(const mask_array<T>&);
          valarray(const indirect_array<T>&);
          inline ~valarray();
          valarray& operator=(const valarray&);
          valarray& operator=(const slice_array<T>&);
          valarray& operator=(const gslice_array<T>&);
          valarray& operator=(const mask_array<T>&);
          valarray& operator=(const indirect_array<T>&);
          inline size_t length() const;
          inline operator T*();
          inline operator const T*() const;
          inline const T    operator[](size_t);
          inline T&         operator[](size_t);
          const valarray    operator[](slice) const;
          slice_array<T>    operator[](slice);
          const valarray    operator[](const gslice&) const;
          gslice_array<T>   operator[](const gslice&);
          const valarray    operator[](const valarray<bool>&) const;
          mask_array<T>     operator[](const valarray<bool>&);
          const valarray    operator[](const valarray<int>&) const;
          indirect_array<T> operator[](const valarray<int>&);

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

  +-------                 BEGIN BOX 2                -------+
  The  friend  specifiers  are over-specification.  I have left them in,
  pending discussion, because they are a concise summary  of  non-member
  operators applicable to this class.
  +-------                  END BOX 2                 -------+

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

          valarray<T>& operator*= (const valarray<T>& ab);
          valarray<T>& operator/= (const valarray<T>& ab);
          valarray<T>& operator%= (const valarray<T>& ab);
          valarray<T>& operator+= (const valarray<T>& ab);
          valarray<T>& operator-= (const valarray<T>& ab);
          valarray<T>& operator^= (const valarray<T>&);
          valarray<T>& operator|= (const valarray<T>&);
          valarray<T>& operator&= (const valarray<T>&);
          valarray<T>& operator<<=(const valarray<T>&);
          valarray<T>& operator>>=(const valarray<T>&);
          friend const valarray<T> operator* (const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator/ (const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator% (const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator+ (const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator- (const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator^ (const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator| (const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator& (const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator<<(const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator>>(const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator&&(const valarray<T>&, const valarray<T>&);
          friend const valarray<T> operator||(const valarray<T>&, const valarray<T>&);
          friend const valarray<bool> operator==(const valarray<T>&, const T&);
          friend const valarray<bool> operator==(const T&, const valarray<T>&);
          friend const valarray<bool> operator==(const valarray<T>&, const valarray<T>&);
          friend const valarray<bool> operator!=(const valarray<T>&, const T&);
          friend const valarray<bool> operator!=(const T&, const valarray<T>&);
          friend const valarray<bool> operator!=(const valarray<T>&, const valarray<T>&);
          friend const valarray<bool> operator< (const T&, const valarray<T>&);
          friend const valarray<bool> operator< (const T&, const valarray<T>&);
          friend const valarray<bool> operator< (const valarray<T>&, const valarray<T>&);
          friend const valarray<bool> operator> (const valarray<T>&, const T&);
          friend const valarray<bool> operator> (const T&, const valarray<T>&);
          friend const valarray<bool> operator> (const valarray<T>&, const valarray<T>&);
          friend const valarray<bool> operator<=(const valarray<T>&, const T&);
          friend const valarray<bool> operator<=(const T&, const valarray<T>&);
          friend const valarray<bool> operator<=(const valarray<T>&, const valarray<T>&);
          friend const valarray<bool> operator>=(const valarray<T>&, const T&);
          friend const valarray<bool> operator>=(const valarray<T>&, const T&);
          friend const valarray<bool> operator>=(const T&, const valarray<T>&);
          friend const valarray<bool> operator>=(const valarray<T>&, const valarray<T>&);
          const T sum() const;
          void fill(const T&);
          const T min() const;
          const T max() const;

          friend const valarray<T> abs  (const valarray<T>&);
          friend const valarray<T> acos (const valarray<T>&);
          friend const valarray<T> asin (const valarray<T>&);
          friend const valarray<T> atan (const valarray<T>&);
          friend const valarray<T> atan2(const valarray<T>&, const valarray<T>&);
          friend const valarray<T> atan2(const valarray<T>&, const T&);
          friend const valarray<T> atan2(const T&, const valarray<T>&);
          friend const valarray<T> cos  (const valarray<T>&);
          friend const valarray<T> cosh (const valarray<T>&);
          friend const valarray<T> exp  (const valarray<T>&);
          friend const valarray<T> log  (const valarray<T>&);
          friend const valarray<T> log10(const valarray<T>&);
          friend const valarray<T> pow  (const valarray<T>&, const valarray<T>&);
          friend const valarray<T> pow  (const valarray<T>&, const T&);
          friend const valarray<T> pow  (const T&, const valarray<T>&);
          friend const valarray<T> sin  (const valarray<T>&);
          friend const valarray<T> sinh (const valarray<T>&);
          friend const valarray<T> sqrt (const valarray<T>&);
          friend const valarray<T> tan  (const valarray<T>&);
          friend const valarray<T> tanh  (const valarray<T>&);
          const valarray<T> shift(int) const;
          const valarray<T> apply(T func(T)) const;
          const valarray<T> apply(T func(const T&)) const;
          void free();
      private:
      // implementation dependent
      };

1 The template class valarray<T> is a one-dimensional smart array,  with
  elements  numbered  sequentially from zero.  It is a representation of
  the mathematical concept of an ordered set of values.  The illusion of
  higher  dimensionality  may  be produced by the familiar idiom of com­
  puted indices, together with the powerful subsetting capabilities pro­
  vided by the generalized subscript operators.2)

2 An  implementation  is  permitted  to  qualify  any  of  the functions
  declared in <valarray> as inline.

3 A specialization of valarray for a type T has well-defined behavior if
  and only if the type T satisfies the following requirements:3)

  --T  is  not  an  abstract  class (it has no pure virtual member func­
    tions);

  _________________________
  2)  The  intent  is  to specify an array template that has the minimum
  functionality necessary to address aliasing ambiguities and  the  pro­
  liferation  of  temporaries.  Thus, the valarray template is neither a
  matrix class nor a field class.  However, it is a very useful building
  block for designing such classes.
  3)  In  other words, valarray<T> should only be instantiated for value
  types.  These include built-in arithmetic types, pointers, the library
  class complex, and instantiations of valarray for value types.

  --T is not a reference type;

  --T is not cv-qualified;

  --If T is a class, it has a public default constructor;

  --If T is a class, it has a public copy constructor with the signature
    T::T(const T&)

  --If T is a class, it has a public destructor;

  --If T is a class, it has a public assignment operator whose signature
    is either
          T& T::operator=(const T&)
    or
          T& T::operator=(T)

  --If T is a class, its assignment operator, copy and default construc­
    tors,  and destructor must correspond to each other in the following
    sense: Initialization of raw storage using the default  constructor,
    followed by assignment, is semantically equivalent to initialization
    of raw storage  using  the  copy  constructor.   Destruction  of  an
    object, followed by initialization of its raw storage using the copy
    constructor, is semantically equivalent to assignment to the  origi­
    nal object.  This rule states that there must not be any subtle dif­
    ferences in the semantics of initialization versus assignment.  This
    gives  an  implementation considerable flexibility in how arrays are
    initialized.

    For example, an implementation is allowed to initialize  a  valarray
    by  allocating  storage using the new operator (which implies a call
    to the default constructor for each element) and then assigning each
    element  its  value.  Or the implementation can allocate raw storage
    and use the copy constructor to initialize  each  element.   If  the
    distinction between initialization and assignment is important for a
    class, or if it fails to satisfy any of the other conditions  listed
    above,  the  programmer  should use dynarray instead of valarray for
    that class;

  --If T is a class, it does not overload unary operator&.

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

5 For  example,  it  is legitimate to instantiate valarray<complex>, but
  operator > will not be successfully instantiated for valarray<complex>
  operands, since complex does not have any ordering operators.

  26.2.1.1  valarray constructors                    [lib.valarray.cons]
      valarray::valarray();

1 Constructs an object of class valarray<T>, 4) which  has  zero  length
  until  it  is passed into a library function as a modifiable lvalue or
  through  a  non-constant  this  pointer.   This default constructor is
  essential, since arrays of valarray are likely to prove useful.  There
  must  also  be  a way to change the size of an array after initializa­
  tion; this is supplied by the semantics of the assignment operator.
      valarray::valarray(enum Uninitialized, size_t);

2 The array created by this constructor has a length equal to the  value
  of the second argument.  The first argument is not used.  The elements
  of the array are constructed using the  default  constructor  for  the
  instantiating  type  T.   The extra argument is needed to prevent this
  constructor from being used by the compiler to silently convert  inte­
  gers to valarray objects.
      valarray::valarray(const T&, size_t);

3 The array created by this constructor has a length equal to the second
  argument.  The elements of the array are initialized with the value of
  the first argument.
      valarray::valarray(const T*, size_t);

4 The array created by this constructor has a length equal to the second
  argument n.  The values of the elements of the array  are  initialized
  with  the  first  n  values  pointed to by the first argument.  If the
  value of the second argument is greater  than  the  number  of  values
  pointed  to  by  the  first argument, the behavior is undefined.  This
  constructor is the preferred method for converting  a  C  array  to  a
  valarray object.
      valarray::valarray(const valarray&);

5 The array created by this constructor has the same length as the argu­
  ment array.  The elements are initialized with the values of the  cor­
  responding elements of the argument array.  This copy constructor cre­
  ates a distinct array rather than an alias.  Implementations in  which
  arrays share storage are permitted, but they must implement a copy-on-
  reference mechanism to ensure that arrays are conceptually distinct.
      valarray::valarray(const slice_array<T>&);
      valarray::valarray(const gslice_array<T>&);
      valarray::valarray(const mask_array<T>&);
      valarray::valarray(const indirect_array<T>&);

6 These conversion constructors convert one of the four  reference  tem­
  plates to a valarray.

  _________________________
  4) For  convenience,  such  objects  are  referred  to  as  ``arrays''
  throughout the remainder of subclause _lib.numarray_.

  26.2.1.2  valarray destructor                       [lib.valarray.des]
      valarray::~valarray();

  26.2.1.3  valarray assignment                       [lib.valarray.op=]
      valarray& valarray::operator=(const valarray&);

1 The  assignment  operator modifies the length of the *this array to be
  equal to that of the argument array.  Each element of the *this  array
  is  then  assigned the value of the corresponding element of the argu­
  ment array.  Assignment is the usual way to change the  length  of  an
  array  after  initialization.   Assignment results in a distinct array
  rather than an alias.
      valarray& valarray::operator=(const slice_array<T>&);
      valarray& valarray::operator=(const gslice_array<T>&);
      valarray& valarray::operator=(const mask_array<T>&);
      valarray& valarray::operator=(const indirect_array<T>&);

2 These operators allow the results of a generalized subscripting opera­
  tion to be assigned directly to a valarray.

  26.2.1.4  valarray length access                [lib.valarray::length]
      size_t valarray::length() const;

1 This function returns the number of elements in the this array.

  26.2.1.5  valarray pointer conversion               [lib.valarray.ptr]
      valarray::operator T*();
      valarray::operator const T*() const;

1 A  non-constant array may be converted to a pointer to the instantiat­
  ing type.  A constant array may be  converted  to  a  pointer  to  the
  instantiating type, qualified by const.

2 It is guaranteed that
      &a[0] == (T*)a
  for  any  non-constant valarray<T> a.  The pointer returned for a non-
  constant array (whether or not it points to a type qualified by const)
  is  valid  for the same duration as a reference returned by the size_t
  subscript operator.  The pointer returned  for  a  constant  array  is
  valid for the lifetime of the array.5)

  26.2.1.6  valarray element access                [lib.valarray.access]
      const T operator[](size_t) const;
      T& operator[](size_t);

1 When applied to a constant array, the subscript operator  returns  the
  value  of  the  corresponding element of the array.  When applied to a
  non-constant array, the subscript operator returns a reference to  the
  corresponding element of the array.

  _________________________
  5) This form of access is essential for reusability and cross-language
  programming.

2 Thus, the expression
      (a[i] = q, a[i]) == q
  evaluates as true for any non-constant valarray<T> a, any T q, and for
  any size_t i such that the value of i is less than the length of a.

3 The expression
      &a[i+j] == &a[i] + j
  evaluates  as true for all size_t i and size_t j such that i+j is less
  than the length of the non-constant array a.

4 Likewise, the expression
      &a[i] != &b[j]
  evaluates as true for any two non-constant arrays a and b and for  any
  size_t  i  and size_t j such that i is less than the length of a and j
  is less than the length of b.  This property indicates an  absence  of
  aliasing and may be used to advantage by optimizing compilers.6)

5 The  reference  returned  by the subscript operator for a non-constant
  array is guaranteed to be valid until  the  array  to  whose  data  it
  refers  is  passed into any library function as a modifiable lvalue or
  through a non-const this pointer.

6 Computed assigns [such as valarray& valarray::operator+=(const  valar­
  ray&)]  do  not by themselves invalidate references to array data.  If
  the subscript operator is invoked with a size_t argument  whose  value
  is not less than the length of the array, the behavior is undefined.

  26.2.1.7  valarray subset operations                [lib.valarray.sub]
      const valarray    operator[](slice) const;
      slice_array<T>    operator[](slice);
      const valarray    operator[](const gslice&) const;
      gslice_array<T>   operator[](const gslice&);
      const valarray    operator[](const valarray<bool>&) const;
      mask_array<T>     operator[](const valarray<bool>&);
      const valarray    operator[](const valarray<int>&) const;
      indirect_array<T> operator[](const valarray<int>&);

1 Each  of  these  operations  returns  a subset of the this array.  The
  const- qualified versions return this subset as a new  valarray.   The
  non-const  versions return a class template object which has reference
  semantics to the original array.

  26.2.1.8  valarray unary operators                [lib.valarray.unary]
      const valarray valarray::operator+() const;
      const valarray valarray::operator-() const;
      const valarray valarray::operator~() const;
      const valarray valarray::operator!() const;

  _________________________
  6)  Compilers  may  take  advantage of inlining, constant propagation,
  loop fusion, tracking of pointers obtained from operator new, and oth­
  er techniques to generate efficient valarrays.

1 Each of these operators may only be instantiated for a type T to which
  the  indicated  operator  can  be  applied and for which the indicated
  operator returns a value which is of type &T or which may be unambigu­
  ously converted to type T.

2 Each  of these operators returns an array whose length is equal to the
  length of the this array.  Each element of the returned array is  ini­
  tialized  with  the  result  of applying the indicated operator to the
  corresponding element of the this array.

  26.2.1.9  valarray binary operators         [lib.valarray.binary.scal]
       with scalars
      const valarray operator* (const valarray&, const T&);
      const valarray operator/ (const valarray&, const T&);
      const valarray operator% (const valarray&, const T&);
      const valarray operator+ (const valarray&, const T&);
      const valarray operator- (const valarray&, const T&);
      const valarray operator^ (const valarray&, const T&);
      const valarray operator& (const valarray&, const T&);
      const valarray operator| (const valarray&, const T&);
      const valarray operator<<(const valarray&, const T&);
      const valarray operator>>(const valarray&, const T&);
      const valarray operator&&(const valarray&, const T&);
      const valarray operator||(const valarray&, const T&);
      const valarray operator* (const T&, const valarray&);
      const valarray operator/ (const T&, const valarray&);
      const valarray operator% (const T&, const valarray&);
      const valarray operator+ (const T&, const valarray&);
      const valarray operator- (const T&, const valarray&);
      const valarray operator^ (const T&, const valarray&);
      const valarray operator& (const T&, const valarray&);
      const valarray operator| (const T&, const valarray&);
      const valarray operator<<(const T&, const valarray&);
      const valarray operator>>(const T&, const valarray&);
      const valarray operator&&(const T&, const valarray&);
      const valarray operator||(const T&, const valarray&);

1 Each of these operators may only be instantiated for a type T to which
  the indicated operator can be applied  and  for  which  the  indicated
  operator  returns a value which is of type T or which can be unambigu­
  ously converted to type T.

2 Each of these operators returns an array whose length is equal to  the
  length  of  the array argument.  Each element of the returned array is
  initialized with the result of applying the indicated operator to  the
  corresponding element of the array argument and the scalar argument.

  26.2.1.10  valarray computed assigns       [lib.valarray.cassign.scal]
       with scalars

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

1 Each of these operators may only be instantiated for a type T to which
  the indicated operator can be applied.

2 Each of these operators applies the indicated operation to  each  ele­
  ment of the this array and the scalar argument.

3 The this array is then returned by reference.

4 The appearance of an array on the left hand side of a computed assign­
  ment does not invalidate references or pointers to the elements of the
  array.

  26.2.1.11  valarray binary operations         [lib.valarray.bin.array]
       with other arrays
      const valarray operator* (const valarray&, const valarray&);
      const valarray operator/ (const valarray&, const valarray&);
      const valarray operator% (const valarray&, const valarray&);
      const valarray operator+ (const valarray&, const valarray&);
      const valarray operator- (const valarray&, const valarray&);
      const valarray operator^ (const valarray&, const valarray&);
      const valarray operator& (const valarray&, const valarray&);
      const valarray operator| (const valarray&, const valarray&);
      const valarray operator<<(const valarray&, const valarray&);
      const valarray operator>>(const valarray&, const valarray&);
      const valarray operator&&(const valarray&, const valarray&);
      const valarray operator||(const valarray&, const valarray&);

1 Each of these operators may only be instantiated for a type T to which
  the  indicated  operator  can  be  applied and for which the indicated
  operator returns a value which is of type T or which can be  unambigu­
  ously converted to type T.

2 Each  of these operators returns an array whose length is equal to the
  lengths of the argument arrays.  Each element of the returned array is
  initialized  with the result of applying the indicated operator to the
  corresponding elements of the argument arrays.

3 If the argument arrays do not have the same length,  the  behavior  is
  undefined.

  26.2.1.12  valarray computed               [lib.valarray.assign.array]
       assignments with other arrays
      valarray& valarray::operator*= (const valarray&);
      valarray& valarray::operator/= (const valarray&);
      valarray& valarray::operator%= (const valarray&);
      valarray& valarray::operator+= (const valarray&);
      valarray& valarray::operator-= (const valarray&);
      valarray& valarray::operator^= (const valarray&);
      valarray& valarray::operator&= (const valarray&);
      valarray& valarray::operator|= (const valarray&);
      valarray& valarray::operator<<=(const valarray&);
      valarray& valarray::operator>>=(const valarray&);

1 Each of these operators may only be instantiated for a type T to which
  the  indicated  operator can be applied.  Each of these operators per­
  forms the indicated operation on each of its elements and  the  corre­
  sponding element of the argument array.

2 The this array is then returned by reference.

3 If  the this array and the argument array do not have the same length,
  the behavior is undefined.  The appearance of an  array  on  the  left
  hand  side  of a computed assignment does not invalidate references or
  pointers.

  26.2.1.13  valarray comparison operators      [lib.valarray.comp.scal]
       with scalars
      const valarray<bool> operator==(const valarray&, const T&);
      const valarray<bool> operator!=(const valarray&, const T&);
      const valarray<bool> operator< (const valarray&, const T&);
      const valarray<bool> operator> (const valarray&, const T&);
      const valarray<bool> operator<=(const valarray&, const T&);
      const valarray<bool> operator>=(const valarray&, const T&);
      const valarray<bool> operator==(const T&, const valarray&);
      const valarray<bool> operator!=(const T&, const valarray&);
      const valarray<bool> operator< (const T&, const valarray&);
      const valarray<bool> operator> (const T&, const valarray&);
      const valarray<bool> operator<=(const T&, const valarray&);
      const valarray<bool> operator>=(const T&, const valarray&);

1 Each of these operators may only be instantiated for a type T to which
  the indicated operator can be applied  and  for  which  the  indicated
  operator  returns  a value which is of type bool or which can be unam­
  biguously converted to type bool.

2 Each of these operators returns a bool array whose length is equal  to
  the  length of the array argument.  Each element of the returned array
  is initialized with the result of applying the indicated  operator  to
  the corresponding element of the this array and the scalar argument.

  26.2.1.14  valarray comparison               [lib.valarray.comp.array]
       operators with other arrays
      const valarray<bool> operator==(const valarray&, const valarray&);
      const valarray<bool> operator!=(const valarray&, const valarray&);
      const valarray<bool> operator< (const valarray&, const valarray&);
      const valarray<bool> operator> (const valarray&, const valarray&);
      const valarray<bool> operator<=(const valarray&, const valarray&);
      const valarray<bool> operator>=(const valarray&, const valarray&);

1 Each of these operators may only be instantiated for a type T to which
  the indicated operator can be applied  and  for  which  the  indicated
  operator  returns  a value which is of type bool or which can be unam­
  biguously converted to type bool.

2 Each of these operators returns a bool array whose length is equal  to
  the length of the array arguments.  Each element of the returned array
  is initialized with the result of applying the indicated  operator  to
  the corresponding elements of the argument arrays.

3 If  the  two array arguments do not have the same length, the behavior
  is undefined.

  26.2.1.15  valarray sum function                    [lib.valarray.sum]
      const T valarray::sum() const;
  This function may only be instantiated for a type T  to  which  opera­
  tor+=  can  be applied.  This function returns the sum of all the ele­
  ments of the array.

1 If the array has length 0, the behavior is undefined.   If  the  array
  has  length  1,  sum  returns  the value of element 0.  Otherwise, the
  returned value is calculated by applying operator+= to a  copy  of  an
  element of the array and all other elements of the array in an unspec­
  ified order.

  26.2.1.16  valarray fill function                  [lib.valarray.fill]
      void valarray::fill(const T&);
  This function assigns the value of the argument to all the elements of
  the  this  array.  The length of the array is not changed, nor are any
  pointers or references to the elements of the array invalidated.

  26.2.1.17  valarray transcendentals           [lib.valarray.transcend]

      const valarray abs  (const valarray&);
      const valarray acos (const valarray&);
      const valarray asin (const valarray&);
      const valarray atan (const valarray&);
      const valarray atan2(const valarray&, const valarray&);
      const valarray atan2(const valarray&, const T&);
      const valarray atan2(const T&, const valarray&);
      const valarray cos  (const valarray&);
      const valarray cosh (const valarray&);
      const valarray exp  (const valarray&);
      const valarray log  (const valarray&);
      const valarray log10(const valarray&);
      const valarray pow  (const valarray&, const valarray&);
      const valarray pow  (const valarray&, const T&);
      const valarray pow  (const T&, const valarray&);
      const valarray sin  (const valarray&);
      const valarray sinh (const valarray&);
      const valarray sqrt (const valarray&);
      const valarray tan  (const valarray&);
      const valarray tanh (const valarray&);

1 Each of these functions may only be instantiated for a type T to which
  a  unique function with the indicated name can be applied.  This func­
  tion must return a value which is of type T or which can be  unambigu­
  ously converted to type T.

  26.2.1.18  valarray min and max functions        [lib.valarray.minmax]
      const T min(const valarray&);
      const T max(const valarray&);

1 These  functions may only be instantiated for a type T to which opera­
  tor> and operator< may be applied and for which operator>  and  opera­
  tor<  return  a  value which is of type bool or which can be unambigu­
  ously converted to type bool.

2 These functions return the minimum or maximum value found in the argu­
  ment array.

3 The  value  returned  for  an  array of length 0 is undefined.  For an
  array of length 1, the value of element 0 is returned.  For all  other
  array  lengths,  the  determination is made using operator> and opera­
  tor<, in a manner analogous to the application of operator+=  for  the
  sum function.

  26.2.1.19  valarray shift function                [lib.valarray.shift]
      const valarray valarray::shift(int) const;

1 This  function  returns an array whose length is identical to the this
  array, but whose element values are shifted the number of places indi­
  cated by the argument.

2 For  example,  if the argument has the value 2, the first two elements
  of the result will be constructed using the default  constructor;  the
  third  element  of  the result will be assigned the value of the first

  element of the argument; etc.

  +-------                 BEGIN BOX 3                -------+
  Should  a cshift (circular shift) function also be defined?  This is a
  common operation in Fortran.
  +-------                  END BOX 3                 -------+

  26.2.1.20  valarray mapping functions               [lib.valarray.map]
      const valarray valarray::apply(T func(T)) const;
      const valarray valarray::apply(T func(const T&)) const;

1 These functions return an array whose length  is  equal  to  the  this
  array.   Each  element  of  the  returned  array is assigned the value
  returned by applying the argument function to the  corresponding  ele­
  ment of the this array.

  26.2.1.21  valarray free function                  [lib.valarray.free]
      void valarray::free();

1 This function sets the length of an array to zero.7)

  26.2.2  Class slice                                  [lib.class.slice]
      class slice {
      public:
          slice();
          slice(int, int, int);
          int start() const;
          int length() const;
          int stride() const;
      private:
      //    implementation defined
      };

1 The slice class represents a BLAS-like slice from an  array.   Such  a
  slice is specified by a starting index, a length, and a stride.8)

  26.2.2.1  slice constructors                          [lib.cons.slice]
      slice::slice();
      slice::slice(int start, int length, int stride);
      slice::slice(const slice&);

1 The  default  constructor for slice creates a slice which specifies no
  elements.  A default constructor is provided only to permit the decla­
  ration  of  arrays  of  slices.   The constructor with arguments for a
  slice takes a start, length, and stride parameter.

2 For example,
      slice(3, 8, 2)
  _________________________
  7)  An  implementation  may reclaim the storage used by the array when
  this function is called.
  8) C++ programs may instantiate this class.

  constructs a slice which selects elements 3, 5,  7,  ...  17  from  an
  array.

  26.2.2.2  slice access functions                    [lib.slice.access]
      int slice::start() const;
      int slice::length() const;
      int slice::stride() const;

1 These  functions  return  the  start, length, or stride specified by a
  slice object.

  26.2.3  Template class slice_array          [lib.template.slice.array]
      template <class T> class slice_array {
      public:
          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;
          void fill(const T&);
      private:
          slice_array();
          slice_array(const slice_array&);
          slice_array& operator=(const slice_array&);
      //   remainder implementation defined
      };

1 The slice_array template is a helper template used by the  slice  sub­
  script operator
      slice_array<T> valarray<T>::operator[](slice);
  It  has  reference  semantics  to  a subset of an array specified by a
  slice object.

2 For example, the expression
      a[slice(1, 5, 3)] = b;
  has the effect of assigning the elements of b to a slice of  the  ele­
  ments  in  a.  For the slice shown, the elements selected from a be 1,
  4, ..., 13.

3 Note that programmers may not instantiate slice_array, since  all  its
  constructors are private.  It is intended purely as a helper class and
  should be transparent to the user.

  26.2.3.1  slice_array constructors                [lib.cons.slice.arr]
      slice_array::slice_array();
      slice_array::slice_array(const slice_array&);

1 Note  that the slice_array template has no public constructors.  These
  constructors are declared to be private.  These constructors need  not
  be defined.

  26.2.3.2  slice_array assignment                [lib.slice.arr.assign]
      void operator=(const valarray<T>&) const;
      slice_array& operator=(const slice_array&);

1 The  second  of these two assignment operators is declared private and
  need not be defined.  The first has reference semantics, assigning the
  values  of  the  argument  array  elements to selected elements of the
  valarray<T> object to which the slice_array object refers.

  26.2.3.3  slice_array computed             [lib.slice.arr.comp.assign]
       assignment
      void slice_array::operator*= (const valarray<T>&) const;
      void slice_array::operator/= (const valarray<T>&) const;
      void slice_array::operator%= (const valarray<T>&) const;
      void slice_array::operator+= (const valarray<T>&) const;
      void slice_array::operator-= (const valarray<T>&) const;
      void slice_array::operator^= (const valarray<T>&) const;
      void slice_array::operator&= (const valarray<T>&) const;
      void slice_array::operator|= (const valarray<T>&) const;
      void slice_array::operator<<=(const valarray<T>&) const;
      void slice_array::operator>>=(const valarray<T>&) const;

1 These  computed  assignments  have  reference  semantics, applying the
  indicated operation to the elements of the argument array and selected
  elements  of  the  valarray<T>  object to which the slice_array object
  refers.

  26.2.3.4  slice_array fill function               [lib.slice.arr.fill]
      void fill(const T&);

1 This function has reference semantics,  assigning  the  value  of  its
  argument  to  the  elements  of  the  valarray<T>  object to which the
  slice_array object refers.

  26.2.4  The gslice class                            [lib.class.gslice]
      class gslice {
      public:
          gslice();
          gslice(int s, const valarray<int>& l, const valarray<int>& d);
          int start() const;
          valarray<int> length() const;
          valarray<int> stride() const;
      private:
      //  implementation defined
      };

1 This class represents a generalized slice out of an array.   A  gslice
  is  defined by a starting offset (s), a set of lengths (lj), and a set
  of strides (dj).  The number of  lengths  must  equal  the  number  of
  strides.

2 A  gslice  represents  a  mapping from a set of indices (ij), equal in
  number to the number of strides, to a single index k.   It  is  useful
  for  building  multidimensional  array classes using the valarray tem­
  plate, which is one-dimensional.  The  set  of  one-dimensional  index
  values specified by a gslice are
          k = s + sum_over_j(ijdj)
  where  the multidimensional indices ij range in value from 0 to lij-1.

3 For example, the gslice specification
      start  = 3
      length = {2, 4, 3}
      stride = {19, 4, 1}
  yields the sequence of one-dimensional indices
      k = 3 + (0,1) x 19 = (0,1,2,3) x 4 + (0,1,2) x 1
  which are ordered as shown in the following table:
      (i0, i1, i2, k) =
              (0, 0, 0, 3),
              (0, 0, 1, 4),
              (0, 0, 2, 5),
              (0, 1, 0, 7),
              (0, 1, 1, 8),
              (0, 1, 2, 9),
              (0, 2, 0, 11),
              (0, 2, 1, 12),
              (0, 2, 2, 13),
              (0, 3, 0, 15),
              (0, 3, 1, 16),
              (0, 3, 2, 17),
              (1, 0, 0, 22),
              (1, 0, 1, 23),
              ...
              (1, 3, 2, 36)
  That is, the highest-ordered index turns fastest.

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

5 For  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
              (0, 0, 0, 3),
              (0, 0, 1, 4),
              (0, 0, 2, 5),
              (0, 1, 0, 4),
              (0, 1, 1, 5),
              (0, 1, 2, 6),
              ...

6 If a degenerate slice is used as the argument to the non-const version
  of operator[](const gslice&), the resulting behavior is undefined.

  26.2.4.1  gslice constructors                        [lib.gslice.cons]
      gslice::gslice();
      gslice::gslice(int start, const valarray<int>& lengths, const valarray<int>& strides);
      gslice::gslice(const gslice&);

1 The  default constructor creates a gslice which specifies no elements.
  The constructor with arguments builds a gslice based on  a  specifica­
  tion of start, lengths, and strides, as explained in the previous sec­
  tion.

  26.2.4.2  gslice access functions                  [lib.gslice.access]
      int start() const;
      valarray<int> length() const;
      valarray<int> stride() const;
  These  access  functions  return  the  representation  of  the  start,
  lengths, or strides specified for the gslice.

  26.2.5  Template class gslice_array        [lib.template.gslice.array]
      template <class T> class gslice_array {
      public:
          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;
          void fill(const T&);
      private:
          gslice_array();
          gslice_array(const gslice_array&);
          gslice_array& operator=(const gslice_array&);
      //  remainder implementation defined
      };

1 This  template is a helper template used by the slice subscript opera­
  tor
      gslice_array<T> valarray<T>::operator[](const gslice&);
  It has reference semantics to a subset of  an  array  specified  by  a
  gslice object.

2 Thus, the expression
      a[gslice(1, length, stride)] = b
  has  the  effect of assigning the elements of b to a generalized slice
  of the elements in a.

3 Note that programmers may not instantiate gslice_array, since all  its
  constructors are private.  It is intended purely as a helper class and
  should be transparent to the user.

  26.2.5.1  gslice_array constructors            [lib.gslice.array.cons]
      gslice_array::gslice_array();
      gslice_array::gslice_array(const gslice_array&);

1 The gslice_array template has no public constructors.  It declares the
  above  constructors  to  be  private.   These constructors need not be
  defined.

  26.2.5.2  gslice_array assignment            [lib.gslice.array.assign]
      void operator=(const valarray<T>&) const;
      gslice_array& operator=(const gslice_array&);

1 The second of these two assignment operators is declared  private  and
  need not be defined.  The first has reference semantics, assigning the
  values of the argument array elements  to  selected  elements  of  the
  valarray<T> object to which the gslice_array refers.

  26.2.5.3  gslice_array computed         [lib.gslice.array.comp.assign]
       assignment
      void gslice_array::operator*= (const valarray<T>&) const;
      void gslice_array::operator/= (const valarray<T>&) const;
      void gslice_array::operator%= (const valarray<T>&) const;
      void gslice_array::operator+= (const valarray<T>&) const;
      void gslice_array::operator-= (const valarray<T>&) const;
      void gslice_array::operator^= (const valarray<T>&) const;
      void gslice_array::operator&= (const valarray<T>&) const;
      void gslice_array::operator|= (const valarray<T>&) const;
      void gslice_array::operator<<=(const valarray<T>&) const;
      void gslice_array::operator>>=(const valarray<T>&) const;

1 These computed assignments  have  reference  semantics,  applying  the
  indicated operation to the elements of the argument array and selected
  elements of the valarray<T> object to which  the  gslice_array  object
  refers.

  26.2.5.4  gslice_array fill function           [lib.gslice.array.fill]
      void fill(const T&);

1 This  function  has  reference  semantics,  assigning the value of its
  argument to the elements  of  the  valarray<T>  object  to  which  the
  gslice_array object refers.

  26.2.6  Template class mask_array            [lib.template.mask.array]

      template <class T> class mask_array {
      public:
          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;
          void fill(const T&);
      private:
          mask_array();
          mask_array(const mask_array&);
          mask_array& operator=(const mask_array&);
      //  remainder implementation defined
      };

1 This template is a helper template used by the mask subscript operator
      mask_array<T> valarray<T>::operator[](const valarray<bool>&);
  It  has  reference  semantics  to  a subset of an array specified by a
  boolean mask.  Thus, the expression
      a[mask] = b;
  has the effect of assigning the elements of b to the  masked  elements
  in a (those for which the corresponding element in mask is true.

2 Note  that C++ programs may not declare instances of mask_array, since
  all its constructors are private.  It is intended purely as  a  helper
  class, and should be transparent to the user.

  26.2.6.1  mask_array constructors                [lib.mask.array.cons]
      mask_array::mask_array();
      mask_array::mask_array(const mask_array&);

1 The  mask_array  template has no public constructors.  It declares the
  above constructors to be private.   These  constructors  need  not  be
  defined.

  26.2.6.2  mask_array assignment                [lib.mask.array.assign]
      void operator=(const valarray<T>&) const;
      mask_array& operator=(const mask_array&);

1 The  second  of these two assignment operators is declared private and
  need not be defined.  The first has reference semantics, assigning the
  values  of  the  argument  array  elements to selected elements of the
  valarray<T> object to which it refers.

  26.2.6.3  mask_array computed             [lib.mask.array.comp.assign]
       assignment
      void mask_array::operator*= (const valarray<T>&) const;
      void mask_array::operator/= (const valarray<T>&) const;
      void mask_array::operator%= (const valarray<T>&) const;
      void mask_array::operator+= (const valarray<T>&) const;
      void mask_array::operator-= (const valarray<T>&) const;
      void mask_array::operator^= (const valarray<T>&) const;
      void mask_array::operator&= (const valarray<T>&) const;
      void mask_array::operator|= (const valarray<T>&) const;
      void mask_array::operator<<=(const valarray<T>&) const;
      void mask_array::operator>>=(const valarray<T>&) const;

1 These  computed  assignments  have  reference  semantics, applying the
  indicated operation to the elements of the argument array and selected
  elements of the valarray<T> object to which the mask object refers.

  26.2.6.4  mask_array fill function               [lib.mask.array.fill]
      void fill(const T&);
  This  function  has  reference  semantics,  assigning the value of its
  argument to the elements  of  the  valarray<T>  object  to  which  the
  mask_array object refers.

  26.2.7  Template class                   [lib.template.indirect.array]
       indirect_array
      template <class T> class indirect_array {
      public:
          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;
          void fill(const T&);
      private:
          indirect_array();
          indirect_array(const indirect_array&);
          indirect_array& operator=(const indirect_array&);
      //  remainder implementation defined
      };

1 This template is a helper template  used  by  the  indirect  subscript
  operator
      indirect_array<T> valarray<T>::operator[](const valarray<int>&);
  It  has  reference  semantics  to a subset of an array specified by an
  indirect_array.  Thus the expression
      a[indirect] = b;
  has the effect of assigning the elements of b to  the  elements  in  a
  whose indices appear in indirect.

2 Note that C++ programs may not declare  instances  of  indirect_array,
  since  all  its  constructors are private.  It is intended purely as a
  helper class, and should be transparent to the user.

  26.2.7.1  indirect_array constructors        [lib.indirect.array.cons]
      indirect_array::indirect_array();
      indirect_array::indirect_array(const indirect_array&);
  The indirect_array template has no public constructors.  The construc­
  tors  listed  above  are  private.   These  constructors  need  not be
  defined.

  26.2.7.2  indirect_array assignment        [lib.indirect.array.assign]
      void operator=(const valarray<T>&) const;
      indirect_array& operator=(const indirect_array&);

1 The second of these two assignment operators is declared  private  and
  need not be defined.  The first has reference semantics, assigning the
  values of the argument array elements  to  selected  elements  of  the
  valarray<T> object to which it refers.

2 If  the  indirect_array specifies an element in the valarray<T> object
  to which it refers more than once, the behavior is undefined.

3 For example,
      int addr = {2, 3, 1, 4, 4};
      valarray<int> indirect(addr, 5);
      valarray<double> a(0., 10), b(1., 5);
      array[indirect] = b;
  results in undefined behavior since element 4 is  specified  twice  in
  the indirection.

  26.2.7.3  indirect_array              [lib.indirect.array.comp.assign]
       computed assignment
      void indirect_array::operator*= (const valarray<T>&) const;
      void indirect_array::operator/= (const valarray<T>&) const;
      void indirect_array::operator%= (const valarray<T>&) const;
      void indirect_array::operator+= (const valarray<T>&) const;
      void indirect_array::operator-= (const valarray<T>&) const;
      void indirect_array::operator^= (const valarray<T>&) const;
      void indirect_array::operator&= (const valarray<T>&) const;
      void indirect_array::operator|= (const valarray<T>&) const;
      void indirect_array::operator<<=(const valarray<T>&) const;
      void indirect_array::operator>>=(const valarray<T>&) const;

1 These computed assignments  have  reference  semantics,  applying  the
  indicated operation to the elements of the argument array and selected
  elements of the valarray<T> object to which the indirect_array  object
  refers.

2 If  the  indirect_array specifies an element in the valarray<T> object
  to which it refers more than once, the behavior is undefined.

  26.2.7.4  indirect_array fill function       [lib.indirect.array.fill]
      void fill(const T&);

1 This function has reference semantics,  assigning  the  value  of  its
  argument  to the elements of the valarray<T> object to which the indi­
  rect_array object refers.

  26.3  Generalized numeric operations                 [lib.numeric.ops]

1 Headers:

  --<stl numerics (TBD)>

2 Table 3:

              Table 3--Header <stl numerics (TBD)> synopsis

              +--------------------------------------------+
              |         Type                  Name(s)      |
              +--------------------------------------------+
              |Template functions:                         |
              |accumulate [2]            inner_product [2] |
              |adjacent_difference [2]   partial_sum [2]   |
              +--------------------------------------------+

  26.3.1  Accumulate                                    [lib.accumulate]
      template <class InputIterator, class T>
      T accumulate(InputIterator first, InputIterator last, T init);

      template <class InputIterator, class T, class BinaryOperation>
      T accumulate(InputIterator first, InputIterator last, T init,
                   BinaryOperation binary_op);

1 Initializes the accumulator acc with the initial value init  and  then
  modifies  it with acc = acc + *i or acc = binary_op(acc, *i) for every
  iterator i in the range [first, last) in order.9) binary_op is assumed
  not to cause side effects.

  26.3.2  Inner product                              [lib.inner.product]

  _________________________
  9) accumulate is similar to the APL reduction operator and Common Lisp
  reduce  function,  but it avoids the difficulty of defining the result
  of reduction on an empty sequence by always requiring an initial  val­
  ue.

      template <class InputIterator1, class InputIterator2, class T>
      T inner_product(InputIterator1 first1, InputIterator1 last1,
                      InputIterator2 first2, T init);

      template <class InputIterator1, class InputIterator2, class T,
                class BinaryOperation1, class BinaryOperation2>
      T inner_product(InputIterator1 first1, InputIterator1 last1,
                      InputIterator2 first2, T init,
                      BinaryOperation1 binary_op1, BinaryOperation2 binary_op2);

1 Computes its result by initializing the accumulator acc with the  ini­
  tial value init and then modifying it with
  acc = acc + (*i1) * (*i2)
  or
  acc = binary_op1(acc, binary_op2(*i1, *i2))
  for  every  iterator  i1 in the range [first, last) and iterator i2 in
  the range [first2, first2 + (last - first))  in order.

2 binary_op1 and binary_op2 shall not cause side effects.

  26.3.3  Partial sum                                  [lib.partial.sum]
      template <class InputIterator, class OutputIterator>
      OutputIterator partial_sum(InputIterator first, InputIterator last,
                                 OutputIterator result);

      template <class InputIterator, class OutputIterator, class BinaryOperation>
      OutputIterator partial_sum(InputIterator first, InputIterator last,
                                 OutputIterator result, BinaryOperation binary_op);

1 Assigns to every iterator i in the range [result,  result  +  (last  -
  first)) a value correspondingly equal to
  ((...(*first + *(first + 1)) + ...) + *(first + (i - result)))
  or
  binary_op(binary_op(..., binary_op(*first, *(first + 1)),...), *(first + (i - result)))

2 Returns result + (last - first).

3 Complexity:  Exactly  (last - first) - 1 applications of binary_op are
  performed.

4 binary_op is expected not to have any side  effects.   result  may  be
  equal to first.

  26.3.4  Adjacent difference                  [lib.adjacent.difference]
      template <class InputIterator, class OutputIterator>
      OutputIterator adjacent_difference(InputIterator first, InputIterator last,
                                         OutputIterator result);

      template <class InputIterator, class OutputIterator, class BinaryOperation>
      OutputIterator adjacent_difference(InputIterator first, InputIterator last,
                                         OutputIterator result, BinaryOperation binary_op);

1 Assigns  to  every  element  referred  to  by  iterator i in the range
  [result + 1, result + (last - first)) a value correspondingly equal to

  *(first   +  (i  -  result))  -  *(first  +  (i  -  result)  -  1)  or
  binary_op(*(first + (i - result)), *(first  +  (i  -  result)  -  1)).
  result gets the value of *first.

2 binary_op  shall  not  have  any side effects.  result may be equal to
  first.

3 Returns result + (last - first).

4 Complexity: Exactly (last - first) - 1 applications of  binary_op  are
  performed.

  26.4  C Library                                           [lib.c.math]

1 Headers:

  --<cmath>

  --<cstdlib> abs(), div(), rand(), srand()

2 Table 4:

                     Table 4--Header <cmath> synopsis

                +-----------------------------------------+
                | Type                Name(s)             |
                +-----------------------------------------+
                |Macro:   HUGE_VAL                        |
                +-----------------------------------------+
                |Functions:                               |
                |acos     ceil       fabs    ldexp   pow  |
                |asin     cos        floor   log     sin  |
                |atan     cosh       fmod    log10   sinh |
                |atan2    exp        frexp   modf    sqrt |
                +-----------------------------------------+

3 Table 5:

                    Table 5--Header <cstdlib> synopsis

                      +----------------------------+
                      | Type          Name(s)      |
                      +----------------------------+
                      |Macros:   RAND_MAX          |
                      +----------------------------+
                      |Types:    div_t      ldiv_t |
                      +----------------------------+
                      |Functions:                  |
                      |abs       labs       srand  |
                      |div       ldiv       rand   |
                      +----------------------------+

4 The contents are the same as the Standard C library.

  SEE ALSO: ISO C subclauses 7.5, 7.10.2, 7.10.6.