From Jason Turner

[numerics]

Large diff (287.2 KB) - rendering may be slow on some devices

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpsfewi5k7/{from.md → to.md} +1771 -2318
tmp/tmpsfewi5k7/{from.md → to.md} RENAMED
@@ -5,118 +5,65 @@
5
  This Clause describes components that C++ programs may use to perform
6
  seminumerical operations.
7
 
8
  The following subclauses describe components for complex number types,
9
  random number generation, numeric ( *n*-at-a-time) arrays, generalized
10
- numeric algorithms, and mathematical functions for floating-point types,
11
- as summarized in Table  [[tab:numerics.lib.summary]].
12
 
13
- **Table: Numerics library summary** <a id="tab:numerics.lib.summary">[tab:numerics.lib.summary]</a>
14
 
15
  | Subclause | | Header |
16
- | ------------------------ | ------------------------------ | ------------ |
17
- | [[numerics.defns]] | Definitions | |
18
  | [[numeric.requirements]] | Requirements | |
19
  | [[cfenv]] | Floating-point environment | `<cfenv>` |
20
  | [[complex.numbers]] | Complex numbers | `<complex>` |
 
21
  | [[rand]] | Random number generation | `<random>` |
22
  | [[numarray]] | Numeric arrays | `<valarray>` |
23
- | [[numeric.ops]] | Generalized numeric operations | `<numeric>` |
24
- | [[c.math]] | Mathematical functions for | `<cmath>` |
25
- | | floating-point types | `<cstdlib>` |
26
 
27
 
28
- ## Definitions <a id="numerics.defns">[[numerics.defns]]</a>
29
-
30
- Define `GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, ..., aN)` as follows:
31
-
32
- - `a1` when `N` is `1`, otherwise
33
- - `op(GENERALIZED_NONCOMMUTATIVE_SUM(op, a1, ..., aK),`
34
- `\phantom{op(}GENERALIZED_NONCOMMUTATIVE_SUM(op, aM, ..., aN))` for
35
- any `K` where 1 < K+1 = M ≤ N.
36
-
37
- Define `GENERALIZED_SUM(op, a1, ..., aN)` as
38
- `GENERALIZED_NONCOMMUTATIVE_SUM(op, b1, ..., bN)`, where `b1, ..., bN`
39
- may be any permutation of `a1, ..., aN`.
40
-
41
  ## Numeric type requirements <a id="numeric.requirements">[[numeric.requirements]]</a>
42
 
43
  The `complex` and `valarray` components are parameterized by the type of
44
  information they contain and manipulate. A C++ program shall instantiate
45
- these components only with a type `T` that satisfies the following
46
- requirements:[^1]
47
-
48
- - `T` is not an abstract class (it has no pure virtual member
49
- functions);
50
- - `T` is not a reference type;
51
- - `T` is not cv-qualified;
52
- - If `T` is a class, it has a public default constructor;
53
- - If `T` is a class, it has a public copy constructor with the signature
54
- `T::T(const T&)`
55
- - If `T` is a class, it has a public destructor;
56
- - If `T` is a class, it has a public assignment operator whose signature
57
- is either `T& T::operator=(const T&)` or `T& T::operator=(T)`
58
- - If `T` is a class, its assignment operator, copy and default
59
- constructors, and destructor shall correspond to each other in the
60
- following sense:
61
- - Initialization of raw storage using the copy constructor on the
62
- value of `T()`, however obtained, is semantically equivalent to
63
- value-initialization of the same raw storage.
64
- - Initialization of raw storage using the default constructor,
65
- followed by assignment, is semantically equivalent to initialization
66
- of raw storage using the copy constructor.
67
- - Destruction of an object, followed by initialization of its raw
68
- storage using the copy constructor, is semantically equivalent to
69
- assignment to the original object.
70
-
71
- \[*Note 1*:
72
- This rule states, in part, that there shall not be any subtle
73
- differences in the semantics of initialization versus assignment. This
74
- gives an implementation considerable flexibility in how arrays are
75
- initialized.
76
- \[*Example 1*:
77
- An implementation is allowed to initialize a `valarray` by allocating
78
- storage using the `new` operator (which implies a call to the default
79
- constructor for each element) and then assigning each element its
80
- value. Or the implementation can allocate raw storage and use the copy
81
- constructor to initialize each element.
82
- — *end example*]
83
- If the distinction between initialization and assignment is important
84
- for a class, or if it fails to satisfy any of the other conditions
85
- listed above, the programmer should use `vector` ([[vector]]) instead
86
- of `valarray` for that class.
87
- — *end note*]
88
- - If `T` is a class, it does not overload unary `operator&`.
89
 
90
  If any operation on `T` throws an exception the effects are undefined.
91
 
92
  In addition, many member and related functions of `valarray<T>` can be
93
  successfully instantiated and will exhibit well-defined behavior if and
94
- only if `T` satisfies additional requirements specified for each such
95
- member or related function.
96
 
97
- [*Example 2*: It is valid to instantiate `valarray<complex>`, but
98
  `operator>()` will not be successfully instantiated for
99
  `valarray<complex>` operands, since `complex` does not have any ordering
100
  operators. — *end example*]
101
 
102
  ## The floating-point environment <a id="cfenv">[[cfenv]]</a>
103
 
104
  ### Header `<cfenv>` synopsis <a id="cfenv.syn">[[cfenv.syn]]</a>
105
 
106
  ``` cpp
107
  #define FE_ALL_EXCEPT see below
108
- #define FE_DIVBYZERO see below
109
- #define FE_INEXACT see below
110
- #define FE_INVALID see below
111
- #define FE_OVERFLOW see below
112
- #define FE_UNDERFLOW see below
113
 
114
- #define FE_DOWNWARD see below
115
- #define FE_TONEAREST see below
116
- #define FE_TOWARDZERO see below
117
- #define FE_UPWARD see below
118
 
119
  #define FE_DFL_ENV see below
120
 
121
  namespace std {
122
  // types
@@ -141,125 +88,117 @@ namespace std {
141
  ```
142
 
143
  The contents and meaning of the header `<cfenv>` are the same as the C
144
  standard library header `<fenv.h>`.
145
 
146
- [*Note 1*: This International Standard does not require an
147
- implementation to support the `FENV_ACCESS` pragma; it is
148
- *implementation-defined* ([[cpp.pragma]]) whether the pragma is
149
- supported. As a consequence, it is *implementation-defined* whether
150
- these functions can be used to test floating-point status flags, set
151
- floating-point control modes, or run under non-default mode settings. If
152
- the pragma is used to enable control over the floating-point
153
- environment, this International Standard does not specify the effect on
154
- floating-point evaluation in constant expressions. — *end note*]
155
 
156
- The floating-point environment has thread storage duration (
157
- [[basic.stc.thread]]). The initial state for a thread’s floating-point
158
  environment is the state of the floating-point environment of the thread
159
- that constructs the corresponding `thread` object (
160
- [[thread.thread.class]]) at the time it constructed the object.
 
161
 
162
  [*Note 2*: That is, the child thread gets the floating-point state of
163
  the parent thread at the time of the child’s creation. — *end note*]
164
 
165
- A separate floating-point environment shall be maintained for each
166
- thread. Each function accesses the environment corresponding to its
167
- calling thread.
168
 
169
- ISO C 7.6
170
 
171
  ## Complex numbers <a id="complex.numbers">[[complex.numbers]]</a>
172
 
173
  The header `<complex>` defines a class template, and numerous functions
174
  for representing and manipulating complex numbers.
175
 
176
  The effect of instantiating the template `complex` for any type other
177
  than `float`, `double`, or `long double` is unspecified. The
178
  specializations `complex<float>`, `complex<double>`, and
179
- `complex<long double>` are literal types ([[basic.types]]).
180
 
181
  If the result of a function is not mathematically defined or not in the
182
  range of representable values for its type, the behavior is undefined.
183
 
184
- If `z` is an lvalue expression of type cv `complex<T>` then:
185
 
186
- - the expression `reinterpret_cast<cv T(&)[2]>(z)` shall be well-formed,
187
- - `reinterpret_cast<cv T(&)[2]>(z)[0]` shall designate the real part of
188
- `z`, and
189
- - `reinterpret_cast<cv T(&)[2]>(z)[1]` shall designate the imaginary
190
- part of `z`.
191
 
192
  Moreover, if `a` is an expression of type cv `complex<T>*` and the
193
  expression `a[i]` is well-defined for an integer expression `i`, then:
194
 
195
- - `reinterpret_cast<cv T*>(a)[2*i]` shall designate the real part of
196
- `a[i]`, and
197
- - `reinterpret_cast<cv T*>(a)[2*i + 1]` shall designate the imaginary
198
- part of `a[i]`.
199
 
200
  ### Header `<complex>` synopsis <a id="complex.syn">[[complex.syn]]</a>
201
 
202
  ``` cpp
203
  namespace std {
 
204
  template<class T> class complex;
 
 
205
  template<> class complex<float>;
206
  template<> class complex<double>;
207
  template<> class complex<long double>;
208
 
209
  // [complex.ops], operators
210
- template<class T>
211
- complex<T> operator+(const complex<T>&, const complex<T>&);
212
- template<class T> complex<T> operator+(const complex<T>&, const T&);
213
- template<class T> complex<T> operator+(const T&, const complex<T>&);
214
 
215
- template<class T> complex<T> operator-(
216
- const complex<T>&, const complex<T>&);
217
- template<class T> complex<T> operator-(const complex<T>&, const T&);
218
- template<class T> complex<T> operator-(const T&, const complex<T>&);
219
 
220
- template<class T> complex<T> operator*(
221
- const complex<T>&, const complex<T>&);
222
- template<class T> complex<T> operator*(const complex<T>&, const T&);
223
- template<class T> complex<T> operator*(const T&, const complex<T>&);
224
 
225
- template<class T> complex<T> operator/(
226
- const complex<T>&, const complex<T>&);
227
- template<class T> complex<T> operator/(const complex<T>&, const T&);
228
- template<class T> complex<T> operator/(const T&, const complex<T>&);
229
 
230
- template<class T> complex<T> operator+(const complex<T>&);
231
- template<class T> complex<T> operator-(const complex<T>&);
232
 
233
- template<class T> constexpr bool operator==(
234
- const complex<T>&, const complex<T>&);
235
  template<class T> constexpr bool operator==(const complex<T>&, const T&);
236
- template<class T> constexpr bool operator==(const T&, const complex<T>&);
237
-
238
- template<class T> constexpr bool operator!=(const complex<T>&, const complex<T>&);
239
- template<class T> constexpr bool operator!=(const complex<T>&, const T&);
240
- template<class T> constexpr bool operator!=(const T&, const complex<T>&);
241
 
242
  template<class T, class charT, class traits>
243
- basic_istream<charT, traits>&
244
- operator>>(basic_istream<charT, traits>&, complex<T>&);
245
 
246
  template<class T, class charT, class traits>
247
- basic_ostream<charT, traits>&
248
- operator<<(basic_ostream<charT, traits>&, const complex<T>&);
249
 
250
  // [complex.value.ops], values
251
  template<class T> constexpr T real(const complex<T>&);
252
  template<class T> constexpr T imag(const complex<T>&);
253
 
254
  template<class T> T abs(const complex<T>&);
255
  template<class T> T arg(const complex<T>&);
256
- template<class T> T norm(const complex<T>&);
257
 
258
- template<class T> complex<T> conj(const complex<T>&);
259
  template<class T> complex<T> proj(const complex<T>&);
260
- template<class T> complex<T> polar(const T&, const T& = 0);
261
 
262
  // [complex.transcendentals], transcendentals
263
  template<class T> complex<T> acos(const complex<T>&);
264
  template<class T> complex<T> asin(const complex<T>&);
265
  template<class T> complex<T> atan(const complex<T>&);
@@ -300,148 +239,148 @@ namespace std {
300
 
301
  ### Class template `complex` <a id="complex">[[complex]]</a>
302
 
303
  ``` cpp
304
  namespace std {
305
- template<class T>
306
- class complex {
307
  public:
308
  using value_type = T;
309
 
310
  constexpr complex(const T& re = T(), const T& im = T());
311
  constexpr complex(const complex&);
312
  template<class X> constexpr complex(const complex<X>&);
313
 
314
  constexpr T real() const;
315
- void real(T);
316
  constexpr T imag() const;
317
- void imag(T);
318
 
319
- complex<T>& operator= (const T&);
320
- complex<T>& operator+=(const T&);
321
- complex<T>& operator-=(const T&);
322
- complex<T>& operator*=(const T&);
323
- complex<T>& operator/=(const T&);
324
 
325
- complex& operator=(const complex&);
326
- template<class X> complex<T>& operator= (const complex<X>&);
327
- template<class X> complex<T>& operator+=(const complex<X>&);
328
- template<class X> complex<T>& operator-=(const complex<X>&);
329
- template<class X> complex<T>& operator*=(const complex<X>&);
330
- template<class X> complex<T>& operator/=(const complex<X>&);
331
  };
332
  }
333
  ```
334
 
335
  The class `complex` describes an object that can store the Cartesian
336
  components, `real()` and `imag()`, of a complex number.
337
 
338
- ### `complex` specializations <a id="complex.special">[[complex.special]]</a>
339
 
340
  ``` cpp
341
  namespace std {
342
  template<> class complex<float> {
343
  public:
344
  using value_type = float;
345
 
346
  constexpr complex(float re = 0.0f, float im = 0.0f);
 
347
  constexpr explicit complex(const complex<double>&);
348
  constexpr explicit complex(const complex<long double>&);
349
 
350
  constexpr float real() const;
351
- void real(float);
352
  constexpr float imag() const;
353
- void imag(float);
354
 
355
- complex<float>& operator= (float);
356
- complex<float>& operator+=(float);
357
- complex<float>& operator-=(float);
358
- complex<float>& operator*=(float);
359
- complex<float>& operator/=(float);
360
 
361
- complex<float>& operator=(const complex<float>&);
362
- template<class X> complex<float>& operator= (const complex<X>&);
363
- template<class X> complex<float>& operator+=(const complex<X>&);
364
- template<class X> complex<float>& operator-=(const complex<X>&);
365
- template<class X> complex<float>& operator*=(const complex<X>&);
366
- template<class X> complex<float>& operator/=(const complex<X>&);
367
  };
368
 
369
  template<> class complex<double> {
370
  public:
371
  using value_type = double;
372
 
373
  constexpr complex(double re = 0.0, double im = 0.0);
374
  constexpr complex(const complex<float>&);
 
375
  constexpr explicit complex(const complex<long double>&);
376
 
377
  constexpr double real() const;
378
- void real(double);
379
  constexpr double imag() const;
380
- void imag(double);
381
 
382
- complex<double>& operator= (double);
383
- complex<double>& operator+=(double);
384
- complex<double>& operator-=(double);
385
- complex<double>& operator*=(double);
386
- complex<double>& operator/=(double);
387
 
388
- complex<double>& operator=(const complex<double>&);
389
- template<class X> complex<double>& operator= (const complex<X>&);
390
- template<class X> complex<double>& operator+=(const complex<X>&);
391
- template<class X> complex<double>& operator-=(const complex<X>&);
392
- template<class X> complex<double>& operator*=(const complex<X>&);
393
- template<class X> complex<double>& operator/=(const complex<X>&);
394
  };
395
 
396
  template<> class complex<long double> {
397
  public:
398
  using value_type = long double;
399
 
400
  constexpr complex(long double re = 0.0L, long double im = 0.0L);
401
  constexpr complex(const complex<float>&);
402
  constexpr complex(const complex<double>&);
 
403
 
404
  constexpr long double real() const;
405
- void real(long double);
406
  constexpr long double imag() const;
407
- void imag(long double);
408
 
409
- complex<long double>& operator=(const complex<long double>&);
410
- complex<long double>& operator= (long double);
411
- complex<long double>& operator+=(long double);
412
- complex<long double>& operator-=(long double);
413
- complex<long double>& operator*=(long double);
414
- complex<long double>& operator/=(long double);
415
 
416
- template<class X> complex<long double>& operator= (const complex<X>&);
417
- template<class X> complex<long double>& operator+=(const complex<X>&);
418
- template<class X> complex<long double>& operator-=(const complex<X>&);
419
- template<class X> complex<long double>& operator*=(const complex<X>&);
420
- template<class X> complex<long double>& operator/=(const complex<X>&);
 
421
  };
422
  }
423
  ```
424
 
425
- ### `complex` member functions <a id="complex.members">[[complex.members]]</a>
426
 
427
  ``` cpp
428
  template<class T> constexpr complex(const T& re = T(), const T& im = T());
429
  ```
430
 
431
- *Effects:* Constructs an object of class `complex`.
432
-
433
- *Postconditions:* `real() == re && imag() == im`.
434
 
435
  ``` cpp
436
  constexpr T real() const;
437
  ```
438
 
439
  *Returns:* The value of the real component.
440
 
441
  ``` cpp
442
- void real(T val);
443
  ```
444
 
445
  *Effects:* Assigns `val` to the real component.
446
 
447
  ``` cpp
@@ -449,185 +388,170 @@ constexpr T imag() const;
449
  ```
450
 
451
  *Returns:* The value of the imaginary component.
452
 
453
  ``` cpp
454
- void imag(T val);
455
  ```
456
 
457
  *Effects:* Assigns `val` to the imaginary component.
458
 
459
- ### `complex` member operators <a id="complex.member.ops">[[complex.member.ops]]</a>
460
 
461
  ``` cpp
462
- complex<T>& operator+=(const T& rhs);
463
  ```
464
 
465
  *Effects:* Adds the scalar value `rhs` to the real part of the complex
466
  value `*this` and stores the result in the real part of `*this`, leaving
467
  the imaginary part unchanged.
468
 
469
  *Returns:* `*this`.
470
 
471
  ``` cpp
472
- complex<T>& operator-=(const T& rhs);
473
  ```
474
 
475
  *Effects:* Subtracts the scalar value `rhs` from the real part of the
476
  complex value `*this` and stores the result in the real part of `*this`,
477
  leaving the imaginary part unchanged.
478
 
479
  *Returns:* `*this`.
480
 
481
  ``` cpp
482
- complex<T>& operator*=(const T& rhs);
483
  ```
484
 
485
  *Effects:* Multiplies the scalar value `rhs` by the complex value
486
  `*this` and stores the result in `*this`.
487
 
488
  *Returns:* `*this`.
489
 
490
  ``` cpp
491
- complex<T>& operator/=(const T& rhs);
492
  ```
493
 
494
  *Effects:* Divides the scalar value `rhs` into the complex value `*this`
495
  and stores the result in `*this`.
496
 
497
  *Returns:* `*this`.
498
 
499
  ``` cpp
500
- template<class X> complex<T>& operator+=(const complex<X>& rhs);
501
  ```
502
 
503
  *Effects:* Adds the complex value `rhs` to the complex value `*this` and
504
  stores the sum in `*this`.
505
 
506
  *Returns:* `*this`.
507
 
508
  ``` cpp
509
- template<class X> complex<T>& operator-=(const complex<X>& rhs);
510
  ```
511
 
512
  *Effects:* Subtracts the complex value `rhs` from the complex value
513
  `*this` and stores the difference in `*this`.
514
 
515
  *Returns:* `*this`.
516
 
517
  ``` cpp
518
- template<class X> complex<T>& operator*=(const complex<X>& rhs);
519
  ```
520
 
521
  *Effects:* Multiplies the complex value `rhs` by the complex value
522
  `*this` and stores the product in `*this`.
523
 
524
  *Returns:* `*this`.
525
 
526
  ``` cpp
527
- template<class X> complex<T>& operator/=(const complex<X>& rhs);
528
  ```
529
 
530
  *Effects:* Divides the complex value `rhs` into the complex value
531
  `*this` and stores the quotient in `*this`.
532
 
533
  *Returns:* `*this`.
534
 
535
- ### `complex` non-member operations <a id="complex.ops">[[complex.ops]]</a>
536
 
537
  ``` cpp
538
- template<class T> complex<T> operator+(const complex<T>& lhs);
539
  ```
540
 
541
  *Returns:* `complex<T>(lhs)`.
542
 
543
- *Remarks:* unary operator.
544
-
545
  ``` cpp
546
- template<class T> complex<T> operator+(const complex<T>& lhs, const complex<T>& rhs);
547
- template<class T> complex<T> operator+(const complex<T>& lhs, const T& rhs);
548
- template<class T> complex<T> operator+(const T& lhs, const complex<T>& rhs);
549
  ```
550
 
551
  *Returns:* `complex<T>(lhs) += rhs`.
552
 
553
  ``` cpp
554
- template<class T> complex<T> operator-(const complex<T>& lhs);
555
  ```
556
 
557
  *Returns:* `complex<T>(-lhs.real(),-lhs.imag())`.
558
 
559
- *Remarks:* unary operator.
560
-
561
  ``` cpp
562
- template<class T> complex<T> operator-(const complex<T>& lhs, const complex<T>& rhs);
563
- template<class T> complex<T> operator-(const complex<T>& lhs, const T& rhs);
564
- template<class T> complex<T> operator-(const T& lhs, const complex<T>& rhs);
565
  ```
566
 
567
  *Returns:* `complex<T>(lhs) -= rhs`.
568
 
569
  ``` cpp
570
- template<class T> complex<T> operator*(const complex<T>& lhs, const complex<T>& rhs);
571
- template<class T> complex<T> operator*(const complex<T>& lhs, const T& rhs);
572
- template<class T> complex<T> operator*(const T& lhs, const complex<T>& rhs);
573
  ```
574
 
575
  *Returns:* `complex<T>(lhs) *= rhs`.
576
 
577
  ``` cpp
578
- template<class T> complex<T> operator/(const complex<T>& lhs, const complex<T>& rhs);
579
- template<class T> complex<T> operator/(const complex<T>& lhs, const T& rhs);
580
- template<class T> complex<T> operator/(const T& lhs, const complex<T>& rhs);
581
  ```
582
 
583
  *Returns:* `complex<T>(lhs) /= rhs`.
584
 
585
  ``` cpp
586
  template<class T> constexpr bool operator==(const complex<T>& lhs, const complex<T>& rhs);
587
  template<class T> constexpr bool operator==(const complex<T>& lhs, const T& rhs);
588
- template<class T> constexpr bool operator==(const T& lhs, const complex<T>& rhs);
589
  ```
590
 
591
  *Returns:* `lhs.real() == rhs.real() && lhs.imag() == rhs.imag()`.
592
 
593
  *Remarks:* The imaginary part is assumed to be `T()`, or 0.0, for the
594
  `T` arguments.
595
 
596
- ``` cpp
597
- template<class T> constexpr bool operator!=(const complex<T>& lhs, const complex<T>& rhs);
598
- template<class T> constexpr bool operator!=(const complex<T>& lhs, const T& rhs);
599
- template<class T> constexpr bool operator!=(const T& lhs, const complex<T>& rhs);
600
- ```
601
-
602
- *Returns:* `rhs.real() != lhs.real() || rhs.imag() != lhs.imag()`.
603
-
604
  ``` cpp
605
  template<class T, class charT, class traits>
606
- basic_istream<charT, traits>&
607
- operator>>(basic_istream<charT, traits>& is, complex<T>& x);
608
  ```
609
 
610
- *Requires:* The input values shall be convertible to `T`.
611
 
612
  *Effects:* Extracts a complex number `x` of the form: `u`, `(u)`, or
613
  `(u,v)`, where `u` is the real part and `v` is the imaginary
614
- part ([[istream.formatted]]).
615
 
616
  If bad input is encountered, calls `is.setstate(ios_base::failbit)`
617
- (which may throw `ios::failure` ([[iostate.flags]])).
618
 
619
  *Returns:* `is`.
620
 
621
  *Remarks:* This extraction is performed as a series of simpler
622
  extractions. Therefore, the skipping of whitespace is specified to be
623
  the same for each of the simpler extractions.
624
 
625
  ``` cpp
626
  template<class T, class charT, class traits>
627
- basic_ostream<charT, traits>&
628
- operator<<(basic_ostream<charT, traits>& o, const complex<T>& x);
629
  ```
630
 
631
  *Effects:* Inserts the complex number `x` onto the stream `o` as if it
632
  were implemented as follows:
633
 
@@ -644,11 +568,11 @@ return o << s.str();
644
  character, the use of comma as a field separator can be ambiguous.
645
  Inserting `showpoint` into the output stream forces all outputs to show
646
  an explicit decimal point character; as a result, all inserted sequences
647
  of complex numbers can be extracted unambiguously. — *end note*]
648
 
649
- ### `complex` value operations <a id="complex.value.ops">[[complex.value.ops]]</a>
650
 
651
  ``` cpp
652
  template<class T> constexpr T real(const complex<T>& x);
653
  ```
654
 
@@ -671,89 +595,94 @@ template<class T> T arg(const complex<T>& x);
671
  ```
672
 
673
  *Returns:* The phase angle of `x`, or `atan2(imag(x), real(x))`.
674
 
675
  ``` cpp
676
- template<class T> T norm(const complex<T>& x);
677
  ```
678
 
679
  *Returns:* The squared magnitude of `x`.
680
 
681
  ``` cpp
682
- template<class T> complex<T> conj(const complex<T>& x);
683
  ```
684
 
685
  *Returns:* The complex conjugate of `x`.
686
 
687
  ``` cpp
688
  template<class T> complex<T> proj(const complex<T>& x);
689
  ```
690
 
691
  *Returns:* The projection of `x` onto the Riemann sphere.
692
 
693
- *Remarks:* Behaves the same as the C function `cproj`, defined in
694
- 7.3.9.4.
695
 
696
  ``` cpp
697
- template<class T> complex<T> polar(const T& rho, const T& theta = 0);
698
  ```
699
 
700
- *Requires:* `rho` shall be non-negative and non-NaN. `theta` shall be
701
- finite.
702
 
703
  *Returns:* The `complex` value corresponding to a complex number whose
704
  magnitude is `rho` and whose phase angle is `theta`.
705
 
706
- ### `complex` transcendentals <a id="complex.transcendentals">[[complex.transcendentals]]</a>
707
 
708
  ``` cpp
709
  template<class T> complex<T> acos(const complex<T>& x);
710
  ```
711
 
712
  *Returns:* The complex arc cosine of `x`.
713
 
714
- *Remarks:* Behaves the same as C function `cacos`, defined in 7.3.5.1.
 
715
 
716
  ``` cpp
717
  template<class T> complex<T> asin(const complex<T>& x);
718
  ```
719
 
720
  *Returns:* The complex arc sine of `x`.
721
 
722
- *Remarks:* Behaves the same as C function `casin`, defined in 7.3.5.2.
 
723
 
724
  ``` cpp
725
  template<class T> complex<T> atan(const complex<T>& x);
726
  ```
727
 
728
  *Returns:* The complex arc tangent of `x`.
729
 
730
- *Remarks:* Behaves the same as C function `catan`, defined in 7.3.5.3.
 
731
 
732
  ``` cpp
733
  template<class T> complex<T> acosh(const complex<T>& x);
734
  ```
735
 
736
  *Returns:* The complex arc hyperbolic cosine of `x`.
737
 
738
- *Remarks:* Behaves the same as C function `cacosh`, defined in 7.3.6.1.
 
739
 
740
  ``` cpp
741
  template<class T> complex<T> asinh(const complex<T>& x);
742
  ```
743
 
744
  *Returns:* The complex arc hyperbolic sine of `x`.
745
 
746
- *Remarks:* Behaves the same as C function `casinh`, defined in 7.3.6.2.
 
747
 
748
  ``` cpp
749
  template<class T> complex<T> atanh(const complex<T>& x);
750
  ```
751
 
752
  *Returns:* The complex arc hyperbolic tangent of `x`.
753
 
754
- *Remarks:* Behaves the same as C function `catanh`, defined in 7.3.6.3.
 
755
 
756
  ``` cpp
757
  template<class T> complex<T> cos(const complex<T>& x);
758
  ```
759
 
@@ -774,12 +703,14 @@ template<class T> complex<T> exp(const complex<T>& x);
774
  ``` cpp
775
  template<class T> complex<T> log(const complex<T>& x);
776
  ```
777
 
778
  *Returns:* The complex natural (base-e) logarithm of `x`. For all `x`,
779
- `imag(log(x))` lies in the interval \[-π, π\], and when `x` is a
780
- negative real number, `imag(log(x))` is π.
 
 
781
 
782
  *Remarks:* The branch cuts are along the negative real axis.
783
 
784
  ``` cpp
785
  template<class T> complex<T> log10(const complex<T>& x);
@@ -817,12 +748,14 @@ template<class T> complex<T> sinh(const complex<T>& x);
817
  ``` cpp
818
  template<class T> complex<T> sqrt(const complex<T>& x);
819
  ```
820
 
821
  *Returns:* The complex square root of `x`, in the range of the right
822
- half-plane. If the argument is a negative real number, the value
823
- returned lies on the positive imaginary axis.
 
 
824
 
825
  *Remarks:* The branch cuts are along the negative real axis.
826
 
827
  ``` cpp
828
  template<class T> complex<T> tan(const complex<T>& x);
@@ -844,38 +777,40 @@ The following function templates shall have additional overloads:
844
  arg norm
845
  conj proj
846
  imag real
847
  ```
848
 
 
 
849
  The additional overloads shall be sufficient to ensure:
850
 
851
- 1. If the argument has type `long double`, then it is effectively cast
852
- to `complex<long double>`.
853
- 2. Otherwise, if the argument has type `double` or an integer type,
854
- then it is effectively cast to `complex<{}double>`.
855
- 3. Otherwise, if the argument has type `float`, then it is effectively
856
  cast to `complex<float>`.
857
 
858
  Function template `pow` shall have additional overloads sufficient to
859
  ensure, for a call with at least one argument of type `complex<T>`:
860
 
861
- 1. If either argument has type `complex<long double>` or type `long
862
  double`, then both arguments are effectively cast to
863
  `complex<long double>`.
864
- 2. Otherwise, if either argument has type `complex<double>`, `double`,
865
- or an integer type, then both arguments are effectively cast to
866
  `complex<double>`.
867
- 3. Otherwise, if either argument has type `complex<float>` or `float`,
868
  then both arguments are effectively cast to `complex<float>`.
869
 
870
  ### Suffixes for complex number literals <a id="complex.literals">[[complex.literals]]</a>
871
 
872
- This section describes literal suffixes for constructing complex number
873
- literals. The suffixes `i`, `il`, and `if` create complex numbers of the
874
- types `complex<double>`, `complex<long double>`, and `complex<float>`
875
- respectively, with their imaginary part denoted by the given literal
876
- number and the real part being zero.
877
 
878
  ``` cpp
879
  constexpr complex<long double> operator""il(long double d);
880
  constexpr complex<long double> operator""il(unsigned long long d);
881
  ```
@@ -894,57 +829,482 @@ constexpr complex<float> operator""if(long double d);
894
  constexpr complex<float> operator""if(unsigned long long d);
895
  ```
896
 
897
  *Returns:* `complex<float>{0.0f, static_cast<float>(d)}`.
898
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
899
  ## Random number generation <a id="rand">[[rand]]</a>
900
 
901
  This subclause defines a facility for generating (pseudo-)random
902
  numbers.
903
 
904
  In addition to a few utilities, four categories of entities are
905
  described: *uniform random bit generators*, *random number engines*,
906
  *random number engine adaptors*, and *random number distributions*.
907
- These categorizations are applicable to types that satisfy the
908
  corresponding requirements, to objects instantiated from such types, and
909
  to templates producing such types when instantiated.
910
 
911
  [*Note 1*: These entities are specified in such a way as to permit the
912
  binding of any uniform random bit generator object `e` as the argument
913
  to any random number distribution object `d`, thus producing a
914
  zero-argument function object such as given by
915
  `bind(d,e)`. — *end note*]
916
 
917
  Each of the entities specified via this subclause has an associated
918
- arithmetic type ([[basic.fundamental]]) identified as `result_type`.
919
- With `T` as the `result_type` thus associated with such an entity, that
920
  entity is characterized:
921
 
 
 
 
 
 
922
  If integer-valued, an entity may optionally be further characterized as
923
  *signed* or *unsigned*, according to `numeric_limits<T>::is_signed`.
924
 
925
  Unless otherwise specified, all descriptions of calculations in this
926
  subclause use mathematical real numbers.
927
 
928
- Throughout this subclause, the operators , , and denote the respective
929
- conventional bitwise operations. Further:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
930
 
931
  ### Requirements <a id="rand.req">[[rand.req]]</a>
932
 
933
  #### General requirements <a id="rand.req.genl">[[rand.req.genl]]</a>
934
 
935
  Throughout this subclause [[rand]], the effect of instantiating a
936
  template:
937
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
938
  Throughout this subclause [[rand]], phrases of the form “`x` is an
939
  iterator of a specific kind” shall be interpreted as equivalent to the
940
- more formal requirement that “`x` is a value of a type satisfying the
941
  requirements of the specified iterator type”.
942
 
943
  Throughout this subclause [[rand]], any constructor that can be called
944
- with a single argument and that satisfies a requirement specified in
945
- this subclause shall be declared `explicit`.
946
 
947
  #### Seed sequence requirements <a id="rand.req.seedseq">[[rand.req.seedseq]]</a>
948
 
949
  A *seed sequence* is an object that consumes a sequence of
950
  integer-valued data and produces a requested number of unsigned integer
@@ -953,61 +1313,105 @@ values i, 0 ≤ i < 2³², based on the consumed data.
953
  [*Note 1*: Such an object provides a mechanism to avoid replication of
954
  streams of random variates. This can be useful, for example, in
955
  applications requiring large numbers of random number
956
  engines. — *end note*]
957
 
958
- A class `S` satisfies the requirements of a seed sequence if the
959
- expressions shown in Table  [[tab:SeedSequence]] are valid and have the
960
- indicated semantics, and if `S` also satisfies all other requirements of
961
- this section [[rand.req.seedseq]]. In that Table and throughout this
962
- section:
 
 
 
 
 
 
 
 
 
963
 
964
  #### Uniform random bit generator requirements <a id="rand.req.urng">[[rand.req.urng]]</a>
965
 
966
  A *uniform random bit generator* `g` of type `G` is a function object
967
  returning unsigned integer values such that each value in the range of
968
  possible results has (ideally) equal probability of being returned.
969
 
970
  [*Note 1*: The degree to which `g`’s results approximate the ideal is
971
  often determined statistically. — *end note*]
972
 
973
- A class `G` satisfies the requirements of a *uniform random bit
974
- generator* if the expressions shown in Table 
975
- [[tab:UniformRandomBitGenerator]] are valid and have the indicated
976
- semantics, and if `G` also satisfies all other requirements of this
977
- section [[rand.req.urng]]. In that Table and throughout this section:
 
 
 
 
 
978
 
979
- The following relation shall hold: `G::min() < G::max()`.
 
 
 
 
 
 
 
 
 
 
 
980
 
981
  #### Random number engine requirements <a id="rand.req.eng">[[rand.req.eng]]</a>
982
 
983
  A *random number engine* (commonly shortened to *engine*) `e` of type
984
  `E` is a uniform random bit generator that additionally meets the
985
  requirements (e.g., for seeding and for input/output) specified in this
986
- section.
987
 
988
  At any given time, `e` has a state eᵢ for some integer i ≥ 0. Upon
989
  construction, `e` has an initial state e₀. An engine’s state may be
990
  established via a constructor, a `seed` function, assignment, or a
991
  suitable `operator>>`.
992
 
993
  `E`’s specification shall define:
994
 
995
- A class `E` that satisfies the requirements of a uniform random bit
996
- generator ([[rand.req.urng]]) also satisfies the requirements of a
997
- *random number engine* if the expressions shown in Table 
998
- [[tab:RandomEngine]] are valid and have the indicated semantics, and if
999
- `E` also satisfies all other requirements of this section
1000
- [[rand.req.eng]]. In that Table and throughout this section:
1001
-
1002
- where `charT` and `traits` are constrained according to Clause 
1003
- [[strings]] and Clause  [[input.output]].
1004
-
1005
- `E` shall meet the requirements of `CopyConstructible` (Table 
1006
- [[tab:copyconstructible]]) and `CopyAssignable` (Table 
1007
- [[tab:copyassignable]]) types. These operations shall each be of
1008
- complexity no worse than 𝑂(\mbox{size of state}).
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1009
 
1010
  #### Random number engine adaptor requirements <a id="rand.req.adapt">[[rand.req.adapt]]</a>
1011
 
1012
  A *random number engine adaptor* (commonly shortened to *adaptor*) `a`
1013
  of type `A` is a random number engine that takes values produced by some
@@ -1062,11 +1466,20 @@ void seed(result_type s);
1062
  template<class Sseq> void seed(Sseq& q);
1063
  ```
1064
 
1065
  *Effects:* With `b` as the base engine, invokes `b.seed(q)`.
1066
 
1067
- `A` shall also satisfy the following additional requirements:
 
 
 
 
 
 
 
 
 
1068
 
1069
  #### Random number distribution requirements <a id="rand.req.dist">[[rand.req.dist]]</a>
1070
 
1071
  A *random number distribution* (commonly shortened to *distribution*)
1072
  `d` of type `D` is a function object returning values that are
@@ -1081,22 +1494,38 @@ distribution*. Such distribution parameters are identified in this
1081
  context by writing, for example, p(z | a,b) or P(zᵢ | a,b), to name
1082
  specific parameters, or by writing, for example, p(z |{`p`}) or
1083
  P(zᵢ |{`p`}), to denote a distribution’s parameters `p` taken as a
1084
  whole.
1085
 
1086
- A class `D` satisfies the requirements of a *random number distribution*
1087
- if the expressions shown in Table  [[tab:RandomDistribution]] are valid
1088
- and have the indicated semantics, and if `D` and its associated types
1089
- also satisfy all other requirements of this section [[rand.req.dist]].
1090
- In that Table and throughout this section,
1091
 
1092
- where `charT` and `traits` are constrained according to Clauses 
1093
- [[strings]] and [[input.output]].
 
 
 
 
 
 
 
 
 
 
 
 
 
1094
 
1095
- `D` shall satisfy the requirements of `CopyConstructible` (Table 
1096
- [[tab:copyconstructible]]) and `CopyAssignable` (Table 
1097
- [[tab:copyassignable]]) types.
 
 
 
1098
 
1099
  The sequence of numbers produced by repeated invocations of `d(g)` shall
1100
  be independent of any invocation of `os << d` or of any `const` member
1101
  function of `D` between any of the invocations `d(g)`.
1102
 
@@ -1109,14 +1538,14 @@ produce the same sequence of numbers as would repeated invocations of
1109
  It is unspecified whether `D::param_type` is declared as a (nested)
1110
  `class` or via a `typedef`. In this subclause [[rand]], declarations of
1111
  `D::param_type` are in the form of `typedef`s for convenience of
1112
  exposition only.
1113
 
1114
- `P` shall satisfy the requirements of `CopyConstructible` (Table 
1115
- [[tab:copyconstructible]]), `CopyAssignable` (Table 
1116
- [[tab:copyassignable]]), and `EqualityComparable` (Table 
1117
- [[tab:equalitycomparable]]) types.
1118
 
1119
  For each of the constructors of `D` taking arguments corresponding to
1120
  parameters of the distribution, `P` shall have a corresponding
1121
  constructor subject to the same requirements and taking arguments
1122
  identical in number, type, and default values. Moreover, for each of the
@@ -1128,178 +1557,41 @@ the identical name, type, and semantics.
1128
 
1129
  ``` cpp
1130
  using distribution_type = D;
1131
  ```
1132
 
1133
- ### Header `<random>` synopsis <a id="rand.synopsis">[[rand.synopsis]]</a>
1134
-
1135
- ``` cpp
1136
- #include <initializer_list>
1137
-
1138
- namespace std {
1139
- // [rand.eng.lcong], class template linear_congruential_engine
1140
- template<class UIntType, UIntType a, UIntType c, UIntType m>
1141
- class linear_congruential_engine;
1142
-
1143
- // [rand.eng.mers], class template mersenne_twister_engine
1144
- template<class UIntType, size_t w, size_t n, size_t m, size_t r,
1145
- UIntType a, size_t u, UIntType d, size_t s,
1146
- UIntType b, size_t t,
1147
- UIntType c, size_t l, UIntType f>
1148
- class mersenne_twister_engine;
1149
-
1150
- // [rand.eng.sub], class template subtract_with_carry_engine
1151
- template<class UIntType, size_t w, size_t s, size_t r>
1152
- class subtract_with_carry_engine;
1153
-
1154
- // [rand.adapt.disc], class template discard_block_engine
1155
- template<class Engine, size_t p, size_t r>
1156
- class discard_block_engine;
1157
-
1158
- // [rand.adapt.ibits], class template independent_bits_engine
1159
- template<class Engine, size_t w, class UIntType>
1160
- class independent_bits_engine;
1161
-
1162
- // [rand.adapt.shuf], class template shuffle_order_engine
1163
- template<class Engine, size_t k>
1164
- class shuffle_order_engine;
1165
-
1166
- // [rand.predef], engines and engine adaptors with predefined parameters
1167
- using minstd_rand0 = see below;
1168
- using minstd_rand = see below;
1169
- using mt19937 = see below;
1170
- using mt19937_64 = see below;
1171
- using ranlux24_base = see below;
1172
- using ranlux48_base = see below;
1173
- using ranlux24 = see below;
1174
- using ranlux48 = see below;
1175
- using knuth_b = see below;
1176
-
1177
- using default_random_engine = see below;
1178
-
1179
- // [rand.device], class random_device
1180
- class random_device;
1181
-
1182
- // [rand.util.seedseq], class seed_seq
1183
- class seed_seq;
1184
-
1185
- // [rand.util.canonical], function template generate_canonical
1186
- template<class RealType, size_t bits, class URBG>
1187
- RealType generate_canonical(URBG& g);
1188
-
1189
- // [rand.dist.uni.int], class template uniform_int_distribution
1190
- template<class IntType = int>
1191
- class uniform_int_distribution;
1192
-
1193
- // [rand.dist.uni.real], class template uniform_real_distribution
1194
- template<class RealType = double>
1195
- class uniform_real_distribution;
1196
-
1197
- // [rand.dist.bern.bernoulli], class bernoulli_distribution
1198
- class bernoulli_distribution;
1199
-
1200
- // [rand.dist.bern.bin], class template binomial_distribution
1201
- template<class IntType = int>
1202
- class binomial_distribution;
1203
-
1204
- // [rand.dist.bern.geo], class template geometric_distribution
1205
- template<class IntType = int>
1206
- class geometric_distribution;
1207
-
1208
- // [rand.dist.bern.negbin], class template negative_binomial_distribution
1209
- template<class IntType = int>
1210
- class negative_binomial_distribution;
1211
-
1212
- // [rand.dist.pois.poisson], class template poisson_distribution
1213
- template<class IntType = int>
1214
- class poisson_distribution;
1215
-
1216
- // [rand.dist.pois.exp], class template exponential_distribution
1217
- template<class RealType = double>
1218
- class exponential_distribution;
1219
-
1220
- // [rand.dist.pois.gamma], class template gamma_distribution
1221
- template<class RealType = double>
1222
- class gamma_distribution;
1223
-
1224
- // [rand.dist.pois.weibull], class template weibull_distribution
1225
- template<class RealType = double>
1226
- class weibull_distribution;
1227
-
1228
- // [rand.dist.pois.extreme], class template extreme_value_distribution
1229
- template<class RealType = double>
1230
- class extreme_value_distribution;
1231
-
1232
- // [rand.dist.norm.normal], class template normal_distribution
1233
- template<class RealType = double>
1234
- class normal_distribution;
1235
-
1236
- // [rand.dist.norm.lognormal], class template lognormal_distribution
1237
- template<class RealType = double>
1238
- class lognormal_distribution;
1239
-
1240
- // [rand.dist.norm.chisq], class template chi_squared_distribution
1241
- template<class RealType = double>
1242
- class chi_squared_distribution;
1243
-
1244
- // [rand.dist.norm.cauchy], class template cauchy_distribution
1245
- template<class RealType = double>
1246
- class cauchy_distribution;
1247
-
1248
- // [rand.dist.norm.f], class template fisher_f_distribution
1249
- template<class RealType = double>
1250
- class fisher_f_distribution;
1251
-
1252
- // [rand.dist.norm.t], class template student_t_distribution
1253
- template<class RealType = double>
1254
- class student_t_distribution;
1255
-
1256
- // [rand.dist.samp.discrete], class template discrete_distribution
1257
- template<class IntType = int>
1258
- class discrete_distribution;
1259
-
1260
- // [rand.dist.samp.pconst], class template piecewise_constant_distribution
1261
- template<class RealType = double>
1262
- class piecewise_constant_distribution;
1263
-
1264
- // [rand.dist.samp.plinear], class template piecewise_linear_distribution
1265
- template<class RealType = double>
1266
- class piecewise_linear_distribution;
1267
- }
1268
- ```
1269
-
1270
  ### Random number engine class templates <a id="rand.eng">[[rand.eng]]</a>
1271
 
1272
- Each type instantiated from a class template specified in this section 
1273
- [[rand.eng]] satisfies the requirements of a random number engine (
1274
- [[rand.req.eng]]) type.
1275
 
1276
  Except where specified otherwise, the complexity of each function
1277
- specified in this section  [[rand.eng]] is constant.
1278
 
1279
- Except where specified otherwise, no function described in this section 
1280
- [[rand.eng]] throws an exception.
1281
 
1282
- Every function described in this section  [[rand.eng]] that has a
1283
  function parameter `q` of type `Sseq&` for a template type parameter
1284
  named `Sseq` that is different from type `seed_seq` throws what and when
1285
  the invocation of `q.generate` throws.
1286
 
1287
- Descriptions are provided in this section  [[rand.eng]] only for engine
1288
- operations that are not described in [[rand.req.eng]] or for operations
1289
- where there is additional semantic information. In particular,
1290
- declarations for copy constructors, for copy assignment operators, for
1291
- streaming operators, and for equality and inequality operators are not
1292
- shown in the synopses.
1293
 
1294
- Each template specified in this section  [[rand.eng]] requires one or
1295
  more relationships, involving the value(s) of its non-type template
1296
  parameter(s), to hold. A program instantiating any of these templates is
1297
  ill-formed if any such required relationship fails to hold.
1298
 
1299
  For every random number engine and for every random number engine
1300
- adaptor `X` defined in this subclause ([[rand.eng]]) and in subclause 
1301
  [[rand.adapt]]:
1302
 
1303
  - if the constructor
1304
  ``` cpp
1305
  template<class Sseq> explicit X(Sseq& q);
@@ -1343,11 +1635,12 @@ template<class UIntType, UIntType a, UIntType c, UIntType m>
1343
  static constexpr result_type min() { return c == 0u ? 1u: 0u; }
1344
  static constexpr result_type max() { return m - 1u; }
1345
  static constexpr result_type default_seed = 1u;
1346
 
1347
  // constructors and seeding functions
1348
- explicit linear_congruential_engine(result_type s = default_seed);
 
1349
  template<class Sseq> explicit linear_congruential_engine(Sseq& q);
1350
  void seed(result_type s = default_seed);
1351
  template<class Sseq> void seed(Sseq& q);
1352
 
1353
  // generating functions
@@ -1355,41 +1648,38 @@ template<class UIntType, UIntType a, UIntType c, UIntType m>
1355
  void discard(unsigned long long z);
1356
  };
1357
  ```
1358
 
1359
  If the template parameter `m` is 0, the modulus m used throughout this
1360
- section  [[rand.eng.lcong]] is `numeric_limits<result_type>::max()` plus
1361
- 1.
1362
 
1363
  [*Note 1*: m need not be representable as a value of type
1364
  `result_type`. — *end note*]
1365
 
1366
  If the template parameter `m` is not 0, the following relations shall
1367
  hold: `a < m` and `c < m`.
1368
 
1369
  The textual representation consists of the value of xᵢ.
1370
 
1371
  ``` cpp
1372
- explicit linear_congruential_engine(result_type s = default_seed);
1373
  ```
1374
 
1375
- *Effects:* Constructs a `linear_congruential_engine` object. If
1376
- c mod m is 0 and `s` mod m is 0, sets the engine’s state to 1,
1377
- otherwise sets the engine’s state to `s` mod m.
1378
 
1379
  ``` cpp
1380
  template<class Sseq> explicit linear_congruential_engine(Sseq& q);
1381
  ```
1382
 
1383
- *Effects:* Constructs a `linear_congruential_engine` object. With
1384
- $k = \left\lceil \frac{\log_2 m}
1385
- {32}
1386
- \right\rceil$ and a an array (or equivalent) of length
1387
- k + 3, invokes `q.generate(`a+0`, `a+k+3`)` and then computes
1388
- $S = \left(\sum_{j=0}^{k-1}a_{j+3} \cdot 2^{32j} \right) \bmod m$. If
1389
- c mod m is 0 and S is 0, sets the engine’s state to 1, else sets the
1390
- engine’s state to S.
1391
 
1392
  #### Class template `mersenne_twister_engine` <a id="rand.eng.mers">[[rand.eng.mers]]</a>
1393
 
1394
  A `mersenne_twister_engine` random number engine[^2] produces unsigned
1395
  integer random numbers in the closed interval [0,2ʷ-1]. The state xᵢ of
@@ -1399,21 +1689,31 @@ applied to X are to be taken modulo n.
1399
 
1400
  The transition algorithm employs a twisted generalized feedback shift
1401
  register defined by shift values n and m, a twist value r, and a
1402
  conditional xor-mask a. To improve the uniformity of the result, the
1403
  bits of the raw shift register are additionally *tempered* (i.e.,
1404
- scrambled) according to a bit-scrambling matrix defined by values
1405
- u, d, s, b, t, c, and ℓ.
1406
 
1407
  The state transition is performed as follows:
1408
 
 
 
 
 
 
1409
  The sequence X is initialized with the help of an initialization
1410
  multiplier f.
1411
 
1412
  The generation algorithm determines the unsigned integer values
1413
  z₁, z₂, z₃, z₄ as follows, then delivers z₄ as its result:
1414
 
 
 
 
 
 
1415
  ``` cpp
1416
  template<class UIntType, size_t w, size_t n, size_t m, size_t r,
1417
  UIntType a, size_t u, UIntType d, size_t s,
1418
  UIntType b, size_t t,
1419
  UIntType c, size_t l, UIntType f>
@@ -1439,11 +1739,12 @@ template<class UIntType, size_t w, size_t n, size_t m, size_t r,
1439
  static constexpr result_type min() { return 0; }
1440
  static constexpr result_type max() { return 2^w - 1; }
1441
  static constexpr result_type default_seed = 5489u;
1442
 
1443
  // constructors and seeding functions
1444
- explicit mersenne_twister_engine(result_type value = default_seed);
 
1445
  template<class Sseq> explicit mersenne_twister_engine(Sseq& q);
1446
  void seed(result_type value = default_seed);
1447
  template<class Sseq> void seed(Sseq& q);
1448
 
1449
  // generating functions
@@ -1457,18 +1758,18 @@ The following relations shall hold: `0 < m`, `m <= n`, `2u < w`,
1457
  `w <= numeric_limits<UIntType>::digits`, `a <= (1u<<w) - 1u`,
1458
  `b <= (1u<<w) - 1u`, `c <= (1u<<w) - 1u`, `d <= (1u<<w) - 1u`, and
1459
  `f <= (1u<<w) - 1u`.
1460
 
1461
  The textual representation of xᵢ consists of the values of
1462
- Xᵢ₋ₙ, , Xᵢ₋₁, in that order.
1463
 
1464
  ``` cpp
1465
- explicit mersenne_twister_engine(result_type value = default_seed);
1466
  ```
1467
 
1468
- *Effects:* Constructs a `mersenne_twister_engine` object. Sets X₋ₙ to
1469
- `value` mod 2ʷ. Then, iteratively for i = 1-n,…,-1, sets Xᵢ to $$%
1470
  \bigl[f \cdot
1471
  \bigl(X_{i-1} \xor \bigl(X_{i-1} \rightshift (w-2)\bigr)
1472
  \bigr)
1473
  + i \bmod n
1474
  \bigr] \bmod 2^w
@@ -1478,14 +1779,13 @@ explicit mersenne_twister_engine(result_type value = default_seed);
1478
 
1479
  ``` cpp
1480
  template<class Sseq> explicit mersenne_twister_engine(Sseq& q);
1481
  ```
1482
 
1483
- *Effects:* Constructs a `mersenne_twister_engine` object. With
1484
- k = w / 32 ⌉ and a an array (or equivalent) of length n ⋅ k, invokes
1485
- `q.generate(`a+0`, `a+n ⋅ k`)` and then, iteratively for i = -n,…,-1,
1486
- sets Xᵢ to
1487
  $\left(\sum_{j=0}^{k-1}a_{k(i+n)+j} \cdot 2^{32j} \right) \bmod 2^w$.
1488
  Finally, if the most significant w-r bits of X₋ₙ are zero, and if each
1489
  of the other resulting Xᵢ is 0, changes X₋ₙ to 2ʷ⁻¹.
1490
 
1491
  #### Class template `subtract_with_carry_engine` <a id="rand.eng.sub">[[rand.eng.sub]]</a>
@@ -1499,10 +1799,13 @@ all subscripts applied to X are to be taken modulo r. The state xᵢ
1499
  additionally consists of an integer c (known as the *carry*) whose value
1500
  is either 0 or 1.
1501
 
1502
  The state transition is performed as follows:
1503
 
 
 
 
1504
  [*Note 1*: This algorithm corresponds to a modular linear function of
1505
  the form TA(xᵢ) = (a ⋅ xᵢ) mod b, where b is of the form mʳ - mˢ + 1
1506
  and a = b - (b - 1) / m. — *end note*]
1507
 
1508
  The generation algorithm is given by GA(xᵢ) = y, where y is the value
@@ -1522,11 +1825,12 @@ template<class UIntType, size_t w, size_t s, size_t r>
1522
  static constexpr result_type min() { return 0; }
1523
  static constexpr result_type max() { return m - 1; }
1524
  static constexpr result_type default_seed = 19780503u;
1525
 
1526
  // constructors and seeding functions
1527
- explicit subtract_with_carry_engine(result_type value = default_seed);
 
1528
  template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);
1529
  void seed(result_type value = default_seed);
1530
  template<class Sseq> void seed(Sseq& q);
1531
 
1532
  // generating functions
@@ -1540,16 +1844,15 @@ The following relations shall hold: `0u < s`, `s < r`, `0 < w`, and
1540
 
1541
  The textual representation consists of the values of Xᵢ₋ᵣ, …, Xᵢ₋₁, in
1542
  that order, followed by c.
1543
 
1544
  ``` cpp
1545
- explicit subtract_with_carry_engine(result_type value = default_seed);
1546
  ```
1547
 
1548
- *Effects:* Constructs a `subtract_with_carry_engine` object. Sets the
1549
- values of X₋ᵣ, …, X₋, in that order, as specified below. If X₋₁ is then
1550
- 0, sets c to 1; otherwise sets c to 0.
1551
 
1552
  To set the values Xₖ, first construct `e`, a
1553
  `linear_congruential_engine` object, as if by the following definition:
1554
 
1555
  ``` cpp
@@ -1565,45 +1868,44 @@ $\left( \sum_{j=0}^{n-1} z_j \cdot 2^{32j}\right) \bmod m$.
1565
 
1566
  ``` cpp
1567
  template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);
1568
  ```
1569
 
1570
- *Effects:* Constructs a `subtract_with_carry_engine` object. With
1571
- k = w / 32 and a an array (or equivalent) of length r ⋅ k, invokes
1572
- `q.generate(`a+0`, `a+r ⋅ k`)` and then, iteratively for i = -r, …, -1,
1573
- sets Xᵢ to
1574
  $\left(\sum_{j=0}^{k-1}a_{k(i+r)+j} \cdot 2^{32j} \right) \bmod m$. If
1575
  X₋₁ is then 0, sets c to 1; otherwise sets c to 0.
1576
 
1577
  ### Random number engine adaptor class templates <a id="rand.adapt">[[rand.adapt]]</a>
1578
 
1579
  #### In general <a id="rand.adapt.general">[[rand.adapt.general]]</a>
1580
 
1581
- Each type instantiated from a class template specified in this section 
1582
- [[rand.adapt]] satisfies the requirements of a random number engine
1583
- adaptor ([[rand.req.adapt]]) type.
1584
 
1585
  Except where specified otherwise, the complexity of each function
1586
- specified in this section  [[rand.adapt]] is constant.
1587
 
1588
- Except where specified otherwise, no function described in this section 
1589
- [[rand.adapt]] throws an exception.
1590
 
1591
- Every function described in this section  [[rand.adapt]] that has a
1592
  function parameter `q` of type `Sseq&` for a template type parameter
1593
  named `Sseq` that is different from type `seed_seq` throws what and when
1594
  the invocation of `q.generate` throws.
1595
 
1596
- Descriptions are provided in this section  [[rand.adapt]] only for
1597
- adaptor operations that are not described in section  [[rand.req.adapt]]
1598
- or for operations where there is additional semantic information. In
1599
- particular, declarations for copy constructors, for copy assignment
1600
- operators, for streaming operators, and for equality and inequality
1601
- operators are not shown in the synopses.
1602
 
1603
- Each template specified in this section  [[rand.adapt]] requires one or
1604
- more relationships, involving the value(s) of its non-type template
1605
  parameter(s), to hold. A program instantiating any of these templates is
1606
  ill-formed if any such required relationship fails to hold.
1607
 
1608
  #### Class template `discard_block_engine` <a id="rand.adapt.disc">[[rand.adapt.disc]]</a>
1609
 
@@ -1661,11 +1963,11 @@ template<class Engine, size_t p, size_t r>
1661
  The following relations shall hold: `0 < r` and `r <= p`.
1662
 
1663
  The textual representation consists of the textual representation of `e`
1664
  followed by the value of `n`.
1665
 
1666
- In addition to its behavior pursuant to section  [[rand.req.adapt]],
1667
  each constructor that is not a copy constructor sets `n` to 0.
1668
 
1669
  #### Class template `independent_bits_engine` <a id="rand.adapt.ibits">[[rand.adapt.ibits]]</a>
1670
 
1671
  An `independent_bits_engine` random number engine adaptor combines
@@ -1676,10 +1978,17 @@ state eᵢ of its base engine `e`; the size of the state is the size of
1676
  e’s state.
1677
 
1678
  The transition and generation algorithms are described in terms of the
1679
  following integral constants:
1680
 
 
 
 
 
 
 
 
1681
  [*Note 1*: The relation w = n₀ w₀ + (n - n₀)(w₀ + 1) always
1682
  holds. — *end note*]
1683
 
1684
  The transition algorithm is carried out by invoking `e()` as often as
1685
  needed to obtain n₀ values less than y₀ + `e.min()` and n - n₀ values
@@ -1751,10 +2060,15 @@ additional sequence V of k values also of the type delivered by `e`. The
1751
  size of the state is the size of e’s state plus k + 1.
1752
 
1753
  The transition algorithm permutes the values produced by e. The state
1754
  transition is performed as follows:
1755
 
 
 
 
 
 
1756
  The generation algorithm yields the last value of `Y` produced while
1757
  advancing `e`’s state as described above.
1758
 
1759
  ``` cpp
1760
  template<class Engine, size_t k>
@@ -1795,99 +2109,96 @@ template<class Engine, size_t k>
1795
  The following relation shall hold: `0 < k`.
1796
 
1797
  The textual representation consists of the textual representation of
1798
  `e`, followed by the `k` values of V, followed by the value of Y.
1799
 
1800
- In addition to its behavior pursuant to section  [[rand.req.adapt]],
1801
  each constructor that is not a copy constructor initializes
1802
  `V[0]`, …, `V[k-1]` and Y, in that order, with values returned by
1803
  successive invocations of `e()`.
1804
 
1805
  ### Engines and engine adaptors with predefined parameters <a id="rand.predef">[[rand.predef]]</a>
1806
 
1807
  ``` cpp
1808
  using minstd_rand0 =
1809
- linear_congruential_engine<uint_fast32_t, 16807, 0, 2147483647>;
1810
  ```
1811
 
1812
- *Required behavior:* The $10000^{\,th}$ consecutive invocation of a
1813
- default-constructed object of type `minstd_rand0` shall produce the
1814
- value 1043618065.
1815
 
1816
  ``` cpp
1817
  using minstd_rand =
1818
- linear_congruential_engine<uint_fast32_t, 48271, 0, 2147483647>;
1819
  ```
1820
 
1821
- *Required behavior:* The $10000^{\,th}$ consecutive invocation of a
1822
- default-constructed object of type `minstd_rand` shall produce the value
1823
  399268537.
1824
 
1825
  ``` cpp
1826
  using mt19937 =
1827
- mersenne_twister_engine<uint_fast32_t,
1828
- 32,624,397,31,0x9908b0df,11,0xffffffff,7,0x9d2c5680,15,0xefc60000,18,1812433253>;
1829
  ```
1830
 
1831
- *Required behavior:* The $10000^{\,th}$ consecutive invocation of a
1832
- default-constructed object of type `mt19937` shall produce the value
1833
  4123659995.
1834
 
1835
  ``` cpp
1836
  using mt19937_64 =
1837
- mersenne_twister_engine<uint_fast64_t,
1838
- 64,312,156,31,0xb5026f5aa96619e9,29,
1839
- 0x5555555555555555,17,
1840
- 0x71d67fffeda60000,37,
1841
- 0xfff7eee000000000,43,
1842
- 6364136223846793005>;
1843
  ```
1844
 
1845
- *Required behavior:* The $10000^{\,th}$ consecutive invocation of a
1846
- default-constructed object of type `mt19937_64` shall produce the value
1847
  9981545732273789042.
1848
 
1849
  ``` cpp
1850
  using ranlux24_base =
1851
  subtract_with_carry_engine<uint_fast32_t, 24, 10, 24>;
1852
  ```
1853
 
1854
- *Required behavior:* The $10000^{\,th}$ consecutive invocation of a
1855
- default-constructed object of type `ranlux24_base` shall produce the
1856
- value 7937952.
1857
 
1858
  ``` cpp
1859
  using ranlux48_base =
1860
  subtract_with_carry_engine<uint_fast64_t, 48, 5, 12>;
1861
  ```
1862
 
1863
- *Required behavior:* The $10000^{\,th}$ consecutive invocation of a
1864
- default-constructed object of type `ranlux48_base` shall produce the
1865
- value 61839128582725.
1866
 
1867
  ``` cpp
1868
  using ranlux24 = discard_block_engine<ranlux24_base, 223, 23>;
1869
  ```
1870
 
1871
- *Required behavior:* The $10000^{\,th}$ consecutive invocation of a
1872
- default-constructed object of type `ranlux24` shall produce the value
1873
  9901578.
1874
 
1875
  ``` cpp
1876
  using ranlux48 = discard_block_engine<ranlux48_base, 389, 11>;
1877
  ```
1878
 
1879
- *Required behavior:* The $10000^{\,th}$ consecutive invocation of a
1880
- default-constructed object of type `ranlux48` shall produce the value
1881
  249142670248501.
1882
 
1883
  ``` cpp
1884
  using knuth_b = shuffle_order_engine<minstd_rand0,256>;
1885
  ```
1886
 
1887
- *Required behavior:* The $10000^{\,th}$ consecutive invocation of a
1888
- default-constructed object of type `knuth_b` shall produce the value
1889
  1112339016.
1890
 
1891
  ``` cpp
1892
  using default_random_engine = implementation-defined;
1893
  ```
@@ -1920,11 +2231,12 @@ public:
1920
  // generator characteristics
1921
  static constexpr result_type min() { return numeric_limits<result_type>::min(); }
1922
  static constexpr result_type max() { return numeric_limits<result_type>::max(); }
1923
 
1924
  // constructors
1925
- explicit random_device(const string& token = implementation-defined);
 
1926
 
1927
  // generating functions
1928
  result_type operator()();
1929
 
1930
  // property functions
@@ -1935,16 +2247,15 @@ public:
1935
  void operator=(const random_device&) = delete;
1936
  };
1937
  ```
1938
 
1939
  ``` cpp
1940
- explicit random_device(const string& token = implementation-defined);
1941
  ```
1942
 
1943
- *Effects:* Constructs a `random_device` nondeterministic uniform random
1944
- bit generator object. The semantics and default value of the `token`
1945
- parameter are *implementation-defined*. [^3]
1946
 
1947
  *Throws:* A value of an *implementation-defined* type derived from
1948
  `exception` if the `random_device` could not be initialized.
1949
 
1950
  ``` cpp
@@ -1958,11 +2269,11 @@ returned by `operator()`, in the range `min()` to log₂( `max()`+1).
1958
  ``` cpp
1959
  result_type operator()();
1960
  ```
1961
 
1962
  *Returns:* A nondeterministic random value, uniformly distributed
1963
- between `min()` and `max()`, inclusive. It is *implementation-defined*
1964
  how these values are generated.
1965
 
1966
  *Throws:* A value of an *implementation-defined* type derived from
1967
  `exception` if a random number could not be obtained.
1968
 
@@ -2003,35 +2314,35 @@ private:
2003
 
2004
  ``` cpp
2005
  seed_seq();
2006
  ```
2007
 
2008
- *Effects:* Constructs a `seed_seq` object as if by default-constructing
2009
- its member `v`.
2010
 
2011
  *Throws:* Nothing.
2012
 
2013
  ``` cpp
2014
  template<class T>
2015
  seed_seq(initializer_list<T> il);
2016
  ```
2017
 
2018
- *Requires:* `T` shall be an integer type.
2019
 
2020
  *Effects:* Same as `seed_seq(il.begin(), il.end())`.
2021
 
2022
  ``` cpp
2023
  template<class InputIterator>
2024
  seed_seq(InputIterator begin, InputIterator end);
2025
  ```
2026
 
2027
- *Requires:* `InputIterator` shall satisfy the requirements of an input
2028
- iterator (Table  [[tab:iterator.input.requirements]]) type. Moreover,
2029
- `iterator_traits<InputIterator>::value_type` shall denote an integer
2030
  type.
2031
 
2032
- *Effects:* Constructs a `seed_seq` object by the following algorithm:
 
 
 
2033
 
2034
  ``` cpp
2035
  for (InputIterator s = begin; s != end; ++s)
2036
  v.push_back((*s) mod 2³²);
2037
  ```
@@ -2039,21 +2350,63 @@ for( InputIterator s = begin; s != end; ++s)
2039
  ``` cpp
2040
  template<class RandomAccessIterator>
2041
  void generate(RandomAccessIterator begin, RandomAccessIterator end);
2042
  ```
2043
 
2044
- *Requires:* `RandomAccessIterator` shall meet the requirements of a
2045
- mutable random access iterator ([[random.access.iterators]]). Moreover,
2046
- `iterator_traits<RandomAccessIterator>::value_type` shall denote an
2047
  unsigned integer type capable of accommodating 32-bit quantities.
2048
 
 
 
 
 
2049
  *Effects:* Does nothing if `begin == end`. Otherwise, with
2050
  s = `v.size()` and n = `end` - `begin`, fills the supplied range
2051
  [`begin`,`end`) according to the following algorithm in which each
2052
  operation is to be carried out modulo 2³², each indexing operator
2053
  applied to `begin` is to be taken modulo n, and T(x) is defined as
2054
- $x \, \xor \, (x \, \rightshift \, 27)$:
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2055
 
2056
  *Throws:* What and when `RandomAccessIterator` operations of `begin` and
2057
  `end` throw.
2058
 
2059
  ``` cpp
@@ -2068,13 +2421,15 @@ to `param()`.
2068
  ``` cpp
2069
  template<class OutputIterator>
2070
  void param(OutputIterator dest) const;
2071
  ```
2072
 
2073
- *Requires:* `OutputIterator` shall satisfy the requirements of an output
2074
- iterator ([[output.iterators]]). Moreover, the expression `*dest = rt`
2075
- shall be valid for a value `rt` of type `result_type`.
 
 
2076
 
2077
  *Effects:* Copies the sequence of prepared 32-bit units to the given
2078
  destination, as if by executing the following statement:
2079
 
2080
  ``` cpp
@@ -2083,22 +2438,10 @@ copy(v.begin(), v.end(), dest);
2083
 
2084
  *Throws:* What and when `OutputIterator` operations of `dest` throw.
2085
 
2086
  #### Function template `generate_canonical` <a id="rand.util.canonical">[[rand.util.canonical]]</a>
2087
 
2088
- Each function instantiated from the template described in this section 
2089
- [[rand.util.canonical]] maps the result of one or more invocations of a
2090
- supplied uniform random bit generator `g` to one member of the specified
2091
- `RealType` such that, if the values gᵢ produced by `g` are uniformly
2092
- distributed, the instantiation’s results tⱼ, 0 ≤ tⱼ < 1, are distributed
2093
- as uniformly as possible as specified below.
2094
-
2095
- [*Note 1*: Obtaining a value in this way can be a useful step in the
2096
- process of transforming a value generated by a uniform random bit
2097
- generator into a value that can be delivered by a random number
2098
- distribution. — *end note*]
2099
-
2100
  ``` cpp
2101
  template<class RealType, size_t bits, class URBG>
2102
  RealType generate_canonical(URBG& g);
2103
  ```
2104
 
@@ -2111,54 +2454,62 @@ respectively. Calculates a quantity
2111
  $$S = \sum_{i=0}^{k-1} (g_i - \texttt{g.min()})
2112
  \cdot R^i$$ using arithmetic of type `RealType`.
2113
 
2114
  *Returns:* S / Rᵏ.
2115
 
 
 
2116
  *Throws:* What and when `g` throws.
2117
 
 
 
 
 
 
 
 
2118
  ### Random number distribution class templates <a id="rand.dist">[[rand.dist]]</a>
2119
 
2120
  #### In general <a id="rand.dist.general">[[rand.dist.general]]</a>
2121
 
2122
- Each type instantiated from a class template specified in this section 
2123
- [[rand.dist]] satisfies the requirements of a random number
2124
- distribution ([[rand.req.dist]]) type.
2125
 
2126
- Descriptions are provided in this section  [[rand.dist]] only for
2127
  distribution operations that are not described in [[rand.req.dist]] or
2128
  for operations where there is additional semantic information. In
2129
  particular, declarations for copy constructors, for copy assignment
2130
  operators, for streaming operators, and for equality and inequality
2131
  operators are not shown in the synopses.
2132
 
2133
  The algorithms for producing each of the specified distributions are
2134
  *implementation-defined*.
2135
 
2136
  The value of each probability density function p(z) and of each discrete
2137
- probability function P(zᵢ) specified in this section is 0 everywhere
2138
  outside its stated domain.
2139
 
2140
  #### Uniform distributions <a id="rand.dist.uni">[[rand.dist.uni]]</a>
2141
 
2142
  ##### Class template `uniform_int_distribution` <a id="rand.dist.uni.int">[[rand.dist.uni.int]]</a>
2143
 
2144
  A `uniform_int_distribution` random number distribution produces random
2145
  integers i, a ≤ i ≤ b, distributed according to the constant discrete
2146
- probability function $$%
2147
- P(i\,|\,a,b) = 1 / (b - a + 1)
2148
- \; \mbox{.}$$
2149
 
2150
  ``` cpp
2151
  template<class IntType = int>
2152
  class uniform_int_distribution {
2153
  public:
2154
  // types
2155
  using result_type = IntType;
2156
  using param_type = unspecified;
2157
 
2158
  // constructors and reset functions
2159
- explicit uniform_int_distribution(IntType a = 0, IntType b = numeric_limits<IntType>::max());
 
2160
  explicit uniform_int_distribution(const param_type& parm);
2161
  void reset();
2162
 
2163
  // generating functions
2164
  template<class URBG>
@@ -2175,17 +2526,17 @@ template<class IntType = int>
2175
  result_type max() const;
2176
  };
2177
  ```
2178
 
2179
  ``` cpp
2180
- explicit uniform_int_distribution(IntType a = 0, IntType b = numeric_limits<IntType>::max());
2181
  ```
2182
 
2183
- *Requires:* `a` ≤ `b`.
2184
 
2185
- *Effects:* Constructs a `uniform_int_distribution` object; `a` and `b`
2186
- correspond to the respective parameters of the distribution.
2187
 
2188
  ``` cpp
2189
  result_type a() const;
2190
  ```
2191
 
@@ -2201,13 +2552,11 @@ constructed.
2201
 
2202
  ##### Class template `uniform_real_distribution` <a id="rand.dist.uni.real">[[rand.dist.uni.real]]</a>
2203
 
2204
  A `uniform_real_distribution` random number distribution produces random
2205
  numbers x, a ≤ x < b, distributed according to the constant probability
2206
- density function $$%
2207
- p(x\,|\,a,b) = 1 / (b - a)
2208
- \; \mbox{.}$$
2209
 
2210
  [*Note 1*: This implies that p(x | a,b) is undefined when
2211
  `a == b`. — *end note*]
2212
 
2213
  ``` cpp
@@ -2217,11 +2566,12 @@ template<class RealType = double>
2217
  // types
2218
  using result_type = RealType;
2219
  using param_type = unspecified;
2220
 
2221
  // constructors and reset functions
2222
- explicit uniform_real_distribution(RealType a = 0.0, RealType b = 1.0);
 
2223
  explicit uniform_real_distribution(const param_type& parm);
2224
  void reset();
2225
 
2226
  // generating functions
2227
  template<class URBG>
@@ -2238,17 +2588,18 @@ template<class RealType = double>
2238
  result_type max() const;
2239
  };
2240
  ```
2241
 
2242
  ``` cpp
2243
- explicit uniform_real_distribution(RealType a = 0.0, RealType b = 1.0);
2244
  ```
2245
 
2246
- *Requires:* `a` ≤ `b` and `b` - `a` ≤ `numeric_limits<RealType>::max()`.
 
2247
 
2248
- *Effects:* Constructs a `uniform_real_distribution` object; `a` and `b`
2249
- correspond to the respective parameters of the distribution.
2250
 
2251
  ``` cpp
2252
  result_type a() const;
2253
  ```
2254
 
@@ -2265,27 +2616,26 @@ constructed.
2265
  #### Bernoulli distributions <a id="rand.dist.bern">[[rand.dist.bern]]</a>
2266
 
2267
  ##### Class `bernoulli_distribution` <a id="rand.dist.bern.bernoulli">[[rand.dist.bern.bernoulli]]</a>
2268
 
2269
  A `bernoulli_distribution` random number distribution produces `bool`
2270
- values b distributed according to the discrete probability function $$%
2271
- P(b\,|\,p)
2272
- = \left\{ \begin{array}{lcl}
2273
- p & \mbox{if} & b = \tcode{true} \\
2274
- 1-p & \mbox{if} & b = \tcode{false}
2275
- \end{array}\right.
2276
- \; \mbox{.}$$
2277
 
2278
  ``` cpp
2279
  class bernoulli_distribution {
2280
  public:
2281
  // types
2282
  using result_type = bool;
2283
  using param_type = unspecified;
2284
 
2285
  // constructors and reset functions
2286
- explicit bernoulli_distribution(double p = 0.5);
 
2287
  explicit bernoulli_distribution(const param_type& parm);
2288
  void reset();
2289
 
2290
  // generating functions
2291
  template<class URBG>
@@ -2301,17 +2651,16 @@ public:
2301
  result_type max() const;
2302
  };
2303
  ```
2304
 
2305
  ``` cpp
2306
- explicit bernoulli_distribution(double p = 0.5);
2307
  ```
2308
 
2309
- *Requires:* 0 ≤ `p` ≤ 1.
2310
 
2311
- *Effects:* Constructs a `bernoulli_distribution` object; `p` corresponds
2312
- to the parameter of the distribution.
2313
 
2314
  ``` cpp
2315
  double p() const;
2316
  ```
2317
 
@@ -2320,25 +2669,23 @@ constructed.
2320
 
2321
  ##### Class template `binomial_distribution` <a id="rand.dist.bern.bin">[[rand.dist.bern.bin]]</a>
2322
 
2323
  A `binomial_distribution` random number distribution produces integer
2324
  values i ≥ 0 distributed according to the discrete probability function
2325
- $$%
2326
- P(i\,|\,t,p)
2327
- = \binom{t}{i} \cdot p^i \cdot (1-p)^{t-i}
2328
- \; \mbox{.}$$
2329
 
2330
  ``` cpp
2331
  template<class IntType = int>
2332
  class binomial_distribution {
2333
  public:
2334
  // types
2335
  using result_type = IntType;
2336
  using param_type = unspecified;
2337
 
2338
  // constructors and reset functions
2339
- explicit binomial_distribution(IntType t = 1, double p = 0.5);
 
2340
  explicit binomial_distribution(const param_type& parm);
2341
  void reset();
2342
 
2343
  // generating functions
2344
  template<class URBG>
@@ -2355,17 +2702,17 @@ template<class IntType = int>
2355
  result_type max() const;
2356
  };
2357
  ```
2358
 
2359
  ``` cpp
2360
- explicit binomial_distribution(IntType t = 1, double p = 0.5);
2361
  ```
2362
 
2363
- *Requires:* 0 ≤ `p` ≤ 1 and 0 ≤ `t`.
2364
 
2365
- *Effects:* Constructs a `binomial_distribution` object; `t` and `p`
2366
- correspond to the respective parameters of the distribution.
2367
 
2368
  ``` cpp
2369
  IntType t() const;
2370
  ```
2371
 
@@ -2381,25 +2728,23 @@ constructed.
2381
 
2382
  ##### Class template `geometric_distribution` <a id="rand.dist.bern.geo">[[rand.dist.bern.geo]]</a>
2383
 
2384
  A `geometric_distribution` random number distribution produces integer
2385
  values i ≥ 0 distributed according to the discrete probability function
2386
- $$%
2387
- P(i\,|\,p)
2388
- = p \cdot (1-p)^{i}
2389
- \; \mbox{.}$$
2390
 
2391
  ``` cpp
2392
  template<class IntType = int>
2393
  class geometric_distribution {
2394
  public:
2395
  // types
2396
  using result_type = IntType;
2397
  using param_type = unspecified;
2398
 
2399
  // constructors and reset functions
2400
- explicit geometric_distribution(double p = 0.5);
 
2401
  explicit geometric_distribution(const param_type& parm);
2402
  void reset();
2403
 
2404
  // generating functions
2405
  template<class URBG>
@@ -2415,17 +2760,16 @@ template<class IntType = int>
2415
  result_type max() const;
2416
  };
2417
  ```
2418
 
2419
  ``` cpp
2420
- explicit geometric_distribution(double p = 0.5);
2421
  ```
2422
 
2423
- *Requires:* 0 < `p` < 1.
2424
 
2425
- *Effects:* Constructs a `geometric_distribution` object; `p` corresponds
2426
- to the parameter of the distribution.
2427
 
2428
  ``` cpp
2429
  double p() const;
2430
  ```
2431
 
@@ -2434,14 +2778,12 @@ constructed.
2434
 
2435
  ##### Class template `negative_binomial_distribution` <a id="rand.dist.bern.negbin">[[rand.dist.bern.negbin]]</a>
2436
 
2437
  A `negative_binomial_distribution` random number distribution produces
2438
  random integers i ≥ 0 distributed according to the discrete probability
2439
- function $$%
2440
- P(i\,|\,k,p)
2441
- = \binom{k+i-1}{i} \cdot p^k \cdot (1-p)^i
2442
- \; \mbox{.}$$
2443
 
2444
  [*Note 1*: This implies that P(i | k,p) is undefined when
2445
  `p == 1`. — *end note*]
2446
 
2447
  ``` cpp
@@ -2451,11 +2793,12 @@ template<class IntType = int>
2451
  // types
2452
  using result_type = IntType;
2453
  using param_type = unspecified;
2454
 
2455
  // constructor and reset functions
2456
- explicit negative_binomial_distribution(IntType k = 1, double p = 0.5);
 
2457
  explicit negative_binomial_distribution(const param_type& parm);
2458
  void reset();
2459
 
2460
  // generating functions
2461
  template<class URBG>
@@ -2472,17 +2815,17 @@ template<class IntType = int>
2472
  result_type max() const;
2473
  };
2474
  ```
2475
 
2476
  ``` cpp
2477
- explicit negative_binomial_distribution(IntType k = 1, double p = 0.5);
2478
  ```
2479
 
2480
- *Requires:* 0 < `p` ≤ 1 and 0 < `k`.
2481
 
2482
- *Effects:* Constructs a `negative_binomial_distribution` object; `k` and
2483
- `p` correspond to the respective parameters of the distribution.
2484
 
2485
  ``` cpp
2486
  IntType k() const;
2487
  ```
2488
 
@@ -2500,16 +2843,12 @@ constructed.
2500
 
2501
  ##### Class template `poisson_distribution` <a id="rand.dist.pois.poisson">[[rand.dist.pois.poisson]]</a>
2502
 
2503
  A `poisson_distribution` random number distribution produces integer
2504
  values i ≥ 0 distributed according to the discrete probability function
2505
- $$%
2506
- P(i\,|\,\mu)
2507
- = \frac{ e^{-\mu} \mu^{i} }
2508
- { i\,! }
2509
- \; \mbox{.}$$ The distribution parameter μ is also known as this
2510
- distribution’s *mean* .
2511
 
2512
  ``` cpp
2513
  template<class IntType = int>
2514
  class poisson_distribution
2515
  {
@@ -2517,11 +2856,12 @@ template<class IntType = int>
2517
  // types
2518
  using result_type = IntType;
2519
  using param_type = unspecified;
2520
 
2521
  // constructors and reset functions
2522
- explicit poisson_distribution(double mean = 1.0);
 
2523
  explicit poisson_distribution(const param_type& parm);
2524
  void reset();
2525
 
2526
  // generating functions
2527
  template<class URBG>
@@ -2537,17 +2877,16 @@ template<class IntType = int>
2537
  result_type max() const;
2538
  };
2539
  ```
2540
 
2541
  ``` cpp
2542
- explicit poisson_distribution(double mean = 1.0);
2543
  ```
2544
 
2545
- *Requires:* 0 < `mean`.
2546
 
2547
- *Effects:* Constructs a `poisson_distribution` object; `mean`
2548
- corresponds to the parameter of the distribution.
2549
 
2550
  ``` cpp
2551
  double mean() const;
2552
  ```
2553
 
@@ -2556,25 +2895,23 @@ constructed.
2556
 
2557
  ##### Class template `exponential_distribution` <a id="rand.dist.pois.exp">[[rand.dist.pois.exp]]</a>
2558
 
2559
  An `exponential_distribution` random number distribution produces random
2560
  numbers x > 0 distributed according to the probability density function
2561
- $$%
2562
- p(x\,|\,\lambda)
2563
- = \lambda e^{-\lambda x}
2564
- \; \mbox{.}$$
2565
 
2566
  ``` cpp
2567
  template<class RealType = double>
2568
  class exponential_distribution {
2569
  public:
2570
  // types
2571
  using result_type = RealType;
2572
  using param_type = unspecified;
2573
 
2574
  // constructors and reset functions
2575
- explicit exponential_distribution(RealType lambda = 1.0);
 
2576
  explicit exponential_distribution(const param_type& parm);
2577
  void reset();
2578
 
2579
  // generating functions
2580
  template<class URBG>
@@ -2590,17 +2927,16 @@ template<class RealType = double>
2590
  result_type max() const;
2591
  };
2592
  ```
2593
 
2594
  ``` cpp
2595
- explicit exponential_distribution(RealType lambda = 1.0);
2596
  ```
2597
 
2598
- *Requires:* 0 < `lambda`.
2599
 
2600
- *Effects:* Constructs an `exponential_distribution` object; `lambda`
2601
- corresponds to the parameter of the distribution.
2602
 
2603
  ``` cpp
2604
  RealType lambda() const;
2605
  ```
2606
 
@@ -2609,26 +2945,25 @@ constructed.
2609
 
2610
  ##### Class template `gamma_distribution` <a id="rand.dist.pois.gamma">[[rand.dist.pois.gamma]]</a>
2611
 
2612
  A `gamma_distribution` random number distribution produces random
2613
  numbers x > 0 distributed according to the probability density function
2614
- $$%
2615
- p(x\,|\,\alpha,\beta)
2616
- = \frac{e^{-x/\beta}}{\beta^{\alpha} \cdot \Gamma(\alpha)}
2617
- \, \cdot \, x^{\, \alpha-1}
2618
- \; \mbox{.}$$
2619
 
2620
  ``` cpp
2621
  template<class RealType = double>
2622
  class gamma_distribution {
2623
  public:
2624
  // types
2625
  using result_type = RealType;
2626
  using param_type = unspecified;
2627
 
2628
  // constructors and reset functions
2629
- explicit gamma_distribution(RealType alpha = 1.0, RealType beta = 1.0);
 
2630
  explicit gamma_distribution(const param_type& parm);
2631
  void reset();
2632
 
2633
  // generating functions
2634
  template<class URBG>
@@ -2645,17 +2980,17 @@ template<class RealType = double>
2645
  result_type max() const;
2646
  };
2647
  ```
2648
 
2649
  ``` cpp
2650
- explicit gamma_distribution(RealType alpha = 1.0, RealType beta = 1.0);
2651
  ```
2652
 
2653
- *Requires:* 0 < `alpha` and 0 < `beta`.
2654
 
2655
- *Effects:* Constructs a `gamma_distribution` object; `alpha` and `beta`
2656
- correspond to the parameters of the distribution.
2657
 
2658
  ``` cpp
2659
  RealType alpha() const;
2660
  ```
2661
 
@@ -2671,27 +3006,26 @@ constructed.
2671
 
2672
  ##### Class template `weibull_distribution` <a id="rand.dist.pois.weibull">[[rand.dist.pois.weibull]]</a>
2673
 
2674
  A `weibull_distribution` random number distribution produces random
2675
  numbers x ≥ 0 distributed according to the probability density function
2676
- $$%
2677
- p(x\,|\,a,b)
2678
- = \frac{a}{b}
2679
  \cdot \left(\frac{x}{b}\right)^{a-1}
2680
  \cdot \, \exp\left( -\left(\frac{x}{b}\right)^a\right)
2681
- \; \mbox{.}$$
2682
 
2683
  ``` cpp
2684
  template<class RealType = double>
2685
  class weibull_distribution {
2686
  public:
2687
  // types
2688
  using result_type = RealType;
2689
  using param_type = unspecified;
2690
 
2691
  // constructor and reset functions
2692
- explicit weibull_distribution(RealType a = 1.0, RealType b = 1.0);
 
2693
  explicit weibull_distribution(const param_type& parm);
2694
  void reset();
2695
 
2696
  // generating functions
2697
  template<class URBG>
@@ -2708,17 +3042,17 @@ template<class RealType = double>
2708
  result_type max() const;
2709
  };
2710
  ```
2711
 
2712
  ``` cpp
2713
- explicit weibull_distribution(RealType a = 1.0, RealType b = 1.0);
2714
  ```
2715
 
2716
- *Requires:* 0 < `a` and 0 < `b`.
2717
 
2718
- *Effects:* Constructs a `weibull_distribution` object; `a` and `b`
2719
- correspond to the respective parameters of the distribution.
2720
 
2721
  ``` cpp
2722
  RealType a() const;
2723
  ```
2724
 
@@ -2734,28 +3068,25 @@ constructed.
2734
 
2735
  ##### Class template `extreme_value_distribution` <a id="rand.dist.pois.extreme">[[rand.dist.pois.extreme]]</a>
2736
 
2737
  An `extreme_value_distribution` random number distribution produces
2738
  random numbers x distributed according to the probability density
2739
- function[^6] $$%
2740
- p(x\,|\,a,b)
2741
- = \frac{1}{b}
2742
- \cdot \exp\left( \frac{a-x}{b}
2743
- \,-\, \exp\left(\frac{a-x}{b}\right)
2744
- \right)
2745
- \; \mbox{.}$$
2746
 
2747
  ``` cpp
2748
  template<class RealType = double>
2749
  class extreme_value_distribution {
2750
  public:
2751
  // types
2752
  using result_type = RealType;
2753
  using param_type = unspecified;
2754
 
2755
  // constructor and reset functions
2756
- explicit extreme_value_distribution(RealType a = 0.0, RealType b = 1.0);
 
2757
  explicit extreme_value_distribution(const param_type& parm);
2758
  void reset();
2759
 
2760
  // generating functions
2761
  template<class URBG>
@@ -2772,17 +3103,17 @@ template<class RealType = double>
2772
  result_type max() const;
2773
  };
2774
  ```
2775
 
2776
  ``` cpp
2777
- explicit extreme_value_distribution(RealType a = 0.0, RealType b = 1.0);
2778
  ```
2779
 
2780
- *Requires:* 0 < `b`.
2781
 
2782
- *Effects:* Constructs an `extreme_value_distribution` object; `a` and
2783
- `b` correspond to the respective parameters of the distribution.
2784
 
2785
  ``` cpp
2786
  RealType a() const;
2787
  ```
2788
 
@@ -2808,11 +3139,11 @@ numbers x distributed according to the probability density function $$%
2808
  % e^{-(x-\mu)^2 / (2\sigma^2)}
2809
  \exp{\left(- \, \frac{(x - \mu)^2}
2810
  {2 \sigma^2}
2811
  \right)
2812
  }
2813
- \; \mbox{.}$$ The distribution parameters μ and σ are also known as this
2814
  distribution’s *mean* and *standard deviation* .
2815
 
2816
  ``` cpp
2817
  template<class RealType = double>
2818
  class normal_distribution {
@@ -2820,11 +3151,12 @@ template<class RealType = double>
2820
  // types
2821
  using result_type = RealType;
2822
  using param_type = unspecified;
2823
 
2824
  // constructors and reset functions
2825
- explicit normal_distribution(RealType mean = 0.0, RealType stddev = 1.0);
 
2826
  explicit normal_distribution(const param_type& parm);
2827
  void reset();
2828
 
2829
  // generating functions
2830
  template<class URBG>
@@ -2841,17 +3173,17 @@ template<class RealType = double>
2841
  result_type max() const;
2842
  };
2843
  ```
2844
 
2845
  ``` cpp
2846
- explicit normal_distribution(RealType mean = 0.0, RealType stddev = 1.0);
2847
  ```
2848
 
2849
- *Requires:* 0 < `stddev`.
2850
 
2851
- *Effects:* Constructs a `normal_distribution` object; `mean` and
2852
- `stddev` correspond to the respective parameters of the distribution.
2853
 
2854
  ``` cpp
2855
  RealType mean() const;
2856
  ```
2857
 
@@ -2867,31 +3199,25 @@ constructed.
2867
 
2868
  ##### Class template `lognormal_distribution` <a id="rand.dist.norm.lognormal">[[rand.dist.norm.lognormal]]</a>
2869
 
2870
  A `lognormal_distribution` random number distribution produces random
2871
  numbers x > 0 distributed according to the probability density function
2872
- $$%
2873
- p(x\,|\,m,s)
2874
- = \frac{1}
2875
- {s x \sqrt{2 \pi}}
2876
- \cdot
2877
- \exp{\left(- \, \frac{(\ln{x} - m)^2}
2878
- {2 s^2}
2879
- \right)
2880
- }
2881
- \; \mbox{.}$$
2882
 
2883
  ``` cpp
2884
  template<class RealType = double>
2885
  class lognormal_distribution {
2886
  public:
2887
  // types
2888
  using result_type = RealType;
2889
  using param_type = unspecified;
2890
 
2891
  // constructor and reset functions
2892
- explicit lognormal_distribution(RealType m = 0.0, RealType s = 1.0);
 
2893
  explicit lognormal_distribution(const param_type& parm);
2894
  void reset();
2895
 
2896
  // generating functions
2897
  template<class URBG>
@@ -2908,17 +3234,17 @@ template<class RealType = double>
2908
  result_type max() const;
2909
  };
2910
  ```
2911
 
2912
  ``` cpp
2913
- explicit lognormal_distribution(RealType m = 0.0, RealType s = 1.0);
2914
  ```
2915
 
2916
- *Requires:* 0 < `s`.
2917
 
2918
- *Effects:* Constructs a `lognormal_distribution` object; `m` and `s`
2919
- correspond to the respective parameters of the distribution.
2920
 
2921
  ``` cpp
2922
  RealType m() const;
2923
  ```
2924
 
@@ -2934,26 +3260,23 @@ constructed.
2934
 
2935
  ##### Class template `chi_squared_distribution` <a id="rand.dist.norm.chisq">[[rand.dist.norm.chisq]]</a>
2936
 
2937
  A `chi_squared_distribution` random number distribution produces random
2938
  numbers x > 0 distributed according to the probability density function
2939
- $$%
2940
- p(x\,|\,n)
2941
- = \frac{ x^{(n/2)-1} \cdot e^{-x/2}}
2942
- {\Gamma(n/2) \cdot 2^{n/2}}
2943
- \; \mbox{.}$$
2944
 
2945
  ``` cpp
2946
  template<class RealType = double>
2947
  class chi_squared_distribution {
2948
  public:
2949
  // types
2950
  using result_type = RealType;
2951
  using param_type = unspecified;
2952
 
2953
  // constructor and reset functions
2954
- explicit chi_squared_distribution(RealType n = 1);
 
2955
  explicit chi_squared_distribution(const param_type& parm);
2956
  void reset();
2957
 
2958
  // generating functions
2959
  template<class URBG>
@@ -2969,17 +3292,16 @@ template<class RealType = double>
2969
  result_type max() const;
2970
  };
2971
  ```
2972
 
2973
  ``` cpp
2974
- explicit chi_squared_distribution(RealType n = 1);
2975
  ```
2976
 
2977
- *Requires:* 0 < `n`.
2978
 
2979
- *Effects:* Constructs a `chi_squared_distribution` object; `n`
2980
- corresponds to the parameter of the distribution.
2981
 
2982
  ``` cpp
2983
  RealType n() const;
2984
  ```
2985
 
@@ -2987,25 +3309,24 @@ RealType n() const;
2987
  constructed.
2988
 
2989
  ##### Class template `cauchy_distribution` <a id="rand.dist.norm.cauchy">[[rand.dist.norm.cauchy]]</a>
2990
 
2991
  A `cauchy_distribution` random number distribution produces random
2992
- numbers x distributed according to the probability density function $$%
2993
- p(x\,|\,a,b)
2994
- = \left( \pi b \left( 1 + \left( \frac{x-a}{b} \right)^2 \;\right)\right)^{-1}
2995
- \; \mbox{.}$$
2996
 
2997
  ``` cpp
2998
  template<class RealType = double>
2999
  class cauchy_distribution {
3000
  public:
3001
  // types
3002
  using result_type = RealType;
3003
  using param_type = unspecified;
3004
 
3005
  // constructor and reset functions
3006
- explicit cauchy_distribution(RealType a = 0.0, RealType b = 1.0);
 
3007
  explicit cauchy_distribution(const param_type& parm);
3008
  void reset();
3009
 
3010
  // generating functions
3011
  template<class URBG>
@@ -3022,17 +3343,17 @@ template<class RealType = double>
3022
  result_type max() const;
3023
  };
3024
  ```
3025
 
3026
  ``` cpp
3027
- explicit cauchy_distribution(RealType a = 0.0, RealType b = 1.0);
3028
  ```
3029
 
3030
- *Requires:* 0 < `b`.
3031
 
3032
- *Effects:* Constructs a `cauchy_distribution` object; `a` and `b`
3033
- correspond to the respective parameters of the distribution.
3034
 
3035
  ``` cpp
3036
  RealType a() const;
3037
  ```
3038
 
@@ -3048,32 +3369,27 @@ constructed.
3048
 
3049
  ##### Class template `fisher_f_distribution` <a id="rand.dist.norm.f">[[rand.dist.norm.f]]</a>
3050
 
3051
  A `fisher_f_distribution` random number distribution produces random
3052
  numbers x ≥ 0 distributed according to the probability density function
3053
- $$%
3054
- p(x\,|\,m,n)
3055
- = \frac{\Gamma\big((m+n)/2\big)}
3056
- {\Gamma(m/2) \; \Gamma(n/2)}
3057
- \cdot
3058
- \left(\frac{m}{n}\right)^{m/2}
3059
- \cdot
3060
- x^{(m/2)-1}
3061
- \cdot
3062
- {\left( 1 + \frac{m x}{n} \right)}^{-(m+n)/2}
3063
- \; \mbox{.}$$
3064
 
3065
  ``` cpp
3066
  template<class RealType = double>
3067
  class fisher_f_distribution {
3068
  public:
3069
  // types
3070
  using result_type = RealType;
3071
  using param_type = unspecified;
3072
 
3073
  // constructor and reset functions
3074
- explicit fisher_f_distribution(RealType m = 1, RealType n = 1);
 
3075
  explicit fisher_f_distribution(const param_type& parm);
3076
  void reset();
3077
 
3078
  // generating functions
3079
  template<class URBG>
@@ -3090,17 +3406,17 @@ template<class RealType = double>
3090
  result_type max() const;
3091
  };
3092
  ```
3093
 
3094
  ``` cpp
3095
- explicit fisher_f_distribution(RealType m = 1, RealType n = 1);
3096
  ```
3097
 
3098
- *Requires:* 0 < `m` and 0 < `n`.
3099
 
3100
- *Effects:* Constructs a `fisher_f_distribution` object; `m` and `n`
3101
- correspond to the respective parameters of the distribution.
3102
 
3103
  ``` cpp
3104
  RealType m() const;
3105
  ```
3106
 
@@ -3115,29 +3431,27 @@ RealType n() const;
3115
  constructed.
3116
 
3117
  ##### Class template `student_t_distribution` <a id="rand.dist.norm.t">[[rand.dist.norm.t]]</a>
3118
 
3119
  A `student_t_distribution` random number distribution produces random
3120
- numbers x distributed according to the probability density function $$%
3121
- p(x\,|\,n)
3122
- = \frac{1}
3123
- {\sqrt{n \pi}}
3124
- \cdot \frac{\Gamma\big((n+1)/2\big)}
3125
- {\Gamma(n/2)}
3126
  \cdot \left(1 + \frac{x^2}{n} \right)^{-(n+1)/2}
3127
- \; \mbox{.}$$
3128
 
3129
  ``` cpp
3130
  template<class RealType = double>
3131
  class student_t_distribution {
3132
  public:
3133
  // types
3134
  using result_type = RealType;
3135
  using param_type = unspecified;
3136
 
3137
  // constructor and reset functions
3138
- explicit student_t_distribution(RealType n = 1);
 
3139
  explicit student_t_distribution(const param_type& parm);
3140
  void reset();
3141
 
3142
  // generating functions
3143
  template<class URBG>
@@ -3153,17 +3467,16 @@ template<class RealType = double>
3153
  result_type max() const;
3154
  };
3155
  ```
3156
 
3157
  ``` cpp
3158
- explicit student_t_distribution(RealType n = 1);
3159
  ```
3160
 
3161
- *Requires:* 0 < `n`.
3162
 
3163
- *Effects:* Constructs a `student_t_distribution` object; `n` corresponds
3164
- to the parameter of the distribution.
3165
 
3166
  ``` cpp
3167
  RealType n() const;
3168
  ```
3169
 
@@ -3174,20 +3487,17 @@ constructed.
3174
 
3175
  ##### Class template `discrete_distribution` <a id="rand.dist.samp.discrete">[[rand.dist.samp.discrete]]</a>
3176
 
3177
  A `discrete_distribution` random number distribution produces random
3178
  integers i, 0 ≤ i < n, distributed according to the discrete probability
3179
- function $$%
3180
- P(i\,|\,p_0,\ldots,p_{n-1})
3181
- = p_i
3182
- \; \mbox{.}$$
3183
 
3184
  Unless specified otherwise, the distribution parameters are calculated
3185
- as: $p_k = {w_k / S} \; \mbox{ for } k = 0, \ldots, n\!-\!1$ , in which
3186
- the values wₖ, commonly known as the *weights* , shall be non-negative,
3187
- non-NaN, and non-infinity. Moreover, the following relation shall hold:
3188
- 0 < S = w₀ + + wₙ₋₁.
3189
 
3190
  ``` cpp
3191
  template<class IntType = int>
3192
  class discrete_distribution {
3193
  public:
@@ -3233,15 +3543,18 @@ p₀ = 1.
3233
  ``` cpp
3234
  template<class InputIterator>
3235
  discrete_distribution(InputIterator firstW, InputIterator lastW);
3236
  ```
3237
 
3238
- *Requires:* `InputIterator` shall satisfy the requirements of an input
3239
- iterator ([[input.iterators]]). Moreover,
3240
- `iterator_traits<InputIterator>::value_type` shall denote a type that is
3241
- convertible to `double`. If `firstW == lastW`, let n = 1 and w₀ = 1.
3242
- Otherwise, [`firstW`, `lastW`) shall form a sequence w of length n > 0.
 
 
 
3243
 
3244
  *Effects:* Constructs a `discrete_distribution` object with
3245
  probabilities given by the formula above.
3246
 
3247
  ``` cpp
@@ -3253,22 +3566,22 @@ discrete_distribution(initializer_list<double> wl);
3253
  ``` cpp
3254
  template<class UnaryOperation>
3255
  discrete_distribution(size_t nw, double xmin, double xmax, UnaryOperation fw);
3256
  ```
3257
 
3258
- *Requires:* Each instance of type `UnaryOperation` shall be a function
3259
- object ([[function.objects]]) whose return type shall be convertible to
3260
- `double`. Moreover, `double` shall be convertible to the type of
3261
- `UnaryOperation`’s sole parameter. If `nw` = 0, let n = 1, otherwise let
3262
- n = `nw`. The relation 0 < δ = (`xmax` - `xmin`) / n shall hold.
3263
 
3264
  *Effects:* Constructs a `discrete_distribution` object with
3265
  probabilities given by the formula above, using the following values: If
3266
  `nw` = 0, let w₀ = 1. Otherwise, let wₖ = `fw`(`xmin` + k ⋅ δ + δ / 2)
3267
  for k = 0, …, n - 1.
3268
 
3269
- *Complexity:* The number of invocations of `fw` shall not exceed n.
3270
 
3271
  ``` cpp
3272
  vector<double> probabilities() const;
3273
  ```
3274
 
@@ -3279,27 +3592,21 @@ k = 0, …, n-1.
3279
  ##### Class template `piecewise_constant_distribution` <a id="rand.dist.samp.pconst">[[rand.dist.samp.pconst]]</a>
3280
 
3281
  A `piecewise_constant_distribution` random number distribution produces
3282
  random numbers x, b₀ ≤ x < bₙ, uniformly distributed over each
3283
  subinterval [ bᵢ, bᵢ₊₁ ) according to the probability density function
3284
- $$%
3285
- p(x\,|\,b_0,\ldots,b_n,\;\rho_0,\ldots,\rho_{n-1})
3286
- = \rho_i
3287
- \; \mbox{,}
3288
- \mbox{ for } b_i \le x < b_{i+1}
3289
- \; \mbox{.}$$
3290
 
3291
  The n + 1 distribution parameters bᵢ, also known as this distribution’s
3292
- *interval boundaries* , shall satisfy the relation bᵢ < bᵢ₊₁ for
3293
- i = 0, …, n-1. Unless specified otherwise, the remaining n distribution
3294
- parameters are calculated as: $$%
3295
- \rho_k = \;
3296
- \frac{w_k}{S \cdot (b_{k+1}-b_k)}
3297
- \; \mbox{ for } k = 0, \ldots, n\!-\!1,$$ in which the values wₖ,
3298
- commonly known as the *weights* , shall be non-negative, non-NaN, and
3299
- non-infinity. Moreover, the following relation shall hold:
3300
- 0 < S = w₀ + ⋯ + wₙ₋₁.
3301
 
3302
  ``` cpp
3303
  template<class RealType = double>
3304
  class piecewise_constant_distribution {
3305
  public:
@@ -3347,59 +3654,60 @@ n = 1, ρ₀ = 1, b₀ = 0, and b₁ = 1.
3347
  template<class InputIteratorB, class InputIteratorW>
3348
  piecewise_constant_distribution(InputIteratorB firstB, InputIteratorB lastB,
3349
  InputIteratorW firstW);
3350
  ```
3351
 
3352
- *Requires:* `InputIteratorB` and `InputIteratorW` shall each satisfy the
3353
- requirements of an input iterator
3354
- (Table  [[tab:iterator.input.requirements]]) type. Moreover,
3355
- `iterator_traits<InputIteratorB>::value_type` and
3356
- `iterator_traits<InputIteratorW>::value_type` shall each denote a type
3357
- that is convertible to `double`. If `firstB == lastB` or
3358
- `++firstB == lastB`, let n = 1, w₀ = 1, b₀ = 0, and b₁ = 1. Otherwise,
3359
- [`firstB`, `lastB`) shall form a sequence b of length n+1, the length of
3360
- the sequence w starting from `firstW` shall be at least n, and any wₖ
3361
- for k n shall be ignored by the distribution.
 
 
 
3362
 
3363
  *Effects:* Constructs a `piecewise_constant_distribution` object with
3364
  parameters as specified above.
3365
 
3366
  ``` cpp
3367
  template<class UnaryOperation>
3368
  piecewise_constant_distribution(initializer_list<RealType> bl, UnaryOperation fw);
3369
  ```
3370
 
3371
- *Requires:* Each instance of type `UnaryOperation` shall be a function
3372
- object ([[function.objects]]) whose return type shall be convertible to
3373
- `double`. Moreover, `double` shall be convertible to the type of
3374
- `UnaryOperation`’s sole parameter.
3375
 
3376
  *Effects:* Constructs a `piecewise_constant_distribution` object with
3377
  parameters taken or calculated from the following values: If
3378
  `bl.size()` < 2, let n = 1, w₀ = 1, b₀ = 0, and b₁ = 1. Otherwise, let
3379
  [`bl.begin()`, `bl.end()`) form a sequence b₀, …, bₙ, and let
3380
  wₖ = `fw`((bₖ₊₁ + bₖ) / 2) for k = 0, …, n - 1.
3381
 
3382
- *Complexity:* The number of invocations of `fw` shall not exceed n.
3383
 
3384
  ``` cpp
3385
  template<class UnaryOperation>
3386
  piecewise_constant_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);
3387
  ```
3388
 
3389
- *Requires:* Each instance of type `UnaryOperation` shall be a function
3390
- object ([[function.objects]]) whose return type shall be convertible to
3391
- `double`. Moreover, `double` shall be convertible to the type of
3392
- `UnaryOperation`’s sole parameter. If `nw` = 0, let n = 1, otherwise let
3393
- n = `nw`. The relation 0 < δ = (`xmax` - `xmin`) / n shall hold.
3394
 
3395
  *Effects:* Constructs a `piecewise_constant_distribution` object with
3396
  parameters taken or calculated from the following values: Let
3397
  bₖ = `xmin` + k ⋅ δ for k = 0, …, n, and wₖ = `fw`(bₖ + δ / 2) for
3398
  k = 0, …, n - 1.
3399
 
3400
- *Complexity:* The number of invocations of `fw` shall not exceed n.
3401
 
3402
  ``` cpp
3403
  vector<result_type> intervals() const;
3404
  ```
3405
 
@@ -3417,29 +3725,24 @@ k = 0, …, n-1.
3417
 
3418
  ##### Class template `piecewise_linear_distribution` <a id="rand.dist.samp.plinear">[[rand.dist.samp.plinear]]</a>
3419
 
3420
  A `piecewise_linear_distribution` random number distribution produces
3421
  random numbers x, b₀ ≤ x < bₙ, distributed over each subinterval
3422
- [ bᵢ, bᵢ₊₁ ) according to the probability density function $$%
3423
- p(x\,|\,b_0,\ldots,b_n,\;\rho_0,\ldots,\rho_n)
3424
- = \rho_i \cdot {\frac{b_{i+1} - x}{b_{i+1} - b_i}}
3425
  + \rho_{i+1} \cdot {\frac{x - b_i}{b_{i+1} - b_i}}
3426
- \; \mbox{,}
3427
- \mbox{ for } b_i \le x < b_{i+1}
3428
- \; \mbox{.}$$
3429
 
3430
  The n + 1 distribution parameters bᵢ, also known as this distribution’s
3431
  *interval boundaries* , shall satisfy the relation bᵢ < bᵢ₊₁ for
3432
  i = 0, …, n - 1. Unless specified otherwise, the remaining n + 1
3433
- distribution parameters are calculated as
3434
- $\rho_k = {w_k / S} \; \mbox{ for } k = 0, \ldots, n$, in which the
3435
- values wₖ, commonly known as the *weights at boundaries* , shall be
3436
- non-negative, non-NaN, and non-infinity. Moreover, the following
3437
- relation shall hold: $$%
3438
- 0 < S = \frac{1}{2}
3439
- \cdot \sum_{k=0}^{n-1} (w_k + w_{k+1}) \cdot (b_{k+1} - b_k)
3440
- \; \mbox{.}$$
3441
 
3442
  ``` cpp
3443
  template<class RealType = double>
3444
  class piecewise_linear_distribution {
3445
  public:
@@ -3486,58 +3789,55 @@ n = 1, ρ₀ = ρ₁ = 1, b₀ = 0, and b₁ = 1.
3486
  template<class InputIteratorB, class InputIteratorW>
3487
  piecewise_linear_distribution(InputIteratorB firstB, InputIteratorB lastB,
3488
  InputIteratorW firstW);
3489
  ```
3490
 
3491
- *Requires:* `InputIteratorB` and `InputIteratorW` shall each satisfy the
3492
- requirements of an input iterator
3493
- (Table  [[tab:iterator.input.requirements]]) type. Moreover,
3494
- `iterator_traits<InputIteratorB>::value_type` and
3495
- `iterator_traits<InputIteratorW>::value_type` shall each denote a type
3496
- that is convertible to `double`. If `firstB == lastB` or
3497
- `++firstB == lastB`, let n = 1, ρ₀ = ρ₁ = 1, b₀ = 0, and b = 1.
3498
- Otherwise, [`firstB`, `lastB`) shall form a sequence b of length n+1,
3499
- the length of the sequence w starting from `firstW` shall be at least
3500
- n+1, and any wₖ for k ≥ n+1 shall be ignored by the distribution.
3501
 
3502
  *Effects:* Constructs a `piecewise_linear_distribution` object with
3503
  parameters as specified above.
3504
 
3505
  ``` cpp
3506
  template<class UnaryOperation>
3507
  piecewise_linear_distribution(initializer_list<RealType> bl, UnaryOperation fw);
3508
  ```
3509
 
3510
- *Requires:* Each instance of type `UnaryOperation` shall be a function
3511
- object ([[function.objects]]) whose return type shall be convertible to
3512
- `double`. Moreover, `double` shall be convertible to the type of
3513
- `UnaryOperation`’s sole parameter.
3514
 
3515
  *Effects:* Constructs a `piecewise_linear_distribution` object with
3516
  parameters taken or calculated from the following values: If
3517
  `bl.size()` < 2, let n = 1, ρ₀ = ρ₁ = 1, b₀ = 0, and b₁ = 1. Otherwise,
3518
  let [`bl.begin(),` `bl.end()`) form a sequence b₀, …, bₙ, and let
3519
  wₖ = `fw`(bₖ) for k = 0, …, n.
3520
 
3521
- *Complexity:* The number of invocations of `fw` shall not exceed n+1.
3522
 
3523
  ``` cpp
3524
  template<class UnaryOperation>
3525
  piecewise_linear_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);
3526
  ```
3527
 
3528
- *Requires:* Each instance of type `UnaryOperation` shall be a function
3529
- object ([[function.objects]]) whose return type shall be convertible to
3530
- `double`. Moreover, `double` shall be convertible to the type of
3531
- `UnaryOperation`’s sole parameter. If `nw` = 0, let n = 1, otherwise let
3532
- n = `nw`. The relation 0 < δ = (`xmax` - `xmin`) / n shall hold.
3533
 
3534
  *Effects:* Constructs a `piecewise_linear_distribution` object with
3535
  parameters taken or calculated from the following values: Let
3536
  bₖ = `xmin` + k ⋅ δ for k = 0, …, n, and wₖ = `fw`(bₖ) for k = 0, …, n.
3537
 
3538
- *Complexity:* The number of invocations of `fw` shall not exceed n+1.
3539
 
3540
  ``` cpp
3541
  vector<result_type> intervals() const;
3542
  ```
3543
 
@@ -3553,12 +3853,12 @@ vector<result_type> densities() const;
3553
  whose `operator[]` member returns ρₖ when invoked with argument k for
3554
  k = 0, …, n.
3555
 
3556
  ### Low-quality random number generation <a id="c.math.rand">[[c.math.rand]]</a>
3557
 
3558
- [*Note 1*: The header `<cstdlib>` ([[cstdlib.syn]]) declares the
3559
- functions described in this subclause. — *end note*]
3560
 
3561
  ``` cpp
3562
  int rand();
3563
  void srand(unsigned int seed);
3564
  ```
@@ -3566,19 +3866,19 @@ void srand(unsigned int seed);
3566
  *Effects:* The `rand` and `srand` functions have the semantics specified
3567
  in the C standard library.
3568
 
3569
  *Remarks:* The implementation may specify that particular library
3570
  functions may call `rand`. It is *implementation-defined* whether the
3571
- `rand` function may introduce data races ([[res.on.data.races]]).
3572
 
3573
  [*Note 1*: The other random number generation facilities in this
3574
- International Standard ([[rand]]) are often preferable to `rand`,
3575
- because `rand`’s underlying algorithm is unspecified. Use of `rand`
3576
- therefore continues to be non-portable, with unpredictable and
3577
- oft-questionable quality and performance. — *end note*]
3578
 
3579
- ISO C 7.22.2
3580
 
3581
  ## Numeric arrays <a id="numarray">[[numarray]]</a>
3582
 
3583
  ### Header `<valarray>` synopsis <a id="valarray.syn">[[valarray.syn]]</a>
3584
 
@@ -3595,101 +3895,133 @@ namespace std {
3595
  template<class T> class indirect_array; // an indirected array
3596
 
3597
  template<class T> void swap(valarray<T>&, valarray<T>&) noexcept;
3598
 
3599
  template<class T> valarray<T> operator* (const valarray<T>&, const valarray<T>&);
3600
- template<class T> valarray<T> operator* (const valarray<T>&, const T&);
3601
- template<class T> valarray<T> operator* (const T&, const valarray<T>&);
 
 
3602
 
3603
  template<class T> valarray<T> operator/ (const valarray<T>&, const valarray<T>&);
3604
- template<class T> valarray<T> operator/ (const valarray<T>&, const T&);
3605
- template<class T> valarray<T> operator/ (const T&, const valarray<T>&);
 
 
3606
 
3607
  template<class T> valarray<T> operator% (const valarray<T>&, const valarray<T>&);
3608
- template<class T> valarray<T> operator% (const valarray<T>&, const T&);
3609
- template<class T> valarray<T> operator% (const T&, const valarray<T>&);
 
 
3610
 
3611
  template<class T> valarray<T> operator+ (const valarray<T>&, const valarray<T>&);
3612
- template<class T> valarray<T> operator+ (const valarray<T>&, const T&);
3613
- template<class T> valarray<T> operator+ (const T&, const valarray<T>&);
 
 
3614
 
3615
  template<class T> valarray<T> operator- (const valarray<T>&, const valarray<T>&);
3616
- template<class T> valarray<T> operator- (const valarray<T>&, const T&);
3617
- template<class T> valarray<T> operator- (const T&, const valarray<T>&);
 
 
3618
 
3619
  template<class T> valarray<T> operator^ (const valarray<T>&, const valarray<T>&);
3620
- template<class T> valarray<T> operator^ (const valarray<T>&, const T&);
3621
- template<class T> valarray<T> operator^ (const T&, const valarray<T>&);
 
 
3622
 
3623
  template<class T> valarray<T> operator& (const valarray<T>&, const valarray<T>&);
3624
- template<class T> valarray<T> operator& (const valarray<T>&, const T&);
3625
- template<class T> valarray<T> operator& (const T&, const valarray<T>&);
 
 
3626
 
3627
  template<class T> valarray<T> operator| (const valarray<T>&, const valarray<T>&);
3628
- template<class T> valarray<T> operator| (const valarray<T>&, const T&);
3629
- template<class T> valarray<T> operator| (const T&, const valarray<T>&);
 
 
3630
 
3631
  template<class T> valarray<T> operator<<(const valarray<T>&, const valarray<T>&);
3632
- template<class T> valarray<T> operator<<(const valarray<T>&, const T&);
3633
- template<class T> valarray<T> operator<<(const T&, const valarray<T>&);
 
 
3634
 
3635
  template<class T> valarray<T> operator>>(const valarray<T>&, const valarray<T>&);
3636
- template<class T> valarray<T> operator>>(const valarray<T>&, const T&);
3637
- template<class T> valarray<T> operator>>(const T&, const valarray<T>&);
 
 
3638
 
3639
  template<class T> valarray<bool> operator&&(const valarray<T>&, const valarray<T>&);
3640
- template<class T> valarray<bool> operator&&(const valarray<T>&, const T&);
3641
- template<class T> valarray<bool> operator&&(const T&, const valarray<T>&);
 
 
3642
 
3643
  template<class T> valarray<bool> operator||(const valarray<T>&, const valarray<T>&);
3644
- template<class T> valarray<bool> operator||(const valarray<T>&, const T&);
3645
- template<class T> valarray<bool> operator||(const T&, const valarray<T>&);
 
 
3646
 
3647
- template<class T>
3648
- valarray<bool> operator==(const valarray<T>&, const valarray<T>&);
3649
- template<class T> valarray<bool> operator==(const valarray<T>&, const T&);
3650
- template<class T> valarray<bool> operator==(const T&, const valarray<T>&);
3651
- template<class T>
3652
- valarray<bool> operator!=(const valarray<T>&, const valarray<T>&);
3653
- template<class T> valarray<bool> operator!=(const valarray<T>&, const T&);
3654
- template<class T> valarray<bool> operator!=(const T&, const valarray<T>&);
 
 
3655
 
3656
- template<class T>
3657
- valarray<bool> operator< (const valarray<T>&, const valarray<T>&);
3658
- template<class T> valarray<bool> operator< (const valarray<T>&, const T&);
3659
- template<class T> valarray<bool> operator< (const T&, const valarray<T>&);
3660
- template<class T>
3661
- valarray<bool> operator> (const valarray<T>&, const valarray<T>&);
3662
- template<class T> valarray<bool> operator> (const valarray<T>&, const T&);
3663
- template<class T> valarray<bool> operator> (const T&, const valarray<T>&);
3664
- template<class T>
3665
- valarray<bool> operator<=(const valarray<T>&, const valarray<T>&);
3666
- template<class T> valarray<bool> operator<=(const valarray<T>&, const T&);
3667
- template<class T> valarray<bool> operator<=(const T&, const valarray<T>&);
3668
- template<class T>
3669
- valarray<bool> operator>=(const valarray<T>&, const valarray<T>&);
3670
- template<class T> valarray<bool> operator>=(const valarray<T>&, const T&);
3671
- template<class T> valarray<bool> operator>=(const T&, const valarray<T>&);
 
 
 
 
3672
 
3673
  template<class T> valarray<T> abs (const valarray<T>&);
3674
  template<class T> valarray<T> acos (const valarray<T>&);
3675
  template<class T> valarray<T> asin (const valarray<T>&);
3676
  template<class T> valarray<T> atan (const valarray<T>&);
3677
 
3678
  template<class T> valarray<T> atan2(const valarray<T>&, const valarray<T>&);
3679
- template<class T> valarray<T> atan2(const valarray<T>&, const T&);
3680
- template<class T> valarray<T> atan2(const T&, const valarray<T>&);
 
 
3681
 
3682
  template<class T> valarray<T> cos (const valarray<T>&);
3683
  template<class T> valarray<T> cosh (const valarray<T>&);
3684
  template<class T> valarray<T> exp (const valarray<T>&);
3685
  template<class T> valarray<T> log (const valarray<T>&);
3686
  template<class T> valarray<T> log10(const valarray<T>&);
3687
 
3688
  template<class T> valarray<T> pow(const valarray<T>&, const valarray<T>&);
3689
- template<class T> valarray<T> pow(const valarray<T>&, const T&);
3690
- template<class T> valarray<T> pow(const T&, const valarray<T>&);
3691
 
3692
  template<class T> valarray<T> sin (const valarray<T>&);
3693
  template<class T> valarray<T> sinh (const valarray<T>&);
3694
  template<class T> valarray<T> sqrt (const valarray<T>&);
3695
  template<class T> valarray<T> tan (const valarray<T>&);
@@ -3718,28 +4050,28 @@ nested argument type.[^7]
3718
 
3719
  Implementations introducing such replacement types shall provide
3720
  additional functions and operators as follows:
3721
 
3722
  - for every function taking a `const valarray<T>&` other than `begin`
3723
- and `end` ([[valarray.range]]), identical functions taking the
3724
  replacement types shall be added;
3725
  - for every function taking two `const valarray<T>&` arguments,
3726
  identical functions taking every combination of `const valarray<T>&`
3727
  and replacement types shall be added.
3728
 
3729
  In particular, an implementation shall allow a `valarray<T>` to be
3730
  constructed from such replacement types and shall allow assignments and
3731
  compound assignments of such types to `valarray<T>`, `slice_array<T>`,
3732
  `gslice_array<T>`, `mask_array<T>` and `indirect_array<T>` objects.
3733
 
3734
- These library functions are permitted to throw a `bad_alloc` (
3735
- [[bad.alloc]]) exception if there are not sufficient resources available
3736
  to carry out the operation. Note that the exception is not mandated.
3737
 
3738
  ### Class template `valarray` <a id="template.valarray">[[template.valarray]]</a>
3739
 
3740
- #### Class template `valarray` overview <a id="template.valarray.overview">[[template.valarray.overview]]</a>
3741
 
3742
  ``` cpp
3743
  namespace std {
3744
  template<class T> class valarray {
3745
  public:
@@ -3839,14 +4171,11 @@ object of type `valarray<T>` is referred to as an “array” throughout the
3839
  remainder of  [[numarray]]. The illusion of higher dimensionality may be
3840
  produced by the familiar idiom of computed indices, together with the
3841
  powerful subsetting capabilities provided by the generalized subscript
3842
  operators.[^8]
3843
 
3844
- An implementation is permitted to qualify any of the functions declared
3845
- in `<valarray>` as `inline`.
3846
-
3847
- #### `valarray` constructors <a id="valarray.cons">[[valarray.cons]]</a>
3848
 
3849
  ``` cpp
3850
  valarray();
3851
  ```
3852
 
@@ -3855,11 +4184,11 @@ valarray();
3855
  ``` cpp
3856
  explicit valarray(size_t n);
3857
  ```
3858
 
3859
  *Effects:* Constructs a `valarray` that has length `n`. Each element of
3860
- the array is value-initialized ([[dcl.init]]).
3861
 
3862
  ``` cpp
3863
  valarray(const T& v, size_t n);
3864
  ```
3865
 
@@ -3868,12 +4197,11 @@ the array is initialized with `v`.
3868
 
3869
  ``` cpp
3870
  valarray(const T* p, size_t n);
3871
  ```
3872
 
3873
- *Requires:* `p` points to an array ([[dcl.array]]) of at least `n`
3874
- elements.
3875
 
3876
  *Effects:* Constructs a `valarray` that has length `n`. The values of
3877
  the elements of the array are initialized with the first `n` values
3878
  pointed to by the first argument.[^10]
3879
 
@@ -3916,11 +4244,11 @@ templates to a `valarray`.
3916
  ```
3917
 
3918
  *Effects:* The destructor is applied to every element of `*this`; an
3919
  implementation may return all allocated memory.
3920
 
3921
- #### `valarray` assignment <a id="valarray.assign">[[valarray.assign]]</a>
3922
 
3923
  ``` cpp
3924
  valarray& operator=(const valarray& v);
3925
  ```
3926
 
@@ -3928,11 +4256,11 @@ valarray& operator=(const valarray& v);
3928
  the corresponding element of `v`. If the length of `v` is not equal to
3929
  the length of `*this`, resizes `*this` to make the two arrays the same
3930
  length, as if by calling `resize(v.size())`, before performing the
3931
  assignment.
3932
 
3933
- *Postconditions:* `size() == v.size()`.
3934
 
3935
  *Returns:* `*this`.
3936
 
3937
  ``` cpp
3938
  valarray& operator=(valarray&& v) noexcept;
@@ -3964,63 +4292,64 @@ valarray& operator=(const slice_array<T>&);
3964
  valarray& operator=(const gslice_array<T>&);
3965
  valarray& operator=(const mask_array<T>&);
3966
  valarray& operator=(const indirect_array<T>&);
3967
  ```
3968
 
3969
- *Requires:* The length of the array to which the argument refers equals
3970
- `size()`. The value of an element in the left-hand side of a `valarray`
3971
- assignment operator does not depend on the value of another element in
3972
- that left-hand side.
3973
 
3974
  These operators allow the results of a generalized subscripting
3975
  operation to be assigned directly to a `valarray`.
3976
 
3977
- #### `valarray` element access <a id="valarray.access">[[valarray.access]]</a>
3978
 
3979
  ``` cpp
3980
  const T& operator[](size_t n) const;
3981
  T& operator[](size_t n);
3982
  ```
3983
 
3984
- *Requires:* `n < size()`.
3985
 
3986
  *Returns:* A reference to the corresponding element of the array.
3987
 
3988
  [*Note 1*: The expression `(a[i] = q, a[i]) == q` evaluates to `true`
3989
  for any non-constant `valarray<T> a`, any `T q`, and for any `size_t i`
3990
  such that the value of `i` is less than the length of
3991
  `a`. — *end note*]
3992
 
3993
- *Remarks:* The expression `&a[i+j] == &a[i] + j` evaluates to `true` for
3994
- all `size_t i` and `size_t j` such that `i+j < a.size()`.
 
3995
 
3996
- The expression `&a[i] != &b[j]` evaluates to `true` for any two arrays
3997
- `a` and `b` and for any `size_t i` and `size_t j` such that
3998
- `i < a.size()` and `j < b.size()`.
3999
 
4000
  [*Note 2*: This property indicates an absence of aliasing and may be
4001
  used to advantage by optimizing compilers. Compilers may take advantage
4002
  of inlining, constant propagation, loop fusion, tracking of pointers
4003
  obtained from `operator new`, and other techniques to generate efficient
4004
  `valarray`s. — *end note*]
4005
 
4006
  The reference returned by the subscript operator for an array shall be
4007
- valid until the member function
4008
- `resize(size_t, T)` ([[valarray.members]]) is called for that array or
4009
- until the lifetime of that array ends, whichever happens first.
4010
 
4011
- #### `valarray` subset operations <a id="valarray.sub">[[valarray.sub]]</a>
4012
 
4013
  The member `operator[]` is overloaded to provide several ways to select
4014
  sequences of elements from among those controlled by `*this`. Each of
4015
  these operations returns a subset of the array. The const-qualified
4016
  versions return this subset as a new `valarray` object. The non-const
4017
  versions return a class template object which has reference semantics to
4018
  the original array, working in conjunction with various overloads of
4019
  `operator=` and other assigning operators to allow selective replacement
4020
  (slicing) of the controlled sequence. In each case the selected
4021
- element(s) must exist.
4022
 
4023
  ``` cpp
4024
  valarray operator[](slice slicearr) const;
4025
  ```
4026
 
@@ -4167,30 +4496,29 @@ v0[valarray<size_t>(vi, 5)] = v1;
4167
  // v0 == valarray<char>("abCDeBgAEjklmnop", 16)
4168
  ```
4169
 
4170
  — *end example*]
4171
 
4172
- #### `valarray` unary operators <a id="valarray.unary">[[valarray.unary]]</a>
4173
 
4174
  ``` cpp
4175
  valarray operator+() const;
4176
  valarray operator-() const;
4177
  valarray operator~() const;
4178
  valarray<bool> operator!() const;
4179
  ```
4180
 
4181
- *Requires:* Each of these operators may only be instantiated for a type
4182
- `T` to which the indicated operator can be applied and for which the
4183
- indicated operator returns a value which is of type `T` (`bool` for
4184
- `operator!`) or which may be unambiguously implicitly converted to type
4185
- `T` (`bool` for `operator!`).
4186
 
4187
  *Returns:* A `valarray` whose length is `size()`. Each element of the
4188
  returned array is initialized with the result of applying the indicated
4189
  operator to the corresponding element of the array.
4190
 
4191
- #### `valarray` compound assignment <a id="valarray.cassign">[[valarray.cassign]]</a>
4192
 
4193
  ``` cpp
4194
  valarray& operator*= (const valarray& v);
4195
  valarray& operator/= (const valarray& v);
4196
  valarray& operator%= (const valarray& v);
@@ -4201,15 +4529,18 @@ valarray& operator&= (const valarray& v);
4201
  valarray& operator|= (const valarray& v);
4202
  valarray& operator<<=(const valarray& v);
4203
  valarray& operator>>=(const valarray& v);
4204
  ```
4205
 
4206
- *Requires:* `size() == v.size()`. Each of these operators may only be
4207
- instantiated for a type `T` if the indicated operator can be applied to
4208
- two operands of type `T`. The value of an element in the left-hand side
4209
- of a valarray compound assignment operator does not depend on the value
4210
- of another element in that left hand side.
 
 
 
4211
 
4212
  *Effects:* Each of these operators performs the indicated operation on
4213
  each of the elements of `*this` and the corresponding element of `v`.
4214
 
4215
  *Returns:* `*this`.
@@ -4228,24 +4559,23 @@ valarray& operator&= (const T& v);
4228
  valarray& operator|= (const T& v);
4229
  valarray& operator<<=(const T& v);
4230
  valarray& operator>>=(const T& v);
4231
  ```
4232
 
4233
- *Requires:* Each of these operators may only be instantiated for a type
4234
- `T` if the indicated operator can be applied to two operands of type
4235
- `T`.
4236
 
4237
  *Effects:* Each of these operators applies the indicated operation to
4238
  each element of `*this` and `v`.
4239
 
4240
  *Returns:* `*this`
4241
 
4242
  *Remarks:* The appearance of an array on the left-hand side of a
4243
  compound assignment does not invalidate references or pointers to the
4244
  elements of the array.
4245
 
4246
- #### `valarray` member functions <a id="valarray.members">[[valarray.members]]</a>
4247
 
4248
  ``` cpp
4249
  void swap(valarray& v) noexcept;
4250
  ```
4251
 
@@ -4264,33 +4594,34 @@ size_t size() const;
4264
 
4265
  ``` cpp
4266
  T sum() const;
4267
  ```
4268
 
4269
- *Requires:* `size() > 0`. This function may only be instantiated for a
4270
- type `T` to which `operator+=` can be applied.
 
4271
 
4272
  *Returns:* The sum of all the elements of the array. If the array has
4273
  length 1, returns the value of element 0. Otherwise, the returned value
4274
  is calculated by applying `operator+=` to a copy of an element of the
4275
  array and all other elements of the array in an unspecified order.
4276
 
4277
  ``` cpp
4278
  T min() const;
4279
  ```
4280
 
4281
- *Requires:* `size() > 0`
4282
 
4283
  *Returns:* The minimum value contained in `*this`. For an array of
4284
  length 1, the value of element 0 is returned. For all other array
4285
  lengths, the determination is made using `operator<`.
4286
 
4287
  ``` cpp
4288
  T max() const;
4289
  ```
4290
 
4291
- *Requires:* `size() > 0`.
4292
 
4293
  *Returns:* The maximum value contained in `*this`. For an array of
4294
  length 1, the value of element 0 is returned. For all other array
4295
  lengths, the determination is made using `operator<`.
4296
 
@@ -4305,13 +4636,13 @@ is `(*this)[`*`I`*` + n]` if *`I`*` + n` is non-negative and less than
4305
  [*Note 1*: If element zero is taken as the leftmost element, a positive
4306
  value of `n` shifts the elements left `n` places, with zero
4307
  fill. — *end note*]
4308
 
4309
  [*Example 1*: If the argument has the value -2, the first two elements
4310
- of the result will be value-initialized ([[dcl.init]]); the third
4311
- element of the result will be assigned the value of the first element of
4312
- the argument; etc. — *end example*]
4313
 
4314
  ``` cpp
4315
  valarray cshift(int n) const;
4316
  ```
4317
 
@@ -4337,183 +4668,197 @@ void resize(size_t sz, T c = T());
4337
  assigns to each element the value of the second argument. Resizing
4338
  invalidates all pointers and references to elements in the array.
4339
 
4340
  ### `valarray` non-member operations <a id="valarray.nonmembers">[[valarray.nonmembers]]</a>
4341
 
4342
- #### `valarray` binary operators <a id="valarray.binary">[[valarray.binary]]</a>
4343
 
4344
  ``` cpp
4345
- template<class T> valarray<T> operator*
4346
- (const valarray<T>&, const valarray<T>&);
4347
- template<class T> valarray<T> operator/
4348
- (const valarray<T>&, const valarray<T>&);
4349
- template<class T> valarray<T> operator%
4350
- (const valarray<T>&, const valarray<T>&);
4351
- template<class T> valarray<T> operator+
4352
- (const valarray<T>&, const valarray<T>&);
4353
- template<class T> valarray<T> operator-
4354
- (const valarray<T>&, const valarray<T>&);
4355
- template<class T> valarray<T> operator^
4356
- (const valarray<T>&, const valarray<T>&);
4357
- template<class T> valarray<T> operator&
4358
- (const valarray<T>&, const valarray<T>&);
4359
- template<class T> valarray<T> operator|
4360
- (const valarray<T>&, const valarray<T>&);
4361
- template<class T> valarray<T> operator<<
4362
- (const valarray<T>&, const valarray<T>&);
4363
- template<class T> valarray<T> operator>>
4364
- (const valarray<T>&, const valarray<T>&);
4365
  ```
4366
 
4367
- *Requires:* Each of these operators may only be instantiated for a type
4368
- `T` to which the indicated operator can be applied and for which the
4369
- indicated operator returns a value which is of type `T` or which can be
4370
- unambiguously implicitly converted to type `T`. The argument arrays have
4371
- the same length.
4372
 
4373
  *Returns:* A `valarray` whose length is equal to the lengths of the
4374
  argument arrays. Each element of the returned array is initialized with
4375
  the result of applying the indicated operator to the corresponding
4376
  elements of the argument arrays.
4377
 
4378
  ``` cpp
4379
- template<class T> valarray<T> operator* (const valarray<T>&, const T&);
4380
- template<class T> valarray<T> operator* (const T&, const valarray<T>&);
4381
- template<class T> valarray<T> operator/ (const valarray<T>&, const T&);
4382
- template<class T> valarray<T> operator/ (const T&, const valarray<T>&);
4383
- template<class T> valarray<T> operator% (const valarray<T>&, const T&);
4384
- template<class T> valarray<T> operator% (const T&, const valarray<T>&);
4385
- template<class T> valarray<T> operator+ (const valarray<T>&, const T&);
4386
- template<class T> valarray<T> operator+ (const T&, const valarray<T>&);
4387
- template<class T> valarray<T> operator- (const valarray<T>&, const T&);
4388
- template<class T> valarray<T> operator- (const T&, const valarray<T>&);
4389
- template<class T> valarray<T> operator^ (const valarray<T>&, const T&);
4390
- template<class T> valarray<T> operator^ (const T&, const valarray<T>&);
4391
- template<class T> valarray<T> operator& (const valarray<T>&, const T&);
4392
- template<class T> valarray<T> operator& (const T&, const valarray<T>&);
4393
- template<class T> valarray<T> operator| (const valarray<T>&, const T&);
4394
- template<class T> valarray<T> operator| (const T&, const valarray<T>&);
4395
- template<class T> valarray<T> operator<<(const valarray<T>&, const T&);
4396
- template<class T> valarray<T> operator<<(const T&, const valarray<T>&);
4397
- template<class T> valarray<T> operator>>(const valarray<T>&, const T&);
4398
- template<class T> valarray<T> operator>>(const T&, const valarray<T>&);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4399
  ```
4400
 
4401
- *Requires:* Each of these operators may only be instantiated for a type
4402
- `T` to which the indicated operator can be applied and for which the
4403
- indicated operator returns a value which is of type `T` or which can be
4404
- unambiguously implicitly converted to type `T`.
4405
 
4406
  *Returns:* A `valarray` whose length is equal to the length of the array
4407
  argument. Each element of the returned array is initialized with the
4408
  result of applying the indicated operator to the corresponding element
4409
  of the array argument and the non-array argument.
4410
 
4411
- #### `valarray` logical operators <a id="valarray.comparison">[[valarray.comparison]]</a>
4412
 
4413
  ``` cpp
4414
- template<class T> valarray<bool> operator==
4415
- (const valarray<T>&, const valarray<T>&);
4416
- template<class T> valarray<bool> operator!=
4417
- (const valarray<T>&, const valarray<T>&);
4418
- template<class T> valarray<bool> operator<
4419
- (const valarray<T>&, const valarray<T>&);
4420
- template<class T> valarray<bool> operator>
4421
- (const valarray<T>&, const valarray<T>&);
4422
- template<class T> valarray<bool> operator<=
4423
- (const valarray<T>&, const valarray<T>&);
4424
- template<class T> valarray<bool> operator>=
4425
- (const valarray<T>&, const valarray<T>&);
4426
- template<class T> valarray<bool> operator&&
4427
- (const valarray<T>&, const valarray<T>&);
4428
- template<class T> valarray<bool> operator||
4429
- (const valarray<T>&, const valarray<T>&);
4430
  ```
4431
 
4432
- *Requires:* Each of these operators may only be instantiated for a type
4433
- `T` to which the indicated operator can be applied and for which the
4434
- indicated operator returns a value which is of type `bool` or which can
4435
- be unambiguously implicitly converted to type `bool`. The two array
4436
- arguments have the same length.
4437
 
4438
  *Returns:* A `valarray<bool>` whose length is equal to the length of the
4439
  array arguments. Each element of the returned array is initialized with
4440
  the result of applying the indicated operator to the corresponding
4441
  elements of the argument arrays.
4442
 
4443
  ``` cpp
4444
- template<class T> valarray<bool> operator==(const valarray<T>&, const T&);
4445
- template<class T> valarray<bool> operator==(const T&, const valarray<T>&);
4446
- template<class T> valarray<bool> operator!=(const valarray<T>&, const T&);
4447
- template<class T> valarray<bool> operator!=(const T&, const valarray<T>&);
4448
- template<class T> valarray<bool> operator< (const valarray<T>&, const T&);
4449
- template<class T> valarray<bool> operator< (const T&, const valarray<T>&);
4450
- template<class T> valarray<bool> operator> (const valarray<T>&, const T&);
4451
- template<class T> valarray<bool> operator> (const T&, const valarray<T>&);
4452
- template<class T> valarray<bool> operator<=(const valarray<T>&, const T&);
4453
- template<class T> valarray<bool> operator<=(const T&, const valarray<T>&);
4454
- template<class T> valarray<bool> operator>=(const valarray<T>&, const T&);
4455
- template<class T> valarray<bool> operator>=(const T&, const valarray<T>&);
4456
- template<class T> valarray<bool> operator&&(const valarray<T>&, const T&);
4457
- template<class T> valarray<bool> operator&&(const T&, const valarray<T>&);
4458
- template<class T> valarray<bool> operator||(const valarray<T>&, const T&);
4459
- template<class T> valarray<bool> operator||(const T&, const valarray<T>&);
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4460
  ```
4461
 
4462
- *Requires:* Each of these operators may only be instantiated for a type
4463
- `T` to which the indicated operator can be applied and for which the
4464
- indicated operator returns a value which is of type `bool` or which can
4465
- be unambiguously implicitly converted to type `bool`.
4466
 
4467
  *Returns:* A `valarray<bool>` whose length is equal to the length of the
4468
  array argument. Each element of the returned array is initialized with
4469
  the result of applying the indicated operator to the corresponding
4470
  element of the array and the non-array argument.
4471
 
4472
- #### `valarray` transcendentals <a id="valarray.transcend">[[valarray.transcend]]</a>
4473
 
4474
  ``` cpp
4475
  template<class T> valarray<T> abs (const valarray<T>&);
4476
  template<class T> valarray<T> acos (const valarray<T>&);
4477
  template<class T> valarray<T> asin (const valarray<T>&);
4478
  template<class T> valarray<T> atan (const valarray<T>&);
4479
- template<class T> valarray<T> atan2
4480
- (const valarray<T>&, const valarray<T>&);
4481
- template<class T> valarray<T> atan2(const valarray<T>&, const T&);
4482
- template<class T> valarray<T> atan2(const T&, const valarray<T>&);
4483
  template<class T> valarray<T> cos (const valarray<T>&);
4484
  template<class T> valarray<T> cosh (const valarray<T>&);
4485
  template<class T> valarray<T> exp (const valarray<T>&);
4486
  template<class T> valarray<T> log (const valarray<T>&);
4487
  template<class T> valarray<T> log10(const valarray<T>&);
4488
- template<class T> valarray<T> pow
4489
- (const valarray<T>&, const valarray<T>&);
4490
- template<class T> valarray<T> pow (const valarray<T>&, const T&);
4491
- template<class T> valarray<T> pow (const T&, const valarray<T>&);
4492
  template<class T> valarray<T> sin (const valarray<T>&);
4493
  template<class T> valarray<T> sinh (const valarray<T>&);
4494
  template<class T> valarray<T> sqrt (const valarray<T>&);
4495
  template<class T> valarray<T> tan (const valarray<T>&);
4496
  template<class T> valarray<T> tanh (const valarray<T>&);
4497
  ```
4498
 
4499
- *Requires:* Each of these functions may only be instantiated for a type
4500
- `T` to which a unique function with the indicated name can be applied
4501
- (unqualified). This function shall return a value which is of type `T`
4502
- or which can be unambiguously implicitly converted to type `T`.
4503
 
4504
- #### `valarray` specialized algorithms <a id="valarray.special">[[valarray.special]]</a>
4505
 
4506
  ``` cpp
4507
  template<class T> void swap(valarray<T>& x, valarray<T>& y) noexcept;
4508
  ```
4509
 
4510
  *Effects:* Equivalent to `x.swap(y)`.
4511
 
4512
  ### Class `slice` <a id="class.slice">[[class.slice]]</a>
4513
 
4514
- #### Class `slice` overview <a id="class.slice.overview">[[class.slice.overview]]</a>
4515
 
4516
  ``` cpp
4517
  namespace std {
4518
  class slice {
4519
  public:
@@ -4521,18 +4866,20 @@ namespace std {
4521
  slice(size_t, size_t, size_t);
4522
 
4523
  size_t start() const;
4524
  size_t size() const;
4525
  size_t stride() const;
 
 
4526
  };
4527
  }
4528
  ```
4529
 
4530
  The `slice` class represents a BLAS-like slice from an array. Such a
4531
  slice is specified by a starting index, a length, and a stride.[^12]
4532
 
4533
- #### `slice` constructors <a id="cons.slice">[[cons.slice]]</a>
4534
 
4535
  ``` cpp
4536
  slice();
4537
  slice(size_t start, size_t length, size_t stride);
4538
  slice(const slice&);
@@ -4542,13 +4889,13 @@ The default constructor is equivalent to `slice(0, 0, 0)`. A default
4542
  constructor is provided only to permit the declaration of arrays of
4543
  slices. The constructor with arguments for a slice takes a start,
4544
  length, and stride parameter.
4545
 
4546
  [*Example 1*: `slice(3, 8, 2)` constructs a slice which selects
4547
- elements 3, 5, 7, ... 17 from an array. — *end example*]
4548
 
4549
- #### `slice` access functions <a id="slice.access">[[slice.access]]</a>
4550
 
4551
  ``` cpp
4552
  size_t start() const;
4553
  size_t size() const;
4554
  size_t stride() const;
@@ -4556,13 +4903,25 @@ size_t stride() const;
4556
 
4557
  *Returns:* The start, length, or stride specified by a `slice` object.
4558
 
4559
  *Complexity:* Constant time.
4560
 
 
 
 
 
 
 
 
 
 
 
 
 
4561
  ### Class template `slice_array` <a id="template.slice.array">[[template.slice.array]]</a>
4562
 
4563
- #### Class template `slice_array` overview <a id="template.slice.array.overview">[[template.slice.array.overview]]</a>
4564
 
4565
  ``` cpp
4566
  namespace std {
4567
  template<class T> class slice_array {
4568
  public:
@@ -4588,37 +4947,37 @@ namespace std {
4588
  slice_array() = delete; // as implied by declaring copy constructor above
4589
  };
4590
  }
4591
  ```
4592
 
4593
- The `slice_array` template is a helper template used by the `slice`
4594
- subscript operator
4595
 
4596
  ``` cpp
4597
  slice_array<T> valarray<T>::operator[](slice);
4598
  ```
4599
 
4600
  It has reference semantics to a subset of an array specified by a
4601
  `slice` object.
4602
 
4603
  [*Example 1*: The expression `a[slice(1, 5, 3)] = b;` has the effect of
4604
  assigning the elements of `b` to a slice of the elements in `a`. For the
4605
- slice shown, the elements selected from `a` are 1, 4, ...,
4606
- 13. — *end example*]
4607
 
4608
- #### `slice_array` assignment <a id="slice.arr.assign">[[slice.arr.assign]]</a>
4609
 
4610
  ``` cpp
4611
  void operator=(const valarray<T>&) const;
4612
  const slice_array& operator=(const slice_array&) const;
4613
  ```
4614
 
4615
  These assignment operators have reference semantics, assigning the
4616
  values of the argument array elements to selected elements of the
4617
  `valarray<T>` object to which the `slice_array` object refers.
4618
 
4619
- #### `slice_array` compound assignment <a id="slice.arr.comp.assign">[[slice.arr.comp.assign]]</a>
4620
 
4621
  ``` cpp
4622
  void operator*= (const valarray<T>&) const;
4623
  void operator/= (const valarray<T>&) const;
4624
  void operator%= (const valarray<T>&) const;
@@ -4634,11 +4993,11 @@ void operator>>=(const valarray<T>&) const;
4634
  These compound assignments have reference semantics, applying the
4635
  indicated operation to the elements of the argument array and selected
4636
  elements of the `valarray<T>` object to which the `slice_array` object
4637
  refers.
4638
 
4639
- #### `slice_array` fill function <a id="slice.arr.fill">[[slice.arr.fill]]</a>
4640
 
4641
  ``` cpp
4642
  void operator=(const T&) const;
4643
  ```
4644
 
@@ -4646,11 +5005,11 @@ This function has reference semantics, assigning the value of its
4646
  argument to the elements of the `valarray<T>` object to which the
4647
  `slice_array` object refers.
4648
 
4649
  ### The `gslice` class <a id="class.gslice">[[class.gslice]]</a>
4650
 
4651
- #### The `gslice` class overview <a id="class.gslice.overview">[[class.gslice.overview]]</a>
4652
 
4653
  ``` cpp
4654
  namespace std {
4655
  class gslice {
4656
  public:
@@ -4704,11 +5063,11 @@ If the stride parameters in the previous example are changed to {1, 1,
4704
  — *end example*]
4705
 
4706
  If a degenerate slice is used as the argument to the non-`const` version
4707
  of `operator[](const gslice&)`, the behavior is undefined.
4708
 
4709
- #### `gslice` constructors <a id="gslice.cons">[[gslice.cons]]</a>
4710
 
4711
  ``` cpp
4712
  gslice();
4713
  gslice(size_t start, const valarray<size_t>& lengths,
4714
  const valarray<size_t>& strides);
@@ -4716,13 +5075,13 @@ gslice(const gslice&);
4716
  ```
4717
 
4718
  The default constructor is equivalent to
4719
  `gslice(0, valarray<size_t>(), valarray<size_t>())`. The constructor
4720
  with arguments builds a `gslice` based on a specification of start,
4721
- lengths, and strides, as explained in the previous section.
4722
 
4723
- #### `gslice` access functions <a id="gslice.access">[[gslice.access]]</a>
4724
 
4725
  ``` cpp
4726
  size_t start() const;
4727
  valarray<size_t> size() const;
4728
  valarray<size_t> stride() const;
@@ -4734,11 +5093,11 @@ specified for the `gslice`.
4734
  *Complexity:* `start()` is constant time. `size()` and `stride()` are
4735
  linear in the number of strides.
4736
 
4737
  ### Class template `gslice_array` <a id="template.gslice.array">[[template.gslice.array]]</a>
4738
 
4739
- #### Class template `gslice_array` overview <a id="template.gslice.array.overview">[[template.gslice.array.overview]]</a>
4740
 
4741
  ``` cpp
4742
  namespace std {
4743
  template<class T> class gslice_array {
4744
  public:
@@ -4764,36 +5123,34 @@ namespace std {
4764
  gslice_array() = delete; // as implied by declaring copy constructor above
4765
  };
4766
  }
4767
  ```
4768
 
4769
- This template is a helper template used by the `slice` subscript
4770
  operator
4771
 
4772
  ``` cpp
4773
  gslice_array<T> valarray<T>::operator[](const gslice&);
4774
  ```
4775
 
4776
  It has reference semantics to a subset of an array specified by a
4777
- `gslice` object.
 
 
4778
 
4779
- Thus, the expression `a[gslice(1, length, stride)] = b` has the effect
4780
- of assigning the elements of `b` to a generalized slice of the elements
4781
- in `a`.
4782
-
4783
- #### `gslice_array` assignment <a id="gslice.array.assign">[[gslice.array.assign]]</a>
4784
 
4785
  ``` cpp
4786
  void operator=(const valarray<T>&) const;
4787
  const gslice_array& operator=(const gslice_array&) const;
4788
  ```
4789
 
4790
  These assignment operators have reference semantics, assigning the
4791
  values of the argument array elements to selected elements of the
4792
  `valarray<T>` object to which the `gslice_array` refers.
4793
 
4794
- #### `gslice_array` compound assignment <a id="gslice.array.comp.assign">[[gslice.array.comp.assign]]</a>
4795
 
4796
  ``` cpp
4797
  void operator*= (const valarray<T>&) const;
4798
  void operator/= (const valarray<T>&) const;
4799
  void operator%= (const valarray<T>&) const;
@@ -4809,11 +5166,11 @@ void operator>>=(const valarray<T>&) const;
4809
  These compound assignments have reference semantics, applying the
4810
  indicated operation to the elements of the argument array and selected
4811
  elements of the `valarray<T>` object to which the `gslice_array` object
4812
  refers.
4813
 
4814
- #### `gslice_array` fill function <a id="gslice.array.fill">[[gslice.array.fill]]</a>
4815
 
4816
  ``` cpp
4817
  void operator=(const T&) const;
4818
  ```
4819
 
@@ -4821,11 +5178,11 @@ This function has reference semantics, assigning the value of its
4821
  argument to the elements of the `valarray<T>` object to which the
4822
  `gslice_array` object refers.
4823
 
4824
  ### Class template `mask_array` <a id="template.mask.array">[[template.mask.array]]</a>
4825
 
4826
- #### Class template `mask_array` overview <a id="template.mask.array.overview">[[template.mask.array.overview]]</a>
4827
 
4828
  ``` cpp
4829
  namespace std {
4830
  template<class T> class mask_array {
4831
  public:
@@ -4860,24 +5217,24 @@ mask_array<T> valarray<T>::operator[](const valarray<bool>&).
4860
  ```
4861
 
4862
  It has reference semantics to a subset of an array specified by a
4863
  boolean mask. Thus, the expression `a[mask] = b;` has the effect of
4864
  assigning the elements of `b` to the masked elements in `a` (those for
4865
- which the corresponding element in `mask` is `true`.)
4866
 
4867
- #### `mask_array` assignment <a id="mask.array.assign">[[mask.array.assign]]</a>
4868
 
4869
  ``` cpp
4870
  void operator=(const valarray<T>&) const;
4871
  const mask_array& operator=(const mask_array&) const;
4872
  ```
4873
 
4874
  These assignment operators have reference semantics, assigning the
4875
  values of the argument array elements to selected elements of the
4876
  `valarray<T>` object to which it refers.
4877
 
4878
- #### `mask_array` compound assignment <a id="mask.array.comp.assign">[[mask.array.comp.assign]]</a>
4879
 
4880
  ``` cpp
4881
  void operator*= (const valarray<T>&) const;
4882
  void operator/= (const valarray<T>&) const;
4883
  void operator%= (const valarray<T>&) const;
@@ -4892,11 +5249,11 @@ void operator>>=(const valarray<T>&) const;
4892
 
4893
  These compound assignments have reference semantics, applying the
4894
  indicated operation to the elements of the argument array and selected
4895
  elements of the `valarray<T>` object to which the mask object refers.
4896
 
4897
- #### `mask_array` fill function <a id="mask.array.fill">[[mask.array.fill]]</a>
4898
 
4899
  ``` cpp
4900
  void operator=(const T&) const;
4901
  ```
4902
 
@@ -4904,11 +5261,11 @@ This function has reference semantics, assigning the value of its
4904
  argument to the elements of the `valarray<T>` object to which the
4905
  `mask_array` object refers.
4906
 
4907
  ### Class template `indirect_array` <a id="template.indirect.array">[[template.indirect.array]]</a>
4908
 
4909
- #### Class template `indirect_array` overview <a id="template.indirect.array.overview">[[template.indirect.array.overview]]</a>
4910
 
4911
  ``` cpp
4912
  namespace std {
4913
  template<class T> class indirect_array {
4914
  public:
@@ -4942,15 +5299,15 @@ operator
4942
  ``` cpp
4943
  indirect_array<T> valarray<T>::operator[](const valarray<size_t>&).
4944
  ```
4945
 
4946
  It has reference semantics to a subset of an array specified by an
4947
- `indirect_array`. Thus the expression `a[indirect] = b;` has the effect
4948
- of assigning the elements of `b` to the elements in `a` whose indices
4949
- appear in `indirect`.
4950
 
4951
- #### `indirect_array` assignment <a id="indirect.array.assign">[[indirect.array.assign]]</a>
4952
 
4953
  ``` cpp
4954
  void operator=(const valarray<T>&) const;
4955
  const indirect_array& operator=(const indirect_array&) const;
4956
  ```
@@ -4974,11 +5331,11 @@ a[indirect] = b;
4974
  results in undefined behavior since element 4 is specified twice in the
4975
  indirection.
4976
 
4977
  — *end example*]
4978
 
4979
- #### `indirect_array` compound assignment <a id="indirect.array.comp.assign">[[indirect.array.comp.assign]]</a>
4980
 
4981
  ``` cpp
4982
  void operator*= (const valarray<T>&) const;
4983
  void operator/= (const valarray<T>&) const;
4984
  void operator%= (const valarray<T>&) const;
@@ -4997,11 +5354,11 @@ elements of the `valarray<T>` object to which the `indirect_array`
4997
  object refers.
4998
 
4999
  If the `indirect_array` specifies an element in the `valarray<T>` object
5000
  to which it refers more than once, the behavior is undefined.
5001
 
5002
- #### `indirect_array` fill function <a id="indirect.array.fill">[[indirect.array.fill]]</a>
5003
 
5004
  ``` cpp
5005
  void operator=(const T&) const;
5006
  ```
5007
 
@@ -5010,22 +5367,22 @@ argument to the elements of the `valarray<T>` object to which the
5010
  `indirect_array` object refers.
5011
 
5012
  ### `valarray` range access <a id="valarray.range">[[valarray.range]]</a>
5013
 
5014
  In the `begin` and `end` function templates that follow, *unspecified*1
5015
- is a type that meets the requirements of a mutable random access
5016
- iterator ([[random.access.iterators]]) and of a contiguous iterator (
5017
- [[iterator.requirements.general]]) whose `value_type` is the template
5018
- parameter `T` and whose `reference` type is `T&`. *unspecified*2 is a
5019
- type that meets the requirements of a constant random access iterator (
5020
- [[random.access.iterators]]) and of a contiguous iterator (
5021
- [[iterator.requirements.general]]) whose `value_type` is the template
5022
- parameter `T` and whose `reference` type is `const T&`.
5023
 
5024
  The iterators returned by `begin` and `end` for an array are guaranteed
5025
- to be valid until the member function `resize(size_t, T)` (
5026
- [[valarray.members]]) is called for that array or until the lifetime of
5027
  that array ends, whichever happens first.
5028
 
5029
  ``` cpp
5030
  template<class T> unspecified{1} begin(valarray<T>& v);
5031
  template<class T> unspecified{2} begin(const valarray<T>& v);
@@ -5038,950 +5395,10 @@ template <class T> unspecified{1} end(valarray<T>& v);
5038
  template<class T> unspecified{2} end(const valarray<T>& v);
5039
  ```
5040
 
5041
  *Returns:* An iterator referencing one past the last value in the array.
5042
 
5043
- ## Generalized numeric operations <a id="numeric.ops">[[numeric.ops]]</a>
5044
-
5045
- ### Header `<numeric>` synopsis <a id="numeric.ops.overview">[[numeric.ops.overview]]</a>
5046
-
5047
- ``` cpp
5048
- namespace std {
5049
- // [accumulate], accumulate
5050
- template <class InputIterator, class T>
5051
- T accumulate(InputIterator first, InputIterator last, T init);
5052
- template <class InputIterator, class T, class BinaryOperation>
5053
- T accumulate(InputIterator first, InputIterator last, T init,
5054
- BinaryOperation binary_op);
5055
-
5056
- // [reduce], reduce
5057
- template<class InputIterator>
5058
- typename iterator_traits<InputIterator>::value_type
5059
- reduce(InputIterator first, InputIterator last);
5060
- template<class InputIterator, class T>
5061
- T reduce(InputIterator first, InputIterator last, T init);
5062
- template<class InputIterator, class T, class BinaryOperation>
5063
- T reduce(InputIterator first, InputIterator last, T init,
5064
- BinaryOperation binary_op);
5065
- template<class ExecutionPolicy, class ForwardIterator>
5066
- typename iterator_traits<ForwardIterator>::value_type
5067
- reduce(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5068
- ForwardIterator first, ForwardIterator last);
5069
- template<class ExecutionPolicy, class ForwardIterator, class T>
5070
- T reduce(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5071
- ForwardIterator first, ForwardIterator last, T init);
5072
- template<class ExecutionPolicy, class ForwardIterator, class T, class BinaryOperation>
5073
- T reduce(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5074
- ForwardIterator first, ForwardIterator last, T init,
5075
- BinaryOperation binary_op);
5076
-
5077
- // [inner.product], inner product
5078
- template <class InputIterator1, class InputIterator2, class T>
5079
- T inner_product(InputIterator1 first1, InputIterator1 last1,
5080
- InputIterator2 first2, T init);
5081
- template <class InputIterator1, class InputIterator2, class T,
5082
- class BinaryOperation1, class BinaryOperation2>
5083
- T inner_product(InputIterator1 first1, InputIterator1 last1,
5084
- InputIterator2 first2, T init,
5085
- BinaryOperation1 binary_op1,
5086
- BinaryOperation2 binary_op2);
5087
-
5088
- // [transform.reduce], transform reduce
5089
- template<class InputIterator1, class InputIterator2, class T>
5090
- T transform_reduce(InputIterator1 first1, InputIterator1 last1,
5091
- InputIterator2 first2,
5092
- T init);
5093
- template<class InputIterator1, class InputIterator2, class T,
5094
- class BinaryOperation1, class BinaryOperation2>
5095
- T transform_reduce(InputIterator1 first1, InputIterator1 last1,
5096
- InputIterator2 first2,
5097
- T init,
5098
- BinaryOperation1 binary_op1,
5099
- BinaryOperation2 binary_op2);
5100
- template<class InputIterator, class T,
5101
- class BinaryOperation, class UnaryOperation>
5102
- T transform_reduce(InputIterator first, InputIterator last,
5103
- T init,
5104
- BinaryOperation binary_op, UnaryOperation unary_op);
5105
- template<class ExecutionPolicy,
5106
- class ForwardIterator1, class ForwardIterator2, class T>
5107
- T transform_reduce(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5108
- ForwardIterator1 first1, ForwardIterator1 last1,
5109
- ForwardIterator2 first2,
5110
- T init);
5111
- template<class ExecutionPolicy,
5112
- class ForwardIterator1, class ForwardIterator2, class T,
5113
- class BinaryOperation1, class BinaryOperation2>
5114
- T transform_reduce(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5115
- ForwardIterator1 first1, ForwardIterator1 last1,
5116
- ForwardIterator2 first2,
5117
- T init,
5118
- BinaryOperation1 binary_op1,
5119
- BinaryOperation2 binary_op2);
5120
- template<class ExecutionPolicy,
5121
- class ForwardIterator, class T,
5122
- class BinaryOperation, class UnaryOperation>
5123
- T transform_reduce(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5124
- ForwardIterator first, ForwardIterator last,
5125
- T init,
5126
- BinaryOperation binary_op, UnaryOperation unary_op);
5127
-
5128
- // [partial.sum], partial sum
5129
- template <class InputIterator, class OutputIterator>
5130
- OutputIterator partial_sum(InputIterator first,
5131
- InputIterator last,
5132
- OutputIterator result);
5133
- template <class InputIterator, class OutputIterator, class BinaryOperation>
5134
- OutputIterator partial_sum(InputIterator first,
5135
- InputIterator last,
5136
- OutputIterator result,
5137
- BinaryOperation binary_op);
5138
-
5139
- // [exclusive.scan], exclusive scan
5140
- template<class InputIterator, class OutputIterator, class T>
5141
- OutputIterator exclusive_scan(InputIterator first, InputIterator last,
5142
- OutputIterator result,
5143
- T init);
5144
- template<class InputIterator, class OutputIterator, class T, class BinaryOperation>
5145
- OutputIterator exclusive_scan(InputIterator first, InputIterator last,
5146
- OutputIterator result,
5147
- T init, BinaryOperation binary_op);
5148
- template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class T>
5149
- ForwardIterator2 exclusive_scan(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5150
- ForwardIterator1 first, ForwardIterator1 last,
5151
- ForwardIterator2 result,
5152
- T init);
5153
- template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class T,
5154
- class BinaryOperation>
5155
- ForwardIterator2 exclusive_scan(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5156
- ForwardIterator1 first, ForwardIterator1 last,
5157
- ForwardIterator2 result,
5158
- T init, BinaryOperation binary_op);
5159
-
5160
- // [inclusive.scan], inclusive scan
5161
- template<class InputIterator, class OutputIterator>
5162
- OutputIterator inclusive_scan(InputIterator first, InputIterator last,
5163
- OutputIterator result);
5164
- template<class InputIterator, class OutputIterator, class BinaryOperation>
5165
- OutputIterator inclusive_scan(InputIterator first, InputIterator last,
5166
- OutputIterator result,
5167
- BinaryOperation binary_op);
5168
- template<class InputIterator, class OutputIterator, class BinaryOperation, class T>
5169
- OutputIterator inclusive_scan(InputIterator first, InputIterator last,
5170
- OutputIterator result,
5171
- BinaryOperation binary_op, T init);
5172
- template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
5173
- ForwardIterator2 inclusive_scan(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5174
- ForwardIterator1 first, ForwardIterator1 last,
5175
- ForwardIterator2 result);
5176
- template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
5177
- class BinaryOperation>
5178
- ForwardIterator2 inclusive_scan(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5179
- ForwardIterator1 first, ForwardIterator1 last,
5180
- ForwardIterator2 result,
5181
- BinaryOperation binary_op);
5182
- template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
5183
- class BinaryOperation, class T>
5184
- ForwardIterator2 inclusive_scan(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5185
- ForwardIterator1 first, ForwardIterator1 last,
5186
- ForwardIterator2 result,
5187
- BinaryOperation binary_op, T init);
5188
-
5189
- // [transform.exclusive.scan], transform exclusive scan
5190
- template<class InputIterator, class OutputIterator, class T,
5191
- class BinaryOperation, class UnaryOperation>
5192
- OutputIterator transform_exclusive_scan(InputIterator first, InputIterator last,
5193
- OutputIterator result,
5194
- T init,
5195
- BinaryOperation binary_op,
5196
- UnaryOperation unary_op);
5197
- template<class ExecutionPolicy,
5198
- class ForwardIterator1, class ForwardIterator2, class T,
5199
- class BinaryOperation, class UnaryOperation>
5200
- ForwardIterator2 transform_exclusive_scan(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5201
- ForwardIterator1 first, ForwardIterator1 last,
5202
- ForwardIterator2 result,
5203
- T init,
5204
- BinaryOperation binary_op,
5205
- UnaryOperation unary_op);
5206
-
5207
- // [transform.inclusive.scan], transform inclusive scan
5208
- template<class InputIterator, class OutputIterator,
5209
- class BinaryOperation, class UnaryOperation>
5210
- OutputIterator transform_inclusive_scan(InputIterator first, InputIterator last,
5211
- OutputIterator result,
5212
- BinaryOperation binary_op,
5213
- UnaryOperation unary_op);
5214
- template<class InputIterator, class OutputIterator,
5215
- class BinaryOperation, class UnaryOperation, class T>
5216
- OutputIterator transform_inclusive_scan(InputIterator first, InputIterator last,
5217
- OutputIterator result,
5218
- BinaryOperation binary_op,
5219
- UnaryOperation unary_op,
5220
- T init);
5221
- template<class ExecutionPolicy,
5222
- class ForwardIterator1, class ForwardIterator2,
5223
- class BinaryOperation, class UnaryOperation>
5224
- ForwardIterator2 transform_inclusive_scan(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5225
- ForwardIterator1 first, ForwardIterator1 last,
5226
- ForwardIterator2 result,
5227
- BinaryOperation binary_op,
5228
- UnaryOperation unary_op);
5229
- template<class ExecutionPolicy,
5230
- class ForwardIterator1, class ForwardIterator2,
5231
- class BinaryOperation, class UnaryOperation, class T>
5232
- ForwardIterator2 transform_inclusive_scan(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5233
- ForwardIterator1 first, ForwardIterator1 last,
5234
- ForwardIterator2 result,
5235
- BinaryOperation binary_op,
5236
- UnaryOperation unary_op,
5237
- T init);
5238
-
5239
- // [adjacent.difference], adjacent difference
5240
- template <class InputIterator, class OutputIterator>
5241
- OutputIterator adjacent_difference(InputIterator first,
5242
- InputIterator last,
5243
- OutputIterator result);
5244
- template <class InputIterator, class OutputIterator, class BinaryOperation>
5245
- OutputIterator adjacent_difference(InputIterator first,
5246
- InputIterator last,
5247
- OutputIterator result,
5248
- BinaryOperation binary_op);
5249
- template <class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
5250
- ForwardIterator2 adjacent_difference(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5251
- ForwardIterator1 first,
5252
- ForwardIterator1 last,
5253
- ForwardIterator2 result);
5254
- template <class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
5255
- class BinaryOperation>
5256
- ForwardIterator2 adjacent_difference(ExecutionPolicy&& exec, // see [algorithms.parallel.overloads]
5257
- ForwardIterator1 first,
5258
- ForwardIterator1 last,
5259
- ForwardIterator2 result,
5260
- BinaryOperation binary_op);
5261
-
5262
- // [numeric.iota], iota
5263
- template <class ForwardIterator, class T>
5264
- void iota(ForwardIterator first, ForwardIterator last, T value);
5265
-
5266
- // [numeric.ops.gcd], greatest common divisor
5267
- template <class M, class N>
5268
- constexpr common_type_t<M,N> gcd(M m, N n);
5269
-
5270
- // [numeric.ops.lcm], least common multiple
5271
- template <class M, class N>
5272
- constexpr common_type_t<M,N> lcm(M m, N n);
5273
- }
5274
- ```
5275
-
5276
- The requirements on the types of algorithms’ arguments that are
5277
- described in the introduction to Clause  [[algorithms]] also apply to
5278
- the following algorithms.
5279
-
5280
- Throughout this subclause, the parameters `UnaryOperation`,
5281
- `BinaryOperation`, `BinaryOperation1`, and `BinaryOperation2` are used
5282
- whenever an algorithm expects a function object ([[function.objects]]).
5283
-
5284
- [*Note 1*: The use of closed ranges as well as semi-open ranges to
5285
- specify requirements throughout this subclause is
5286
- intentional. — *end note*]
5287
-
5288
- ### Accumulate <a id="accumulate">[[accumulate]]</a>
5289
-
5290
- ``` cpp
5291
- template <class InputIterator, class T>
5292
- T accumulate(InputIterator first, InputIterator last, T init);
5293
- template <class InputIterator, class T, class BinaryOperation>
5294
- T accumulate(InputIterator first, InputIterator last, T init,
5295
- BinaryOperation binary_op);
5296
- ```
5297
-
5298
- *Requires:* `T` shall meet the requirements of `CopyConstructible`
5299
- (Table  [[tab:copyconstructible]]) and `CopyAssignable`
5300
- (Table  [[tab:copyassignable]]) types. In the range \[`first`, `last`\],
5301
- `binary_op` shall neither modify elements nor invalidate iterators or
5302
- subranges.[^13]
5303
-
5304
- *Effects:* Computes its result by initializing the accumulator `acc`
5305
- with the initial value `init` and then modifies it with `acc = acc + *i`
5306
- or `acc = binary_op(acc, *i)` for every iterator `i` in the range
5307
- \[`first`, `last`) in order.[^14]
5308
-
5309
- ### Reduce <a id="reduce">[[reduce]]</a>
5310
-
5311
- ``` cpp
5312
- template<class InputIterator>
5313
- typename iterator_traits<InputIterator>::value_type
5314
- reduce(InputIterator first, InputIterator last);
5315
- ```
5316
-
5317
- *Effects:* Equivalent to:
5318
-
5319
- ``` cpp
5320
- return reduce(first, last,
5321
- typename iterator_traits<InputIterator>::value_type{});
5322
- ```
5323
-
5324
- ``` cpp
5325
- template<class ExecutionPolicy, class ForwardIterator>
5326
- typename iterator_traits<ForwardIterator>::value_type
5327
- reduce(ExecutionPolicy&& exec,
5328
- ForwardIterator first, ForwardIterator last);
5329
- ```
5330
-
5331
- *Effects:* Equivalent to:
5332
-
5333
- ``` cpp
5334
- return reduce(std::forward<ExecutionPolicy>(exec), first, last,
5335
- typename iterator_traits<ForwardIterator>::value_type{});
5336
- ```
5337
-
5338
- ``` cpp
5339
- template<class InputIterator, class T>
5340
- T reduce(InputIterator first, InputIterator last, T init);
5341
- ```
5342
-
5343
- *Effects:* Equivalent to:
5344
-
5345
- ``` cpp
5346
- return reduce(first, last, init, plus<>());
5347
- ```
5348
-
5349
- ``` cpp
5350
- template<class ExecutionPolicy, class ForwardIterator, class T>
5351
- T reduce(ExecutionPolicy&& exec,
5352
- ForwardIterator first, ForwardIterator last, T init);
5353
- ```
5354
-
5355
- *Effects:* Equivalent to:
5356
-
5357
- ``` cpp
5358
- return reduce(std::forward<ExecutionPolicy>(exec), first, last, init, plus<>());
5359
- ```
5360
-
5361
- ``` cpp
5362
- template<class InputIterator, class T, class BinaryOperation>
5363
- T reduce(InputIterator first, InputIterator last, T init,
5364
- BinaryOperation binary_op);
5365
- template<class ExecutionPolicy, class ForwardIterator, class T, class BinaryOperation>
5366
- T reduce(ExecutionPolicy&& exec,
5367
- ForwardIterator first, ForwardIterator last, T init,
5368
- BinaryOperation binary_op);
5369
- ```
5370
-
5371
- *Requires:*
5372
-
5373
- - `T` shall be `MoveConstructible` (Table  [[tab:moveconstructible]]).
5374
- - All of `binary_op(init, *first)`, `binary_op(*first, init)`,
5375
- `binary_op(init, init)`, and `binary_op(*first, *first)` shall be
5376
- convertible to `T`.
5377
- - `binary_op` shall neither invalidate iterators or subranges, nor
5378
- modify elements in the range \[`first`, `last`\].
5379
-
5380
- *Returns:* *GENERALIZED_SUM*(binary_op, init, \*i, ...) for every `i` in
5381
- \[`first`, `last`).
5382
-
5383
- *Complexity:* 𝑂(`last - first`) applications of `binary_op`.
5384
-
5385
- [*Note 1*: The difference between `reduce` and `accumulate` is that
5386
- `reduce` applies `binary_op` in an unspecified order, which yields a
5387
- nondeterministic result for non-associative or non-commutative
5388
- `binary_op` such as floating-point addition. — *end note*]
5389
-
5390
- ### Inner product <a id="inner.product">[[inner.product]]</a>
5391
-
5392
- ``` cpp
5393
- template <class InputIterator1, class InputIterator2, class T>
5394
- T inner_product(InputIterator1 first1, InputIterator1 last1,
5395
- InputIterator2 first2, T init);
5396
- template <class InputIterator1, class InputIterator2, class T,
5397
- class BinaryOperation1, class BinaryOperation2>
5398
- T inner_product(InputIterator1 first1, InputIterator1 last1,
5399
- InputIterator2 first2, T init,
5400
- BinaryOperation1 binary_op1,
5401
- BinaryOperation2 binary_op2);
5402
- ```
5403
-
5404
- *Requires:* `T` shall meet the requirements of `CopyConstructible`
5405
- (Table  [[tab:copyconstructible]]) and `CopyAssignable`
5406
- (Table  [[tab:copyassignable]]) types. In the ranges \[`first1`,
5407
- `last1`\] and \[`first2`, `first2 + (last1 - first1)`\] `binary_op1` and
5408
- `binary_op2` shall neither modify elements nor invalidate iterators or
5409
- subranges.[^15]
5410
-
5411
- *Effects:* Computes its result by initializing the accumulator `acc`
5412
- with the initial value `init` and then modifying it with
5413
- `acc = acc + (*i1) * (*i2)` or
5414
- `acc = binary_op1(acc, binary_op2(*i1, *i2))` for every iterator `i1` in
5415
- the range \[`first1`, `last1`) and iterator `i2` in the range
5416
- \[`first2`, `first2 + (last1 - first1)`) in order.
5417
-
5418
- ### Transform reduce <a id="transform.reduce">[[transform.reduce]]</a>
5419
-
5420
- ``` cpp
5421
- template <class InputIterator1, class InputIterator2, class T>
5422
- T transform_reduce(InputIterator1 first1, InputIterator1 last1,
5423
- InputIterator2 first2,
5424
- T init);
5425
- template <class ExecutionPolicy,
5426
- class ForwardIterator1, class ForwardIterator2, class T>
5427
- T transform_reduce(ExecutionPolicy&& exec,
5428
- ForwardIterator1 first1, ForwardIterator1 last1,
5429
- ForwardIterator2 first2,
5430
- T init);
5431
- ```
5432
-
5433
- *Effects:* Equivalent to:
5434
-
5435
- ``` cpp
5436
- return transform_reduce(first1, last1, first2, init, plus<>(), multiplies<>());
5437
- ```
5438
-
5439
- ``` cpp
5440
- template <class InputIterator1, class InputIterator2, class T,
5441
- class BinaryOperation1, class BinaryOperation2>
5442
- T transform_reduce(InputIterator1 first1, InputIterator1 last1,
5443
- InputIterator2 first2,
5444
- T init,
5445
- BinaryOperation1 binary_op1,
5446
- BinaryOperation2 binary_op2);
5447
- template <class ExecutionPolicy,
5448
- class ForwardIterator1, class ForwardIterator2, class T,
5449
- class BinaryOperation1, class BinaryOperation2>
5450
- T transform_reduce(ExecutionPolicy&& exec,
5451
- ForwardIterator1 first1, ForwardIterator1 last1,
5452
- ForwardIterator2 first2,
5453
- T init,
5454
- BinaryOperation1 binary_op1,
5455
- BinaryOperation2 binary_op2);
5456
- ```
5457
-
5458
- *Requires:*
5459
-
5460
- - `T` shall be `MoveConstructible` (Table  [[tab:moveconstructible]]).
5461
- - All of
5462
- - `binary_op1(init, init)`,
5463
- - `binary_op1(init, binary_op2(*first1, *first2))`,
5464
- - `binary_op1(binary_op2(*first1, *first2), init)`, and
5465
- - `binary_op1(binary_op2(*first1, *first2), binary_op2(*first1, *first2))`
5466
-
5467
- shall be convertible to `T`.
5468
- - Neither `binary_op1` nor `binary_op2` shall invalidate subranges, or
5469
- modify elements in the ranges \[`first1`, `last1`\] and \[`first2`,
5470
- `first2 + (last1 - first1)`\].
5471
-
5472
- *Returns:*
5473
-
5474
- ``` cpp
5475
- GENERALIZED_SUM(binary_op1, init, binary_op2(*i, *(first2 + (i - first1))), ...)
5476
- ```
5477
-
5478
- for every iterator `i` in \[`first1`, `last1`).
5479
-
5480
- *Complexity:* 𝑂(`last1 - first1`) applications each of `binary_op1` and
5481
- `binary_op2`.
5482
-
5483
- ``` cpp
5484
- template<class InputIterator, class T,
5485
- class BinaryOperation, class UnaryOperation>
5486
- T transform_reduce(InputIterator first, InputIterator last, T init,
5487
- BinaryOperation binary_op, UnaryOperation unary_op);
5488
- template<class ExecutionPolicy,
5489
- class ForwardIterator, class T,
5490
- class BinaryOperation, class UnaryOperation>
5491
- T transform_reduce(ExecutionPolicy&& exec,
5492
- ForwardIterator first, ForwardIterator last,
5493
- T init, BinaryOperation binary_op, UnaryOperation unary_op);
5494
- ```
5495
-
5496
- *Requires:*
5497
-
5498
- - `T` shall be `MoveConstructible` (Table  [[tab:moveconstructible]]).
5499
- - All of
5500
- - `binary_op(init, init)`,
5501
- - `binary_op(init, unary_op(*first))`,
5502
- - `binary_op(unary_op(*first), init)`, and
5503
- - `binary_op(unary_op(*first), unary_op(*first))`
5504
-
5505
- shall be convertible to `T`.
5506
- - Neither `unary_op` nor `binary_op` shall invalidate subranges, or
5507
- modify elements in the range \[`first`, `last`\].
5508
-
5509
- *Returns:*
5510
-
5511
- ``` cpp
5512
- GENERALIZED_SUM(binary_op, init, unary_op(*i), ...)
5513
- ```
5514
-
5515
- for every iterator `i` in \[`first`, `last`).
5516
-
5517
- *Complexity:* 𝑂(`last - first`) applications each of `unary_op` and
5518
- `binary_op`.
5519
-
5520
- [*Note 1*: `transform_reduce` does not apply `unary_op` to
5521
- `init`. — *end note*]
5522
-
5523
- ### Partial sum <a id="partial.sum">[[partial.sum]]</a>
5524
-
5525
- ``` cpp
5526
- template <class InputIterator, class OutputIterator>
5527
- OutputIterator partial_sum(
5528
- InputIterator first, InputIterator last,
5529
- OutputIterator result);
5530
- template <class InputIterator, class OutputIterator, class BinaryOperation>
5531
- OutputIterator partial_sum(
5532
- InputIterator first, InputIterator last,
5533
- OutputIterator result, BinaryOperation binary_op);
5534
- ```
5535
-
5536
- *Requires:* `InputIterator`’s value type shall be constructible from the
5537
- type of `*first`. The result of the expression `acc + *i` or
5538
- `binary_op(acc, *i)` shall be implicitly convertible to
5539
- `InputIterator`’s value type. `acc` shall be
5540
- writable ([[iterator.requirements.general]]) to the `result` output
5541
- iterator. In the ranges \[`first`, `last`\] and \[`result`,
5542
- `result + (last - first)`\] `binary_op` shall neither modify elements
5543
- nor invalidate iterators or subranges.[^16]
5544
-
5545
- *Effects:* For a non-empty range, the function creates an accumulator
5546
- `acc` whose type is `InputIterator`’s value type, initializes it with
5547
- `*first`, and assigns the result to `*result`. For every iterator `i` in
5548
- \[`first + 1`, `last`) in order, `acc` is then modified by
5549
- `acc = acc + *i` or `acc = binary_op(acc, *i)` and the result is
5550
- assigned to `*(result + (i - first))`.
5551
-
5552
- *Returns:* `result + (last - first)`.
5553
-
5554
- *Complexity:* Exactly `(last - first) - 1` applications of the binary
5555
- operation.
5556
-
5557
- *Remarks:* `result` may be equal to `first`.
5558
-
5559
- ### Exclusive scan <a id="exclusive.scan">[[exclusive.scan]]</a>
5560
-
5561
- ``` cpp
5562
- template<class InputIterator, class OutputIterator, class T>
5563
- OutputIterator exclusive_scan(InputIterator first, InputIterator last,
5564
- OutputIterator result,
5565
- T init);
5566
- ```
5567
-
5568
- *Effects:* Equivalent to:
5569
-
5570
- ``` cpp
5571
- return exclusive_scan(first, last, result, init, plus<>());
5572
- ```
5573
-
5574
- ``` cpp
5575
- template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class T>
5576
- ForwardIterator2 exclusive_scan(ExecutionPolicy&& exec,
5577
- ForwardIterator1 first, ForwardIterator1 last,
5578
- ForwardIterator2 result,
5579
- T init);
5580
- ```
5581
-
5582
- *Effects:* Equivalent to:
5583
-
5584
- ``` cpp
5585
- return exclusive_scan(std::forward<ExecutionPolicy>(exec),
5586
- first, last, result, init, plus<>());
5587
- ```
5588
-
5589
- ``` cpp
5590
- template<class InputIterator, class OutputIterator, class T, class BinaryOperation>
5591
- OutputIterator exclusive_scan(InputIterator first, InputIterator last,
5592
- OutputIterator result,
5593
- T init, BinaryOperation binary_op);
5594
- template<class ExecutionPolicy,
5595
- class ForwardIterator1, class ForwardIterator2, class T, class BinaryOperation>
5596
- ForwardIterator2 exclusive_scan(ExecutionPolicy&& exec,
5597
- ForwardIterator1 first, ForwardIterator1 last,
5598
- ForwardIterator2 result,
5599
- T init, BinaryOperation binary_op);
5600
- ```
5601
-
5602
- *Requires:*
5603
-
5604
- - `T` shall be `MoveConstructible` (Table  [[tab:moveconstructible]]).
5605
- - All of `binary_op(init, init)`, `binary_op(init, *first)`, and
5606
- `binary_op(*first, *first)` shall be convertible to `T`.
5607
- - `binary_op` shall neither invalidate iterators or subranges, nor
5608
- modify elements in the ranges \[`first`, `last`\] or \[`result`,
5609
- `result + (last - first)`\].
5610
-
5611
- *Effects:* For each integer `K` in \[`0`, `last - first`) assigns
5612
- through `result + K` the value of:
5613
-
5614
- ``` cpp
5615
- GENERALIZED_NONCOMMUTATIVE_SUM(
5616
- binary_op, init, *(first + 0), *(first + 1), ..., *(first + K - 1))
5617
- ```
5618
-
5619
- *Returns:* The end of the resulting range beginning at `result`.
5620
-
5621
- *Complexity:* 𝑂(`last - first`) applications of `binary_op`.
5622
-
5623
- *Remarks:* `result` may be equal to `first`.
5624
-
5625
- [*Note 1*: The difference between `exclusive_scan` and `inclusive_scan`
5626
- is that `exclusive_scan` excludes the `i`th input element from the `i`th
5627
- sum. If `binary_op` is not mathematically associative, the behavior of
5628
- `exclusive_scan` may be nondeterministic. — *end note*]
5629
-
5630
- ### Inclusive scan <a id="inclusive.scan">[[inclusive.scan]]</a>
5631
-
5632
- ``` cpp
5633
- template<class InputIterator, class OutputIterator>
5634
- OutputIterator inclusive_scan(InputIterator first, InputIterator last,
5635
- OutputIterator result);
5636
- ```
5637
-
5638
- *Effects:* Equivalent to:
5639
-
5640
- ``` cpp
5641
- return inclusive_scan(first, last, result, plus<>());
5642
- ```
5643
-
5644
- ``` cpp
5645
- template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
5646
- ForwardIterator2 inclusive_scan(ExecutionPolicy&& exec,
5647
- ForwardIterator1 first, ForwardIterator1 last,
5648
- ForwardIterator2 result);
5649
- ```
5650
-
5651
- *Effects:* Equivalent to:
5652
-
5653
- ``` cpp
5654
- return inclusive_scan(std::forward<ExecutionPolicy>(exec), first, last, result, plus<>());
5655
- ```
5656
-
5657
- ``` cpp
5658
- template<class InputIterator, class OutputIterator, class BinaryOperation>
5659
- OutputIterator inclusive_scan(InputIterator first, InputIterator last,
5660
- OutputIterator result,
5661
- BinaryOperation binary_op);
5662
- template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
5663
- class BinaryOperation>
5664
- ForwardIterator2 inclusive_scan(ExecutionPolicy&& exec,
5665
- ForwardIterator1 first, ForwardIterator1 last,
5666
- ForwardIterator2 result,
5667
- BinaryOperation binary_op);
5668
-
5669
- template<class InputIterator, class OutputIterator, class BinaryOperation, class T>
5670
- OutputIterator inclusive_scan(InputIterator first, InputIterator last,
5671
- OutputIterator result,
5672
- BinaryOperation binary_op, T init);
5673
- template<class ExecutionPolicy,
5674
- class ForwardIterator1, class ForwardIterator2, class BinaryOperation, class T>
5675
- ForwardIterator2 inclusive_scan(ExecutionPolicy&& exec,
5676
- ForwardIterator1 first, ForwardIterator1 last,
5677
- ForwardIterator2 result,
5678
- BinaryOperation binary_op, T init);
5679
- ```
5680
-
5681
- *Requires:*
5682
-
5683
- - If `init` is provided, `T` shall be `MoveConstructible`
5684
- (Table  [[tab:moveconstructible]]); otherwise, `ForwardIterator1`’s
5685
- value type shall be `MoveConstructible`.
5686
- - If `init` is provided, all of `binary_op(init, init)`,
5687
- `binary_op(init, *first)`, and `binary_op(*first, *first)` shall be
5688
- convertible to `T`; otherwise, `binary_op(*first, *first)` shall be
5689
- convertible to `ForwardIterator1`’s value type.
5690
- - `binary_op` shall neither invalidate iterators or subranges, nor
5691
- modify elements in the ranges \[`first`, `last`\] or \[`result`,
5692
- `result + (last - first)`\].
5693
-
5694
- *Effects:* For each integer `K` in \[`0`, `last - first`) assigns
5695
- through `result + K` the value of
5696
-
5697
- - *GENERALIZED_NONCOMMUTATIVE_SUM*(
5698
-     binary_op, init, \*(first + 0), \*(first + 1), ..., \*(first +
5699
- K))
5700
- if `init` is provided, or
5701
- - *GENERALIZED_NONCOMMUTATIVE_SUM*(
5702
-     binary_op, \*(first + 0), \*(first + 1), ..., \*(first + K))
5703
- otherwise.
5704
-
5705
- *Returns:* The end of the resulting range beginning at `result`.
5706
-
5707
- *Complexity:* 𝑂(`last - first`) applications of `binary_op`.
5708
-
5709
- *Remarks:* `result` may be equal to `first`.
5710
-
5711
- [*Note 1*: The difference between `exclusive_scan` and `inclusive_scan`
5712
- is that `inclusive_scan` includes the `i`th input element in the `i`th
5713
- sum. If `binary_op` is not mathematically associative, the behavior of
5714
- `inclusive_scan` may be nondeterministic. — *end note*]
5715
-
5716
- ### Transform exclusive scan <a id="transform.exclusive.scan">[[transform.exclusive.scan]]</a>
5717
-
5718
- ``` cpp
5719
- template<class InputIterator, class OutputIterator, class T,
5720
- class BinaryOperation, class UnaryOperation>
5721
- OutputIterator transform_exclusive_scan(InputIterator first, InputIterator last,
5722
- OutputIterator result,
5723
- T init,
5724
- BinaryOperation binary_op,
5725
- UnaryOperation unary_op);
5726
- template<class ExecutionPolicy,
5727
- class ForwardIterator1, class ForwardIterator2, class T,
5728
- class BinaryOperation, class UnaryOperation>
5729
- ForwardIterator2 transform_exclusive_scan(ExecutionPolicy&& exec,
5730
- ForwardIterator1 first, ForwardIterator1 last,
5731
- ForwardIterator2 result,
5732
- T init,
5733
- BinaryOperation binary_op,
5734
- UnaryOperation unary_op);
5735
- ```
5736
-
5737
- *Requires:*
5738
-
5739
- - `T` shall be `MoveConstructible` (Table  [[tab:moveconstructible]]).
5740
- - All of
5741
- - `binary_op(init, init)`,
5742
- - `binary_op(init, unary_op(*first))`, and
5743
- - `binary_op(unary_op(*first), unary_op(*first))`
5744
-
5745
- shall be convertible to `T`.
5746
- - Neither `unary_op` nor `binary_op` shall invalidate iterators or
5747
- subranges, or modify elements in the ranges \[`first`, `last`\] or
5748
- \[`result`, `result + (last - first)`\].
5749
-
5750
- *Effects:* For each integer `K` in \[`0`, `last - first`) assigns
5751
- through `result + K` the value of:
5752
-
5753
- ``` cpp
5754
- GENERALIZED_NONCOMMUTATIVE_SUM(
5755
- binary_op, init,
5756
- unary_op(*(first + 0)), unary_op(*(first + 1)), ..., unary_op(*(first + K - 1)))
5757
- ```
5758
-
5759
- *Returns:* The end of the resulting range beginning at `result`.
5760
-
5761
- *Complexity:* 𝑂(`last - first`) applications each of `unary_op` and
5762
- `binary_op`.
5763
-
5764
- *Remarks:* `result` may be equal to `first`.
5765
-
5766
- [*Note 1*: The difference between `transform_exclusive_scan` and
5767
- `transform_inclusive_scan` is that `transform_exclusive_scan` excludes
5768
- the iᵗʰ input element from the iᵗʰ sum. If `binary_op` is not
5769
- mathematically associative, the behavior of `transform_exclusive_scan`
5770
- may be nondeterministic. `transform_exclusive_scan` does not apply
5771
- `unary_op` to `init`. — *end note*]
5772
-
5773
- ### Transform inclusive scan <a id="transform.inclusive.scan">[[transform.inclusive.scan]]</a>
5774
-
5775
- ``` cpp
5776
- template<class InputIterator, class OutputIterator,
5777
- class BinaryOperation, class UnaryOperation>
5778
- OutputIterator transform_inclusive_scan(InputIterator first, InputIterator last,
5779
- OutputIterator result,
5780
- BinaryOperation binary_op,
5781
- UnaryOperation unary_op);
5782
- template<class ExecutionPolicy,
5783
- class ForwardIterator1, class ForwardIterator2,
5784
- class BinaryOperation, class UnaryOperation>
5785
- ForwardIterator2 transform_inclusive_scan(ExecutionPolicy&& exec,
5786
- ForwardIterator1 first, ForwardIterator1 last,
5787
- ForwardIterator2 result,
5788
- BinaryOperation binary_op,
5789
- UnaryOperation unary_op);
5790
- template<class InputIterator, class OutputIterator,
5791
- class BinaryOperation, class UnaryOperation, class T>
5792
- OutputIterator transform_inclusive_scan(InputIterator first, InputIterator last,
5793
- OutputIterator result,
5794
- BinaryOperation binary_op,
5795
- UnaryOperation unary_op,
5796
- T init);
5797
- template<class ExecutionPolicy,
5798
- class ForwardIterator1, class ForwardIterator2,
5799
- class BinaryOperation, class UnaryOperation, class T>
5800
- ForwardIterator2 transform_inclusive_scan(ExecutionPolicy&& exec,
5801
- ForwardIterator1 first, ForwardIterator1 last,
5802
- ForwardIterator2 result,
5803
- BinaryOperation binary_op,
5804
- UnaryOperation unary_op,
5805
- T init);
5806
- ```
5807
-
5808
- *Requires:*
5809
-
5810
- - If `init` is provided, `T` shall be `MoveConstructible`
5811
- (Table  [[tab:moveconstructible]]); otherwise, `ForwardIterator1`’s
5812
- value type shall be `MoveConstructible`.
5813
- - If `init` is provided, all of
5814
- - `binary_op(init, init)`,
5815
- - `binary_op(init, unary_op(*first))`, and
5816
- - `binary_op(unary_op(*first), unary_op(*first))`
5817
-
5818
- shall be convertible to `T`; otherwise,
5819
- `binary_op(unary_op(*first), unary_op(*first))` shall be convertible
5820
- to `ForwardIterator1`’s value type.
5821
- - Neither `unary_op` nor `binary_op` shall invalidate iterators or
5822
- subranges, nor modify elements in the ranges \[`first`, `last`\] or
5823
- \[`result`, `result + (last - first)`\].
5824
-
5825
- *Effects:* For each integer `K` in \[`0`, `last - first`) assigns
5826
- through `result + K` the value of
5827
-
5828
- - *GENERALIZED_NONCOMMUTATIVE_SUM*(
5829
-     binary_op, init,
5830
-     unary_op(\*(first + 0)), unary_op(\*(first + 1)), ...,
5831
- unary_op(\*(first + K)))
5832
- if `init` is provided, or
5833
- - *GENERALIZED_NONCOMMUTATIVE_SUM*(
5834
-     binary_op,
5835
-     unary_op(\*(first + 0)), unary_op(\*(first + 1)), ...,
5836
- unary_op(\*(first + K)))
5837
- otherwise.
5838
-
5839
- *Returns:* The end of the resulting range beginning at `result`.
5840
-
5841
- *Complexity:* 𝑂(`last - first`) applications each of `unary_op` and
5842
- `binary_op`.
5843
-
5844
- *Remarks:* `result` may be equal to `first`.
5845
-
5846
- [*Note 1*: The difference between `transform_exclusive_scan` and
5847
- `transform_inclusive_scan` is that `transform_inclusive_scan` includes
5848
- the iᵗʰ input element in the iᵗʰ sum. If `binary_op` is not
5849
- mathematically associative, the behavior of `transform_inclusive_scan`
5850
- may be nondeterministic. `transform_inclusive_scan` does not apply
5851
- `unary_op` to `init`. — *end note*]
5852
-
5853
- ### Adjacent difference <a id="adjacent.difference">[[adjacent.difference]]</a>
5854
-
5855
- ``` cpp
5856
- template <class InputIterator, class OutputIterator>
5857
- OutputIterator
5858
- adjacent_difference(InputIterator first, InputIterator last,
5859
- OutputIterator result);
5860
- template <class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
5861
- ForwardIterator2
5862
- adjacent_difference(ExecutionPolicy&& exec,
5863
- ForwardIterator1 first, ForwardIterator1 last,
5864
- ForwardIterator2 result);
5865
-
5866
- template <class InputIterator, class OutputIterator, class BinaryOperation>
5867
- OutputIterator
5868
- adjacent_difference(InputIterator first, InputIterator last,
5869
- OutputIterator result,
5870
- BinaryOperation binary_op);
5871
- template <class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
5872
- class BinaryOperation>
5873
- ForwardIterator2
5874
- adjacent_difference(ExecutionPolicy&& exec,
5875
- ForwardIterator1 first, ForwardIterator1 last,
5876
- ForwardIterator2 result,
5877
- BinaryOperation binary_op);
5878
- ```
5879
-
5880
- *Requires:*
5881
-
5882
- - For the overloads with no `ExecutionPolicy`, `InputIterator`’s value
5883
- type shall be `MoveAssignable` (Table  [[tab:moveassignable]]) and
5884
- shall be constructible from the type of `*first`. `acc` (defined
5885
- below) shall be writable ([[iterator.requirements.general]]) to the
5886
- `result` output iterator. The result of the expression `val - acc` or
5887
- `binary_op(val, acc)` shall be writable to the `result` output
5888
- iterator.
5889
- - For the overloads with an `ExecutionPolicy`, the value type of
5890
- `ForwardIterator1` shall be `CopyConstructible`
5891
- (Table  [[tab:copyconstructible]]), constructible from the expression
5892
- `*first - *first` or `binary_op(*first, *first)`, and assignable to
5893
- the value type of `ForwardIterator2`.
5894
- - For all overloads, in the ranges \[`first`, `last`\] and \[`result`,
5895
- `result + (last - first)`\], `binary_op` shall neither modify elements
5896
- nor invalidate iterators or subranges.[^17]
5897
-
5898
- *Effects:* For the overloads with no `ExecutionPolicy` and a non-empty
5899
- range, the function creates an accumulator `acc` whose type is
5900
- `InputIterator`’s value type, initializes it with `*first`, and assigns
5901
- the result to `*result`. For every iterator `i` in \[`first + 1`,
5902
- `last`) in order, creates an object `val` whose type is
5903
- `InputIterator`’s value type, initializes it with `*i`, computes
5904
- `val - acc` or `binary_op(val, acc)`, assigns the result to
5905
- `*(result + (i - first))`, and move assigns from `val` to `acc`.
5906
-
5907
- For the overloads with an `ExecutionPolicy` and a non-empty range, first
5908
- the function creates an object whose type is `ForwardIterator1`’s value
5909
- type, initializes it with `*first`, and assigns the result to `*result`.
5910
- Then for every `d` in \[`1`, `last - first - 1`\], creates an object
5911
- `val` whose type is `ForwardIterator1`’s value type, initializes it with
5912
- `*(first + d) - *(first + d - 1)` or
5913
- `binary_op(*(first + d), *(first + d - 1))`, and assigns the result to
5914
- `*(result + d)`.
5915
-
5916
- *Returns:* `result + (last - first)`.
5917
-
5918
- *Complexity:* Exactly `(last - first) - 1` applications of the binary
5919
- operation.
5920
-
5921
- *Remarks:* For the overloads with no `ExecutionPolicy`, `result` may be
5922
- equal to `first`. For the overloads with an `ExecutionPolicy`, the
5923
- ranges \[`first`, `last`) and \[`result`, `result + (last - first)`)
5924
- shall not overlap.
5925
-
5926
- ### Iota <a id="numeric.iota">[[numeric.iota]]</a>
5927
-
5928
- ``` cpp
5929
- template <class ForwardIterator, class T>
5930
- void iota(ForwardIterator first, ForwardIterator last, T value);
5931
- ```
5932
-
5933
- *Requires:* `T` shall be convertible to `ForwardIterator`’s value type.
5934
- The expression `++val`, where `val` has type `T`, shall be well formed.
5935
-
5936
- *Effects:* For each element referred to by the iterator `i` in the range
5937
- \[`first`, `last`), assigns `*i = value` and increments `value` as if by
5938
- `++value`.
5939
-
5940
- *Complexity:* Exactly `last - first` increments and assignments.
5941
-
5942
- ### Greatest common divisor <a id="numeric.ops.gcd">[[numeric.ops.gcd]]</a>
5943
-
5944
- ``` cpp
5945
- template <class M, class N>
5946
- constexpr common_type_t<M,N> gcd(M m, N n);
5947
- ```
5948
-
5949
- *Requires:* `|m|` and `|n|` shall be representable as a value of
5950
- `common_type_t<M, N>`.
5951
-
5952
- [*Note 1*: These requirements ensure, for example, that
5953
- `gcd(m, m) = |m|` is representable as a value of type
5954
- `M`. — *end note*]
5955
-
5956
- *Remarks:* If either `M` or `N` is not an integer type, or if either is
5957
- cv `bool`, the program is ill-formed.
5958
-
5959
- *Returns:* Zero when `m` and `n` are both zero. Otherwise, returns the
5960
- greatest common divisor of `|m|` and `|n|`.
5961
-
5962
- *Throws:* Nothing.
5963
-
5964
- ### Least common multiple <a id="numeric.ops.lcm">[[numeric.ops.lcm]]</a>
5965
-
5966
- ``` cpp
5967
- template <class M, class N>
5968
- constexpr common_type_t<M,N> lcm(M m, N n);
5969
- ```
5970
-
5971
- *Requires:* `|m|` and `|n|` shall be representable as a value of
5972
- `common_type_t<M, N>`. The least common multiple of `|m|` and `|n|`
5973
- shall be representable as a value of type `common_type_t<M,N>`.
5974
-
5975
- *Remarks:* If either `M` or `N` is not an integer type, or if either is
5976
- cv `bool` the program is ill-formed.
5977
-
5978
- *Returns:* Zero when either `m` or `n` is zero. Otherwise, returns the
5979
- least common multiple of `|m|` and `|n|`.
5980
-
5981
- *Throws:* Nothing.
5982
-
5983
  ## Mathematical functions for floating-point types <a id="c.math">[[c.math]]</a>
5984
 
5985
  ### Header `<cmath>` synopsis <a id="cmath.syn">[[cmath.syn]]</a>
5986
 
5987
  ``` cpp
@@ -6193,11 +5610,11 @@ namespace std {
6193
  float fabsf(float x);
6194
  long double fabsl(long double x);
6195
 
6196
  float hypot(float x, float y); // see [library.c]
6197
  double hypot(double x, double y);
6198
- long double hypot(double x, double y); // see [library.c]
6199
  float hypotf(float x, float y);
6200
  long double hypotl(long double x, long double y);
6201
 
6202
  // [c.math.hypot3], three-dimensional hypotenuse
6203
  float hypot(float x, float y, float z);
@@ -6362,123 +5779,128 @@ namespace std {
6362
  double fma(double x, double y, double z);
6363
  long double fma(long double x, long double y, long double z); // see [library.c]
6364
  float fmaf(float x, float y, float z);
6365
  long double fmal(long double x, long double y, long double z);
6366
 
 
 
 
 
 
6367
  // [c.math.fpclass], classification / comparison functions
6368
  int fpclassify(float x);
6369
  int fpclassify(double x);
6370
  int fpclassify(long double x);
6371
 
6372
- int isfinite(float x);
6373
- int isfinite(double x);
6374
- int isfinite(long double x);
6375
 
6376
- int isinf(float x);
6377
- int isinf(double x);
6378
- int isinf(long double x);
6379
 
6380
- int isnan(float x);
6381
- int isnan(double x);
6382
- int isnan(long double x);
6383
 
6384
- int isnormal(float x);
6385
- int isnormal(double x);
6386
- int isnormal(long double x);
6387
 
6388
- int signbit(float x);
6389
- int signbit(double x);
6390
- int signbit(long double x);
6391
 
6392
- int isgreater(float x, float y);
6393
- int isgreater(double x, double y);
6394
- int isgreater(long double x, long double y);
6395
 
6396
- int isgreaterequal(float x, float y);
6397
- int isgreaterequal(double x, double y);
6398
- int isgreaterequal(long double x, long double y);
6399
 
6400
- int isless(float x, float y);
6401
- int isless(double x, double y);
6402
- int isless(long double x, long double y);
6403
 
6404
- int islessequal(float x, float y);
6405
- int islessequal(double x, double y);
6406
- int islessequal(long double x, long double y);
6407
 
6408
- int islessgreater(float x, float y);
6409
- int islessgreater(double x, double y);
6410
- int islessgreater(long double x, long double y);
6411
 
6412
- int isunordered(float x, float y);
6413
- int isunordered(double x, double y);
6414
- int isunordered(long double x, long double y);
6415
 
6416
  // [sf.cmath], mathematical special functions
6417
 
6418
- // [sf.cmath.assoc_laguerre], associated Laguerre polynomials
6419
  double assoc_laguerre(unsigned n, unsigned m, double x);
6420
  float assoc_laguerref(unsigned n, unsigned m, float x);
6421
  long double assoc_laguerrel(unsigned n, unsigned m, long double x);
6422
 
6423
- // [sf.cmath.assoc_legendre], associated Legendre functions
6424
  double assoc_legendre(unsigned l, unsigned m, double x);
6425
  float assoc_legendref(unsigned l, unsigned m, float x);
6426
  long double assoc_legendrel(unsigned l, unsigned m, long double x);
6427
 
6428
  // [sf.cmath.beta], beta function
6429
  double beta(double x, double y);
6430
  float betaf(float x, float y);
6431
  long double betal(long double x, long double y);
6432
 
6433
- // [sf.cmath.comp_ellint_1], complete elliptic integral of the first kind
6434
  double comp_ellint_1(double k);
6435
  float comp_ellint_1f(float k);
6436
  long double comp_ellint_1l(long double k);
6437
 
6438
- // [sf.cmath.comp_ellint_2], complete elliptic integral of the second kind
6439
  double comp_ellint_2(double k);
6440
  float comp_ellint_2f(float k);
6441
  long double comp_ellint_2l(long double k);
6442
 
6443
- // [sf.cmath.comp_ellint_3], complete elliptic integral of the third kind
6444
  double comp_ellint_3(double k, double nu);
6445
  float comp_ellint_3f(float k, float nu);
6446
  long double comp_ellint_3l(long double k, long double nu);
6447
 
6448
- // [sf.cmath.cyl_bessel_i], regular modified cylindrical Bessel functions
6449
  double cyl_bessel_i(double nu, double x);
6450
  float cyl_bessel_if(float nu, float x);
6451
  long double cyl_bessel_il(long double nu, long double x);
6452
 
6453
- // [sf.cmath.cyl_bessel_j], cylindrical Bessel functions of the first kind
6454
  double cyl_bessel_j(double nu, double x);
6455
  float cyl_bessel_jf(float nu, float x);
6456
  long double cyl_bessel_jl(long double nu, long double x);
6457
 
6458
- // [sf.cmath.cyl_bessel_k], irregular modified cylindrical Bessel functions
6459
  double cyl_bessel_k(double nu, double x);
6460
  float cyl_bessel_kf(float nu, float x);
6461
  long double cyl_bessel_kl(long double nu, long double x);
6462
 
6463
- // [sf.cmath.cyl_neumann], cylindrical Neumann functions;
6464
  // cylindrical Bessel functions of the second kind
6465
  double cyl_neumann(double nu, double x);
6466
  float cyl_neumannf(float nu, float x);
6467
  long double cyl_neumannl(long double nu, long double x);
6468
 
6469
- // [sf.cmath.ellint_1], incomplete elliptic integral of the first kind
6470
  double ellint_1(double k, double phi);
6471
  float ellint_1f(float k, float phi);
6472
  long double ellint_1l(long double k, long double phi);
6473
 
6474
- // [sf.cmath.ellint_2], incomplete elliptic integral of the second kind
6475
  double ellint_2(double k, double phi);
6476
  float ellint_2f(float k, float phi);
6477
  long double ellint_2l(long double k, long double phi);
6478
 
6479
- // [sf.cmath.ellint_3], incomplete elliptic integral of the third kind
6480
  double ellint_3(double k, double nu, double phi);
6481
  float ellint_3f(float k, float nu, float phi);
6482
  long double ellint_3l(long double k, long double nu, long double phi);
6483
 
6484
  // [sf.cmath.expint], exponential integral
@@ -6499,27 +5921,27 @@ namespace std {
6499
  // [sf.cmath.legendre], Legendre polynomials
6500
  double legendre(unsigned l, double x);
6501
  float legendref(unsigned l, float x);
6502
  long double legendrel(unsigned l, long double x);
6503
 
6504
- // [sf.cmath.riemann_zeta], Riemann zeta function
6505
  double riemann_zeta(double x);
6506
  float riemann_zetaf(float x);
6507
  long double riemann_zetal(long double x);
6508
 
6509
- // [sf.cmath.sph_bessel], spherical Bessel functions of the first kind
6510
  double sph_bessel(unsigned n, double x);
6511
  float sph_besself(unsigned n, float x);
6512
  long double sph_bessell(unsigned n, long double x);
6513
 
6514
- // [sf.cmath.sph_legendre], spherical associated Legendre functions
6515
  double sph_legendre(unsigned l, unsigned m, double theta);
6516
  float sph_legendref(unsigned l, unsigned m, float theta);
6517
  long double sph_legendrel(unsigned l, unsigned m, long double theta);
6518
 
6519
- // [sf.cmath.sph_neumann], spherical Neumann functions;
6520
- // spherical Bessel functions of the second kind:
6521
  double sph_neumann(unsigned n, double x);
6522
  float sph_neumannf(unsigned n, float x);
6523
  long double sph_neumannl(unsigned n, long double x);
6524
  }
6525
  ```
@@ -6528,38 +5950,37 @@ The contents and meaning of the header `<cmath>` are the same as the C
6528
  standard library header `<math.h>`, with the addition of a
6529
  three-dimensional hypotenuse function ([[c.math.hypot3]]) and the
6530
  mathematical special functions described in [[sf.cmath]].
6531
 
6532
  [*Note 1*: Several functions have additional overloads in this
6533
- International Standard, but they have the same behavior as in the C
6534
- standard library ([[library.c]]). — *end note*]
6535
 
6536
  For each set of overloaded functions within `<cmath>`, with the
6537
  exception of `abs`, there shall be additional overloads sufficient to
6538
  ensure:
6539
 
6540
- 1. If any argument of arithmetic type corresponding to a `double`
6541
  parameter has type `long double`, then all arguments of arithmetic
6542
- type ([[basic.fundamental]]) corresponding to `double` parameters
6543
- are effectively cast to `long double`.
6544
- 2. Otherwise, if any argument of arithmetic type corresponding to a
6545
  `double` parameter has type `double` or an integer type, then all
6546
- arguments of arithmetic type corresponding to `double` parameters
6547
- are effectively cast to `double`.
6548
- 3. Otherwise, all arguments of arithmetic type corresponding to
6549
- `double` parameters have type `float`.
6550
 
6551
- [*Note 2*: `abs` is exempted from these rules in order to stay
6552
  compatible with C. — *end note*]
6553
 
6554
  ISO C 7.12
6555
 
6556
  ### Absolute values <a id="c.math.abs">[[c.math.abs]]</a>
6557
 
6558
- [*Note 1*: The headers `<cstdlib>` ([[cstdlib.syn]]) and `<cmath>` (
6559
- [[cmath.syn]]) declare the functions described in this
6560
- subclause. — *end note*]
6561
 
6562
  ``` cpp
6563
  int abs(int j);
6564
  long int abs(long int j);
6565
  long long int abs(long long int j);
@@ -6572,16 +5993,16 @@ long double abs(long double j);
6572
  standard library for the functions `abs`, `labs`, `llabs`, `fabsf`,
6573
  `fabs`, and `fabsl`.
6574
 
6575
  *Remarks:* If `abs()` is called with an argument of type `X` for which
6576
  `is_unsigned_v<X>` is `true` and if `X` cannot be converted to `int` by
6577
- integral promotion ([[conv.prom]]), the program is ill-formed.
6578
 
6579
  [*Note 1*: Arguments that can be promoted to `int` are permitted for
6580
  compatibility with C. — *end note*]
6581
 
6582
- ISO C 7.12.7.2, 7.22.6.1
6583
 
6584
  ### Three-dimensional hypotenuse <a id="c.math.hypot3">[[c.math.hypot3]]</a>
6585
 
6586
  ``` cpp
6587
  float hypot(float x, float y, float z);
@@ -6589,10 +6010,34 @@ double hypot(double x, double y, double z);
6589
  long double hypot(long double x, long double y, long double z);
6590
  ```
6591
 
6592
  *Returns:* $\sqrt{x^2+y^2+z^2}$.
6593
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6594
  ### Classification / comparison functions <a id="c.math.fpclass">[[c.math.fpclass]]</a>
6595
 
6596
  The classification / comparison functions behave the same as the C
6597
  macros with the corresponding names defined in the C standard library.
6598
  Each function is overloaded for the three floating-point types.
@@ -6609,54 +6054,48 @@ a domain error for just those argument values for which:
6609
  - the function description’s *Returns:* clause explicitly specifies a
6610
  domain and those argument values fall outside the specified domain, or
6611
  - the corresponding mathematical function value has a nonzero imaginary
6612
  component, or
6613
  - the corresponding mathematical function is not mathematically
6614
- defined.[^18]
6615
 
6616
  Unless otherwise specified, each function is defined for all finite
6617
  values, for negative infinity, and for positive infinity.
6618
 
6619
- #### Associated Laguerre polynomials <a id="sf.cmath.assoc_laguerre">[[sf.cmath.assoc_laguerre]]</a>
6620
 
6621
  ``` cpp
6622
  double assoc_laguerre(unsigned n, unsigned m, double x);
6623
  float assoc_laguerref(unsigned n, unsigned m, float x);
6624
  long double assoc_laguerrel(unsigned n, unsigned m, long double x);
6625
  ```
6626
 
6627
  *Effects:* These functions compute the associated Laguerre polynomials
6628
  of their respective arguments `n`, `m`, and `x`.
6629
 
6630
- *Returns:* $$%
6631
- \mathsf{L}_n^m(x) =
6632
- (-1)^m \frac{\mathsf{d} ^ m}
6633
- {\mathsf{d}x ^ m} \, \mathsf{L}_{n+m}(x),
6634
- \quad \mbox{for $x \ge 0$}$$ where n is `n`, m is `m`, and x is
6635
  `x`.
6636
 
6637
  *Remarks:* The effect of calling each of these functions is
6638
  *implementation-defined* if `n >= 128` or if `m >= 128`.
6639
 
6640
- #### Associated Legendre functions <a id="sf.cmath.assoc_legendre">[[sf.cmath.assoc_legendre]]</a>
6641
 
6642
  ``` cpp
6643
  double assoc_legendre(unsigned l, unsigned m, double x);
6644
  float assoc_legendref(unsigned l, unsigned m, float x);
6645
  long double assoc_legendrel(unsigned l, unsigned m, long double x);
6646
  ```
6647
 
6648
  *Effects:* These functions compute the associated Legendre functions of
6649
  their respective arguments `l`, `m`, and `x`.
6650
 
6651
- *Returns:* $$%
6652
- \mathsf{P}_\ell^m(x) =
6653
- (1 - x^2) ^ {m/2}
6654
- \:
6655
- \frac{ \mathsf{d} ^ m}
6656
- { \mathsf{d}x ^ m} \, \mathsf{P}_\ell(x),
6657
- \quad \mbox{for $|x| \le 1$}$$ where l is `l`, m is `m`, and x is
6658
  `x`.
6659
 
6660
  *Remarks:* The effect of calling each of these functions is
6661
  *implementation-defined* if `l >= 128`.
6662
 
@@ -6669,115 +6108,105 @@ long double betal(long double x, long double y);
6669
  ```
6670
 
6671
  *Effects:* These functions compute the beta function of their respective
6672
  arguments `x` and `y`.
6673
 
6674
- *Returns:* $$%
6675
- \mathsf{B}(x, y) =
6676
- \frac{ \Gamma(x) \, \Gamma(y) }
6677
- { \Gamma(x+y) },
6678
- \quad \mbox{for $x > 0$,\, $y > 0$}$$ where x is `x` and y is
6679
- `y`.
6680
 
6681
- #### Complete elliptic integral of the first kind <a id="sf.cmath.comp_ellint_1">[[sf.cmath.comp_ellint_1]]</a>
6682
 
6683
  ``` cpp
6684
  double comp_ellint_1(double k);
6685
  float comp_ellint_1f(float k);
6686
  long double comp_ellint_1l(long double k);
6687
  ```
6688
 
6689
  *Effects:* These functions compute the complete elliptic integral of the
6690
  first kind of their respective arguments `k`.
6691
 
6692
- *Returns:* $$%
6693
- \mathsf{K}(k) =
6694
- \mathsf{F}(k, \pi / 2),
6695
- \quad \mbox{for $|k| \le 1$}$$ where k is `k`.
6696
 
6697
- See also [[sf.cmath.ellint_1]].
6698
 
6699
- #### Complete elliptic integral of the second kind <a id="sf.cmath.comp_ellint_2">[[sf.cmath.comp_ellint_2]]</a>
6700
 
6701
  ``` cpp
6702
  double comp_ellint_2(double k);
6703
  float comp_ellint_2f(float k);
6704
  long double comp_ellint_2l(long double k);
6705
  ```
6706
 
6707
  *Effects:* These functions compute the complete elliptic integral of the
6708
  second kind of their respective arguments `k`.
6709
 
6710
- *Returns:* $$%
6711
- \mathsf{E}(k) =
6712
- \mathsf{E}(k, \pi / 2),
6713
- \quad \mbox{for $|k| \le 1$}$$ where k is `k`.
6714
 
6715
- See also [[sf.cmath.ellint_2]].
6716
 
6717
- #### Complete elliptic integral of the third kind <a id="sf.cmath.comp_ellint_3">[[sf.cmath.comp_ellint_3]]</a>
6718
 
6719
  ``` cpp
6720
  double comp_ellint_3(double k, double nu);
6721
  float comp_ellint_3f(float k, float nu);
6722
  long double comp_ellint_3l(long double k, long double nu);
6723
  ```
6724
 
6725
  *Effects:* These functions compute the complete elliptic integral of the
6726
  third kind of their respective arguments `k` and `nu`.
6727
 
6728
- *Returns:* $$%
6729
- \mathsf{\Pi}(\nu, k) = \mathsf{\Pi}(\nu, k, \pi / 2),
6730
- \quad \mbox{for $|k| \le 1$}$$ where k is `k` and $\nu$ is `nu`.
6731
 
6732
- See also [[sf.cmath.ellint_3]].
6733
 
6734
- #### Regular modified cylindrical Bessel functions <a id="sf.cmath.cyl_bessel_i">[[sf.cmath.cyl_bessel_i]]</a>
6735
 
6736
  ``` cpp
6737
  double cyl_bessel_i(double nu, double x);
6738
  float cyl_bessel_if(float nu, float x);
6739
  long double cyl_bessel_il(long double nu, long double x);
6740
  ```
6741
 
6742
  *Effects:* These functions compute the regular modified cylindrical
6743
  Bessel functions of their respective arguments `nu` and `x`.
6744
 
6745
- *Returns:* $$%
6746
- \mathsf{I}_\nu(x) =
6747
- i^{-\nu} \mathsf{J}_\nu(ix)
6748
- =
6749
- \sum_{k=0}^\infty \frac{(x/2)^{\nu+2k}}
6750
- {k! \: \Gamma(\nu+k+1)},
6751
- \quad \mbox{for $x \ge 0$}$$ where $\nu$ is `nu` and x is `x`.
6752
 
6753
  *Remarks:* The effect of calling each of these functions is
6754
  *implementation-defined* if `nu >= 128`.
6755
 
6756
- See also [[sf.cmath.cyl_bessel_j]].
6757
 
6758
- #### Cylindrical Bessel functions of the first kind <a id="sf.cmath.cyl_bessel_j">[[sf.cmath.cyl_bessel_j]]</a>
6759
 
6760
  ``` cpp
6761
  double cyl_bessel_j(double nu, double x);
6762
  float cyl_bessel_jf(float nu, float x);
6763
  long double cyl_bessel_jl(long double nu, long double x);
6764
  ```
6765
 
6766
  *Effects:* These functions compute the cylindrical Bessel functions of
6767
  the first kind of their respective arguments `nu` and `x`.
6768
 
6769
- *Returns:* $$%
6770
- \mathsf{J}_\nu(x) =
6771
- \sum_{k=0}^\infty \frac{(-1)^k (x/2)^{\nu+2k}}
6772
- {k! \: \Gamma(\nu+k+1)},
6773
- \quad \mbox{for $x \ge 0$}$$ where $\nu$ is `nu` and x is `x`.
6774
 
6775
  *Remarks:* The effect of calling each of these functions is
6776
  *implementation-defined* if `nu >= 128`.
6777
 
6778
- #### Irregular modified cylindrical Bessel functions <a id="sf.cmath.cyl_bessel_k">[[sf.cmath.cyl_bessel_k]]</a>
6779
 
6780
  ``` cpp
6781
  double cyl_bessel_k(double nu, double x);
6782
  float cyl_bessel_kf(float nu, float x);
6783
  long double cyl_bessel_kl(long double nu, long double x);
@@ -6810,14 +6239,14 @@ Bessel functions of their respective arguments `nu` and `x`.
6810
  \right.$$ where $\nu$ is `nu` and x is `x`.
6811
 
6812
  *Remarks:* The effect of calling each of these functions is
6813
  *implementation-defined* if `nu >= 128`.
6814
 
6815
- See also [[sf.cmath.cyl_bessel_i]], [[sf.cmath.cyl_bessel_j]],
6816
- [[sf.cmath.cyl_neumann]].
6817
 
6818
- #### Cylindrical Neumann functions <a id="sf.cmath.cyl_neumann">[[sf.cmath.cyl_neumann]]</a>
6819
 
6820
  ``` cpp
6821
  double cyl_neumann(double nu, double x);
6822
  float cyl_neumannf(float nu, float x);
6823
  long double cyl_neumannl(long double nu, long double x);
@@ -6845,13 +6274,13 @@ their respective arguments `nu` and `x`.
6845
  \right.$$ where $\nu$ is `nu` and x is `x`.
6846
 
6847
  *Remarks:* The effect of calling each of these functions is
6848
  *implementation-defined* if `nu >= 128`.
6849
 
6850
- See also [[sf.cmath.cyl_bessel_j]].
6851
 
6852
- #### Incomplete elliptic integral of the first kind <a id="sf.cmath.ellint_1">[[sf.cmath.ellint_1]]</a>
6853
 
6854
  ``` cpp
6855
  double ellint_1(double k, double phi);
6856
  float ellint_1f(float k, float phi);
6857
  long double ellint_1l(long double k, long double phi);
@@ -6859,17 +6288,15 @@ long double ellint_1l(long double k, long double phi);
6859
 
6860
  *Effects:* These functions compute the incomplete elliptic integral of
6861
  the first kind of their respective arguments `k` and `phi` (`phi`
6862
  measured in radians).
6863
 
6864
- *Returns:* $$%
6865
- \mathsf{F}(k, \phi) =
6866
- \int_0^\phi \! \frac{\mathsf{d}\theta}
6867
- {\sqrt{1 - k^2 \sin^2 \theta}},
6868
- \quad \mbox{for $|k| \le 1$}$$ where k is `k` and φ is `phi`.
6869
 
6870
- #### Incomplete elliptic integral of the second kind <a id="sf.cmath.ellint_2">[[sf.cmath.ellint_2]]</a>
6871
 
6872
  ``` cpp
6873
  double ellint_2(double k, double phi);
6874
  float ellint_2f(float k, float phi);
6875
  long double ellint_2l(long double k, long double phi);
@@ -6877,16 +6304,15 @@ long double ellint_2l(long double k, long double phi);
6877
 
6878
  *Effects:* These functions compute the incomplete elliptic integral of
6879
  the second kind of their respective arguments `k` and `phi` (`phi`
6880
  measured in radians).
6881
 
6882
- *Returns:* $$%
6883
- \mathsf{E}(k, \phi) =
6884
- \int_0^\phi \! \sqrt{1 - k^2 \sin^2 \theta} \, \mathsf{d}\theta,
6885
- \quad \mbox{for $|k| \le 1$}$$ where k is `k` and φ is `phi`.
6886
 
6887
- #### Incomplete elliptic integral of the third kind <a id="sf.cmath.ellint_3">[[sf.cmath.ellint_3]]</a>
6888
 
6889
  ``` cpp
6890
  double ellint_3(double k, double nu, double phi);
6891
  float ellint_3f(float k, float nu, float phi);
6892
  long double ellint_3l(long double k, long double nu, long double phi);
@@ -6894,16 +6320,13 @@ long double ellint_3l(long double k, long double nu, long double phi);
6894
 
6895
  *Effects:* These functions compute the incomplete elliptic integral of
6896
  the third kind of their respective arguments `k`, `nu`, and `phi` (`phi`
6897
  measured in radians).
6898
 
6899
- *Returns:* $$%
6900
- \mathsf{\Pi}(\nu, k, \phi) =
6901
- \int_0^\phi \! \frac{ \mathsf{d}\theta }
6902
- { (1 - \nu \, \sin^2 \theta) \sqrt{1 - k^2 \sin^2 \theta} },
6903
- \quad \mbox{for $|k| \le 1$}$$ where $\nu$ is `nu`, k is `k`, and
6904
- φ is `phi`.
6905
 
6906
  #### Exponential integral <a id="sf.cmath.expint">[[sf.cmath.expint]]</a>
6907
 
6908
  ``` cpp
6909
  double expint(double x);
@@ -6949,15 +6372,13 @@ long double laguerrel(unsigned n, long double x);
6949
  ```
6950
 
6951
  *Effects:* These functions compute the Laguerre polynomials of their
6952
  respective arguments `n` and `x`.
6953
 
6954
- *Returns:* $$%
6955
- \mathsf{L}_n(x) =
6956
- \frac{e^x}{n!} \frac{ \mathsf{d} ^ n}
6957
- { \mathsf{d}x ^ n} \, (x^n e^{-x}),
6958
- \quad \mbox{for $x \ge 0$}$$ where n is `n` and x is `x`.
6959
 
6960
  *Remarks:* The effect of calling each of these functions is
6961
  *implementation-defined* if `n >= 128`.
6962
 
6963
  #### Legendre polynomials <a id="sf.cmath.legendre">[[sf.cmath.legendre]]</a>
@@ -6969,22 +6390,19 @@ long double legendrel(unsigned l, long double x);
6969
  ```
6970
 
6971
  *Effects:* These functions compute the Legendre polynomials of their
6972
  respective arguments `l` and `x`.
6973
 
6974
- *Returns:* $$%
6975
- \mathsf{P}_\ell(x) =
6976
- \frac{1}
6977
- {2^\ell \, \ell!}
6978
- \frac{ \mathsf{d} ^ \ell}
6979
- { \mathsf{d}x ^ \ell} \, (x^2 - 1) ^ \ell,
6980
- \quad \mbox{for $|x| \le 1$}$$ where l is `l` and x is `x`.
6981
 
6982
  *Remarks:* The effect of calling each of these functions is
6983
  *implementation-defined* if `l >= 128`.
6984
 
6985
- #### Riemann zeta function <a id="sf.cmath.riemann_zeta">[[sf.cmath.riemann_zeta]]</a>
6986
 
6987
  ``` cpp
6988
  double riemann_zeta(double x);
6989
  float riemann_zetaf(float x);
6990
  long double riemann_zetal(long double x);
@@ -7014,32 +6432,31 @@ respective arguments `x`.
7014
  & \mbox{for $x < 0$}
7015
  \end{array}
7016
  \right.
7017
  \;$$ where x is `x`.
7018
 
7019
- #### Spherical Bessel functions of the first kind <a id="sf.cmath.sph_bessel">[[sf.cmath.sph_bessel]]</a>
7020
 
7021
  ``` cpp
7022
  double sph_bessel(unsigned n, double x);
7023
  float sph_besself(unsigned n, float x);
7024
  long double sph_bessell(unsigned n, long double x);
7025
  ```
7026
 
7027
  *Effects:* These functions compute the spherical Bessel functions of the
7028
  first kind of their respective arguments `n` and `x`.
7029
 
7030
- *Returns:* $$%
7031
- \mathsf{j}_n(x) =
7032
- (\pi/2x)^{1\!/\!2} \mathsf{J}_{n + 1\!/\!2}(x),
7033
- \quad \mbox{for $x \ge 0$}$$ where n is `n` and x is `x`.
7034
 
7035
  *Remarks:* The effect of calling each of these functions is
7036
  *implementation-defined* if `n >= 128`.
7037
 
7038
- See also [[sf.cmath.cyl_bessel_j]].
7039
 
7040
- #### Spherical associated Legendre functions <a id="sf.cmath.sph_legendre">[[sf.cmath.sph_legendre]]</a>
7041
 
7042
  ``` cpp
7043
  double sph_legendre(unsigned l, unsigned m, double theta);
7044
  float sph_legendref(unsigned l, unsigned m, float theta);
7045
  long double sph_legendrel(unsigned l, unsigned m, long double theta);
@@ -7047,30 +6464,23 @@ long double sph_legendrel(unsigned l, unsigned m, long double theta);
7047
 
7048
  *Effects:* These functions compute the spherical associated Legendre
7049
  functions of their respective arguments `l`, `m`, and `theta` (`theta`
7050
  measured in radians).
7051
 
7052
- *Returns:* $$%
7053
- \mathsf{Y}_\ell^m(\theta, 0)
7054
- \;$$ where $$%
7055
- \mathsf{Y}_\ell^m(\theta, \phi) =
7056
- (-1)^m \left[ \frac{(2 \ell + 1)}
7057
- {4 \pi}
7058
- \frac{(\ell - m)!}
7059
- {(\ell + m)!}
7060
- \right]^{1/2}
7061
- \mathsf{P}_\ell^m
7062
- ( \cos\theta ) e ^ {i m \phi},
7063
- \quad \mbox{for $|m| \le \ell$}$$ and l is `l`, m is `m`, and θ
7064
  is `theta`.
7065
 
7066
  *Remarks:* The effect of calling each of these functions is
7067
  *implementation-defined* if `l >= 128`.
7068
 
7069
- See also [[sf.cmath.assoc_legendre]].
7070
 
7071
- #### Spherical Neumann functions <a id="sf.cmath.sph_neumann">[[sf.cmath.sph_neumann]]</a>
7072
 
7073
  ``` cpp
7074
  double sph_neumann(unsigned n, double x);
7075
  float sph_neumannf(unsigned n, float x);
7076
  long double sph_neumannl(unsigned n, long double x);
@@ -7078,32 +6488,103 @@ long double sph_neumannl(unsigned n, long double x);
7078
 
7079
  *Effects:* These functions compute the spherical Neumann functions, also
7080
  known as the spherical Bessel functions of the second kind, of their
7081
  respective arguments `n` and `x`.
7082
 
7083
- *Returns:* $$%
7084
- \mathsf{n}_n(x) =
7085
- (\pi/2x)^{1\!/\!2} \mathsf{N}_{n + 1\!/\!2}(x),
7086
- \quad \mbox{for $x \ge 0$}$$ where n is `n` and x is `x`.
7087
 
7088
  *Remarks:* The effect of calling each of these functions is
7089
  *implementation-defined* if `n >= 128`.
7090
 
7091
- See also [[sf.cmath.cyl_neumann]].
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7092
 
7093
  <!-- Link reference definitions -->
7094
- [accumulate]: #accumulate
7095
- [adjacent.difference]: #adjacent.difference
7096
- [algorithms]: algorithms.md#algorithms
7097
- [bad.alloc]: language.md#bad.alloc
7098
  [basic.fundamental]: basic.md#basic.fundamental
7099
  [basic.stc.thread]: basic.md#basic.stc.thread
7100
  [basic.types]: basic.md#basic.types
 
 
 
 
 
 
 
 
7101
  [c.math]: #c.math
7102
  [c.math.abs]: #c.math.abs
7103
  [c.math.fpclass]: #c.math.fpclass
7104
  [c.math.hypot3]: #c.math.hypot3
 
7105
  [c.math.rand]: #c.math.rand
7106
  [cfenv]: #cfenv
7107
  [cfenv.syn]: #cfenv.syn
7108
  [class.gslice]: #class.gslice
7109
  [class.gslice.overview]: #class.gslice.overview
@@ -7120,49 +6601,47 @@ See also [[sf.cmath.cyl_neumann]].
7120
  [complex.special]: #complex.special
7121
  [complex.syn]: #complex.syn
7122
  [complex.transcendentals]: #complex.transcendentals
7123
  [complex.value.ops]: #complex.value.ops
7124
  [cons.slice]: #cons.slice
7125
- [conv.prom]: conv.md#conv.prom
7126
  [cpp.pragma]: cpp.md#cpp.pragma
7127
- [cstdlib.syn]: language.md#cstdlib.syn
7128
- [dcl.array]: dcl.md#dcl.array
 
7129
  [dcl.init]: dcl.md#dcl.init
7130
- [exclusive.scan]: #exclusive.scan
7131
- [function.objects]: utilities.md#function.objects
7132
  [gslice.access]: #gslice.access
7133
  [gslice.array.assign]: #gslice.array.assign
7134
  [gslice.array.comp.assign]: #gslice.array.comp.assign
7135
  [gslice.array.fill]: #gslice.array.fill
7136
  [gslice.cons]: #gslice.cons
7137
  [implimits]: limits.md#implimits
7138
- [inclusive.scan]: #inclusive.scan
7139
  [indirect.array.assign]: #indirect.array.assign
7140
  [indirect.array.comp.assign]: #indirect.array.comp.assign
7141
  [indirect.array.fill]: #indirect.array.fill
7142
- [inner.product]: #inner.product
7143
  [input.iterators]: iterators.md#input.iterators
7144
  [input.output]: input.md#input.output
 
7145
  [iostate.flags]: input.md#iostate.flags
7146
  [istream.formatted]: input.md#istream.formatted
 
7147
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
7148
  [library.c]: library.md#library.c
7149
  [mask.array.assign]: #mask.array.assign
7150
  [mask.array.comp.assign]: #mask.array.comp.assign
7151
  [mask.array.fill]: #mask.array.fill
 
 
7152
  [numarray]: #numarray
7153
- [numeric.iota]: #numeric.iota
7154
- [numeric.ops]: #numeric.ops
7155
- [numeric.ops.gcd]: #numeric.ops.gcd
7156
- [numeric.ops.lcm]: #numeric.ops.lcm
7157
- [numeric.ops.overview]: #numeric.ops.overview
7158
  [numeric.requirements]: #numeric.requirements
7159
  [numerics]: #numerics
7160
- [numerics.defns]: #numerics.defns
7161
  [numerics.general]: #numerics.general
 
7162
  [output.iterators]: iterators.md#output.iterators
7163
- [partial.sum]: #partial.sum
7164
  [rand]: #rand
7165
  [rand.adapt]: #rand.adapt
7166
  [rand.adapt.disc]: #rand.adapt.disc
7167
  [rand.adapt.general]: #rand.adapt.general
7168
  [rand.adapt.ibits]: #rand.adapt.ibits
@@ -7210,64 +6689,52 @@ See also [[sf.cmath.cyl_neumann]].
7210
  [rand.synopsis]: #rand.synopsis
7211
  [rand.util]: #rand.util
7212
  [rand.util.canonical]: #rand.util.canonical
7213
  [rand.util.seedseq]: #rand.util.seedseq
7214
  [random.access.iterators]: iterators.md#random.access.iterators
7215
- [reduce]: #reduce
7216
  [res.on.data.races]: library.md#res.on.data.races
7217
  [sf.cmath]: #sf.cmath
7218
- [sf.cmath.assoc_laguerre]: #sf.cmath.assoc_laguerre
7219
- [sf.cmath.assoc_legendre]: #sf.cmath.assoc_legendre
7220
  [sf.cmath.beta]: #sf.cmath.beta
7221
- [sf.cmath.comp_ellint_1]: #sf.cmath.comp_ellint_1
7222
- [sf.cmath.comp_ellint_2]: #sf.cmath.comp_ellint_2
7223
- [sf.cmath.comp_ellint_3]: #sf.cmath.comp_ellint_3
7224
- [sf.cmath.cyl_bessel_i]: #sf.cmath.cyl_bessel_i
7225
- [sf.cmath.cyl_bessel_j]: #sf.cmath.cyl_bessel_j
7226
- [sf.cmath.cyl_bessel_k]: #sf.cmath.cyl_bessel_k
7227
- [sf.cmath.cyl_neumann]: #sf.cmath.cyl_neumann
7228
- [sf.cmath.ellint_1]: #sf.cmath.ellint_1
7229
- [sf.cmath.ellint_2]: #sf.cmath.ellint_2
7230
- [sf.cmath.ellint_3]: #sf.cmath.ellint_3
7231
  [sf.cmath.expint]: #sf.cmath.expint
7232
  [sf.cmath.hermite]: #sf.cmath.hermite
7233
  [sf.cmath.laguerre]: #sf.cmath.laguerre
7234
  [sf.cmath.legendre]: #sf.cmath.legendre
7235
- [sf.cmath.riemann_zeta]: #sf.cmath.riemann_zeta
7236
- [sf.cmath.sph_bessel]: #sf.cmath.sph_bessel
7237
- [sf.cmath.sph_legendre]: #sf.cmath.sph_legendre
7238
- [sf.cmath.sph_neumann]: #sf.cmath.sph_neumann
7239
  [slice.access]: #slice.access
7240
  [slice.arr.assign]: #slice.arr.assign
7241
  [slice.arr.comp.assign]: #slice.arr.comp.assign
7242
  [slice.arr.fill]: #slice.arr.fill
 
7243
  [strings]: strings.md#strings
7244
- [tab:RandomDistribution]: #tab:RandomDistribution
7245
- [tab:RandomEngine]: #tab:RandomEngine
7246
- [tab:SeedSequence]: #tab:SeedSequence
7247
- [tab:UniformRandomBitGenerator]: #tab:UniformRandomBitGenerator
7248
- [tab:copyassignable]: #tab:copyassignable
7249
- [tab:copyconstructible]: #tab:copyconstructible
7250
- [tab:equalitycomparable]: #tab:equalitycomparable
7251
- [tab:iterator.input.requirements]: iterators.md#tab:iterator.input.requirements
7252
- [tab:moveassignable]: #tab:moveassignable
7253
- [tab:moveconstructible]: #tab:moveconstructible
7254
- [tab:numerics.lib.summary]: #tab:numerics.lib.summary
7255
  [template.gslice.array]: #template.gslice.array
7256
  [template.gslice.array.overview]: #template.gslice.array.overview
7257
  [template.indirect.array]: #template.indirect.array
7258
  [template.indirect.array.overview]: #template.indirect.array.overview
7259
  [template.mask.array]: #template.mask.array
7260
  [template.mask.array.overview]: #template.mask.array.overview
7261
  [template.slice.array]: #template.slice.array
7262
  [template.slice.array.overview]: #template.slice.array.overview
7263
  [template.valarray]: #template.valarray
7264
  [template.valarray.overview]: #template.valarray.overview
 
7265
  [thread.thread.class]: thread.md#thread.thread.class
7266
- [transform.exclusive.scan]: #transform.exclusive.scan
7267
- [transform.inclusive.scan]: #transform.inclusive.scan
7268
- [transform.reduce]: #transform.reduce
7269
  [valarray.access]: #valarray.access
7270
  [valarray.assign]: #valarray.assign
7271
  [valarray.binary]: #valarray.binary
7272
  [valarray.cassign]: #valarray.cassign
7273
  [valarray.comparison]: #valarray.comparison
@@ -7278,11 +6745,10 @@ See also [[sf.cmath.cyl_neumann]].
7278
  [valarray.special]: #valarray.special
7279
  [valarray.sub]: #valarray.sub
7280
  [valarray.syn]: #valarray.syn
7281
  [valarray.transcend]: #valarray.transcend
7282
  [valarray.unary]: #valarray.unary
7283
- [vector]: containers.md#vector
7284
 
7285
  [^1]: In other words, value types. These include arithmetic types,
7286
  pointers, the library class `complex`, and instantiations of
7287
  `valarray` for value types.
7288
 
@@ -7303,17 +6769,17 @@ See also [[sf.cmath.cyl_neumann]].
7303
  [^6]: The distribution corresponding to this probability density
7304
  function is also known (with a possible change of variable) as the
7305
  Gumbel Type I, the log-Weibull, or the Fisher-Tippett Type I
7306
  distribution.
7307
 
7308
- [^7]: Annex  [[implimits]] recommends a minimum number of recursively
7309
- nested template instantiations. This requirement thus indirectly
7310
- suggests a minimum allowable complexity for valarray expressions.
7311
 
7312
  [^8]: The intent is to specify an array template that has the minimum
7313
  functionality necessary to address aliasing ambiguities and the
7314
- proliferation of temporaries. Thus, the `valarray` template is
7315
  neither a matrix class nor a field class. However, it is a very
7316
  useful building block for designing such classes.
7317
 
7318
  [^9]: This default constructor is essential, since arrays of `valarray`
7319
  may be useful. After initialization, the length of an empty array
@@ -7322,32 +6788,19 @@ See also [[sf.cmath.cyl_neumann]].
7322
  [^10]: This constructor is the preferred method for converting a C array
7323
  to a `valarray` object.
7324
 
7325
  [^11]: This copy constructor creates a distinct array rather than an
7326
  alias. Implementations in which arrays share storage are permitted,
7327
- but they shall implement a copy-on-reference mechanism to ensure
7328
- that arrays are conceptually distinct.
7329
 
7330
  [^12]: BLAS stands for *Basic Linear Algebra Subprograms.* C++ programs
7331
  may instantiate this class. See, for example, Dongarra, Du Croz,
7332
  Duff, and Hammerling: *A set of Level 3 Basic Linear Algebra
7333
  Subprograms*; Technical Report MCS-P1-0888, Argonne National
7334
  Laboratory (USA), Mathematics and Computer Science Division, August,
7335
  1988.
7336
 
7337
- [^13]: The use of fully closed ranges is intentional.
7338
-
7339
- [^14]: `accumulate` is similar to the APL reduction operator and Common
7340
- Lisp reduce function, but it avoids the difficulty of defining the
7341
- result of reduction on an empty sequence by always requiring an
7342
- initial value.
7343
-
7344
- [^15]: The use of fully closed ranges is intentional.
7345
-
7346
- [^16]: The use of fully closed ranges is intentional.
7347
-
7348
- [^17]: The use of fully closed ranges is intentional.
7349
-
7350
- [^18]: A mathematical function is mathematically defined for a given set
7351
  of argument values (a) if it is explicitly defined for that set of
7352
  argument values, or (b) if its limiting value exists and does not
7353
  depend on the direction of approach.
 
5
  This Clause describes components that C++ programs may use to perform
6
  seminumerical operations.
7
 
8
  The following subclauses describe components for complex number types,
9
  random number generation, numeric ( *n*-at-a-time) arrays, generalized
10
+ numeric algorithms, and mathematical constants and functions for
11
+ floating-point types, as summarized in [[numerics.summary]].
12
 
13
+ **Table: Numerics library summary** <a id="numerics.summary">[numerics.summary]</a>
14
 
15
  | Subclause | | Header |
16
+ | ------------------------ | ----------------------------------------------- | ---------------------- |
 
17
  | [[numeric.requirements]] | Requirements | |
18
  | [[cfenv]] | Floating-point environment | `<cfenv>` |
19
  | [[complex.numbers]] | Complex numbers | `<complex>` |
20
+ | [[bit]] | Bit manipulation | `<bit>` |
21
  | [[rand]] | Random number generation | `<random>` |
22
  | [[numarray]] | Numeric arrays | `<valarray>` |
23
+ | [[c.math]] | Mathematical functions for floating-point types | `<cmath>`, `<cstdlib>` |
24
+ | [[numbers]] | Numbers | `<numbers>` |
 
25
 
26
 
 
 
 
 
 
 
 
 
 
 
 
 
 
27
  ## Numeric type requirements <a id="numeric.requirements">[[numeric.requirements]]</a>
28
 
29
  The `complex` and `valarray` components are parameterized by the type of
30
  information they contain and manipulate. A C++ program shall instantiate
31
+ these components only with a numeric type. A *numeric type* is a
32
+ cv-unqualified object type `T` that meets the
33
+ *Cpp17DefaultConstructible*, *Cpp17CopyConstructible*,
34
+ *Cpp17CopyAssignable*, and *Cpp17Destructible* requirements
35
+ [[utility.arg.requirements]]. [^1]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
36
 
37
  If any operation on `T` throws an exception the effects are undefined.
38
 
39
  In addition, many member and related functions of `valarray<T>` can be
40
  successfully instantiated and will exhibit well-defined behavior if and
41
+ only if `T` meets additional requirements specified for each such member
42
+ or related function.
43
 
44
+ [*Example 1*: It is valid to instantiate `valarray<complex>`, but
45
  `operator>()` will not be successfully instantiated for
46
  `valarray<complex>` operands, since `complex` does not have any ordering
47
  operators. — *end example*]
48
 
49
  ## The floating-point environment <a id="cfenv">[[cfenv]]</a>
50
 
51
  ### Header `<cfenv>` synopsis <a id="cfenv.syn">[[cfenv.syn]]</a>
52
 
53
  ``` cpp
54
  #define FE_ALL_EXCEPT see below
55
+ #define FE_DIVBYZERO see below // optional
56
+ #define FE_INEXACT see below // optional
57
+ #define FE_INVALID see below // optional
58
+ #define FE_OVERFLOW see below // optional
59
+ #define FE_UNDERFLOW see below // optional
60
 
61
+ #define FE_DOWNWARD see below // optional
62
+ #define FE_TONEAREST see below // optional
63
+ #define FE_TOWARDZERO see below // optional
64
+ #define FE_UPWARD see below // optional
65
 
66
  #define FE_DFL_ENV see below
67
 
68
  namespace std {
69
  // types
 
88
  ```
89
 
90
  The contents and meaning of the header `<cfenv>` are the same as the C
91
  standard library header `<fenv.h>`.
92
 
93
+ [*Note 1*: This document does not require an implementation to support
94
+ the `FENV_ACCESS` pragma; it is *implementation-defined* [[cpp.pragma]]
95
+ whether the pragma is supported. As a consequence, it is
96
+ *implementation-defined* whether these functions can be used to test
97
+ floating-point status flags, set floating-point control modes, or run
98
+ under non-default mode settings. If the pragma is used to enable control
99
+ over the floating-point environment, this document does not specify the
100
+ effect on floating-point evaluation in constant
101
+ expressions. — *end note*]
102
 
103
+ The floating-point environment has thread storage duration
104
+ [[basic.stc.thread]]. The initial state for a thread’s floating-point
105
  environment is the state of the floating-point environment of the thread
106
+ that constructs the corresponding `thread` object
107
+ [[thread.thread.class]] or `jthread` object [[thread.jthread.class]] at
108
+ the time it constructed the object.
109
 
110
  [*Note 2*: That is, the child thread gets the floating-point state of
111
  the parent thread at the time of the child’s creation. — *end note*]
112
 
113
+ A separate floating-point environment is maintained for each thread.
114
+ Each function accesses the environment corresponding to its calling
115
+ thread.
116
 
117
+ See also: ISO C 7.6
118
 
119
  ## Complex numbers <a id="complex.numbers">[[complex.numbers]]</a>
120
 
121
  The header `<complex>` defines a class template, and numerous functions
122
  for representing and manipulating complex numbers.
123
 
124
  The effect of instantiating the template `complex` for any type other
125
  than `float`, `double`, or `long double` is unspecified. The
126
  specializations `complex<float>`, `complex<double>`, and
127
+ `complex<long double>` are literal types [[basic.types]].
128
 
129
  If the result of a function is not mathematically defined or not in the
130
  range of representable values for its type, the behavior is undefined.
131
 
132
+ If `z` is an lvalue of type cv `complex<T>` then:
133
 
134
+ - the expression `reinterpret_cast<cv T(&)[2]>(z)` is well-formed,
135
+ - `reinterpret_cast<cv T(&)[2]>(z)[0]` designates the real part of `z`,
136
+ and
137
+ - `reinterpret_cast<cv T(&)[2]>(z)[1]` designates the imaginary part of
138
+ `z`.
139
 
140
  Moreover, if `a` is an expression of type cv `complex<T>*` and the
141
  expression `a[i]` is well-defined for an integer expression `i`, then:
142
 
143
+ - `reinterpret_cast<cv T*>(a)[2*i]` designates the real part of `a[i]`,
144
+ and
145
+ - `reinterpret_cast<cv T*>(a)[2*i + 1]` designates the imaginary part of
146
+ `a[i]`.
147
 
148
  ### Header `<complex>` synopsis <a id="complex.syn">[[complex.syn]]</a>
149
 
150
  ``` cpp
151
  namespace std {
152
+ // [complex], class template complex
153
  template<class T> class complex;
154
+
155
+ // [complex.special], specializations
156
  template<> class complex<float>;
157
  template<> class complex<double>;
158
  template<> class complex<long double>;
159
 
160
  // [complex.ops], operators
161
+ template<class T> constexpr complex<T> operator+(const complex<T>&, const complex<T>&);
162
+ template<class T> constexpr complex<T> operator+(const complex<T>&, const T&);
163
+ template<class T> constexpr complex<T> operator+(const T&, const complex<T>&);
 
164
 
165
+ template<class T> constexpr complex<T> operator-(const complex<T>&, const complex<T>&);
166
+ template<class T> constexpr complex<T> operator-(const complex<T>&, const T&);
167
+ template<class T> constexpr complex<T> operator-(const T&, const complex<T>&);
 
168
 
169
+ template<class T> constexpr complex<T> operator*(const complex<T>&, const complex<T>&);
170
+ template<class T> constexpr complex<T> operator*(const complex<T>&, const T&);
171
+ template<class T> constexpr complex<T> operator*(const T&, const complex<T>&);
 
172
 
173
+ template<class T> constexpr complex<T> operator/(const complex<T>&, const complex<T>&);
174
+ template<class T> constexpr complex<T> operator/(const complex<T>&, const T&);
175
+ template<class T> constexpr complex<T> operator/(const T&, const complex<T>&);
 
176
 
177
+ template<class T> constexpr complex<T> operator+(const complex<T>&);
178
+ template<class T> constexpr complex<T> operator-(const complex<T>&);
179
 
180
+ template<class T> constexpr bool operator==(const complex<T>&, const complex<T>&);
 
181
  template<class T> constexpr bool operator==(const complex<T>&, const T&);
 
 
 
 
 
182
 
183
  template<class T, class charT, class traits>
184
+ basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, complex<T>&);
 
185
 
186
  template<class T, class charT, class traits>
187
+ basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const complex<T>&);
 
188
 
189
  // [complex.value.ops], values
190
  template<class T> constexpr T real(const complex<T>&);
191
  template<class T> constexpr T imag(const complex<T>&);
192
 
193
  template<class T> T abs(const complex<T>&);
194
  template<class T> T arg(const complex<T>&);
195
+ template<class T> constexpr T norm(const complex<T>&);
196
 
197
+ template<class T> constexpr complex<T> conj(const complex<T>&);
198
  template<class T> complex<T> proj(const complex<T>&);
199
+ template<class T> complex<T> polar(const T&, const T& = T());
200
 
201
  // [complex.transcendentals], transcendentals
202
  template<class T> complex<T> acos(const complex<T>&);
203
  template<class T> complex<T> asin(const complex<T>&);
204
  template<class T> complex<T> atan(const complex<T>&);
 
239
 
240
  ### Class template `complex` <a id="complex">[[complex]]</a>
241
 
242
  ``` cpp
243
  namespace std {
244
+ template<class T> class complex {
 
245
  public:
246
  using value_type = T;
247
 
248
  constexpr complex(const T& re = T(), const T& im = T());
249
  constexpr complex(const complex&);
250
  template<class X> constexpr complex(const complex<X>&);
251
 
252
  constexpr T real() const;
253
+ constexpr void real(T);
254
  constexpr T imag() const;
255
+ constexpr void imag(T);
256
 
257
+ constexpr complex& operator= (const T&);
258
+ constexpr complex& operator+=(const T&);
259
+ constexpr complex& operator-=(const T&);
260
+ constexpr complex& operator*=(const T&);
261
+ constexpr complex& operator/=(const T&);
262
 
263
+ constexpr complex& operator=(const complex&);
264
+ template<class X> constexpr complex& operator= (const complex<X>&);
265
+ template<class X> constexpr complex& operator+=(const complex<X>&);
266
+ template<class X> constexpr complex& operator-=(const complex<X>&);
267
+ template<class X> constexpr complex& operator*=(const complex<X>&);
268
+ template<class X> constexpr complex& operator/=(const complex<X>&);
269
  };
270
  }
271
  ```
272
 
273
  The class `complex` describes an object that can store the Cartesian
274
  components, `real()` and `imag()`, of a complex number.
275
 
276
+ ### Specializations <a id="complex.special">[[complex.special]]</a>
277
 
278
  ``` cpp
279
  namespace std {
280
  template<> class complex<float> {
281
  public:
282
  using value_type = float;
283
 
284
  constexpr complex(float re = 0.0f, float im = 0.0f);
285
+ constexpr complex(const complex<float>&) = default;
286
  constexpr explicit complex(const complex<double>&);
287
  constexpr explicit complex(const complex<long double>&);
288
 
289
  constexpr float real() const;
290
+ constexpr void real(float);
291
  constexpr float imag() const;
292
+ constexpr void imag(float);
293
 
294
+ constexpr complex& operator= (float);
295
+ constexpr complex& operator+=(float);
296
+ constexpr complex& operator-=(float);
297
+ constexpr complex& operator*=(float);
298
+ constexpr complex& operator/=(float);
299
 
300
+ constexpr complex& operator=(const complex&);
301
+ template<class X> constexpr complex& operator= (const complex<X>&);
302
+ template<class X> constexpr complex& operator+=(const complex<X>&);
303
+ template<class X> constexpr complex& operator-=(const complex<X>&);
304
+ template<class X> constexpr complex& operator*=(const complex<X>&);
305
+ template<class X> constexpr complex& operator/=(const complex<X>&);
306
  };
307
 
308
  template<> class complex<double> {
309
  public:
310
  using value_type = double;
311
 
312
  constexpr complex(double re = 0.0, double im = 0.0);
313
  constexpr complex(const complex<float>&);
314
+ constexpr complex(const complex<double>&) = default;
315
  constexpr explicit complex(const complex<long double>&);
316
 
317
  constexpr double real() const;
318
+ constexpr void real(double);
319
  constexpr double imag() const;
320
+ constexpr void imag(double);
321
 
322
+ constexpr complex& operator= (double);
323
+ constexpr complex& operator+=(double);
324
+ constexpr complex& operator-=(double);
325
+ constexpr complex& operator*=(double);
326
+ constexpr complex& operator/=(double);
327
 
328
+ constexpr complex& operator=(const complex&);
329
+ template<class X> constexpr complex& operator= (const complex<X>&);
330
+ template<class X> constexpr complex& operator+=(const complex<X>&);
331
+ template<class X> constexpr complex& operator-=(const complex<X>&);
332
+ template<class X> constexpr complex& operator*=(const complex<X>&);
333
+ template<class X> constexpr complex& operator/=(const complex<X>&);
334
  };
335
 
336
  template<> class complex<long double> {
337
  public:
338
  using value_type = long double;
339
 
340
  constexpr complex(long double re = 0.0L, long double im = 0.0L);
341
  constexpr complex(const complex<float>&);
342
  constexpr complex(const complex<double>&);
343
+ constexpr complex(const complex<long double>&) = default;
344
 
345
  constexpr long double real() const;
346
+ constexpr void real(long double);
347
  constexpr long double imag() const;
348
+ constexpr void imag(long double);
349
 
350
+ constexpr complex& operator= (long double);
351
+ constexpr complex& operator+=(long double);
352
+ constexpr complex& operator-=(long double);
353
+ constexpr complex& operator*=(long double);
354
+ constexpr complex& operator/=(long double);
 
355
 
356
+ constexpr complex& operator=(const complex&);
357
+ template<class X> constexpr complex& operator= (const complex<X>&);
358
+ template<class X> constexpr complex& operator+=(const complex<X>&);
359
+ template<class X> constexpr complex& operator-=(const complex<X>&);
360
+ template<class X> constexpr complex& operator*=(const complex<X>&);
361
+ template<class X> constexpr complex& operator/=(const complex<X>&);
362
  };
363
  }
364
  ```
365
 
366
+ ### Member functions <a id="complex.members">[[complex.members]]</a>
367
 
368
  ``` cpp
369
  template<class T> constexpr complex(const T& re = T(), const T& im = T());
370
  ```
371
 
372
+ *Ensures:* `real() == re && imag() == im` is `true`.
 
 
373
 
374
  ``` cpp
375
  constexpr T real() const;
376
  ```
377
 
378
  *Returns:* The value of the real component.
379
 
380
  ``` cpp
381
+ constexpr void real(T val);
382
  ```
383
 
384
  *Effects:* Assigns `val` to the real component.
385
 
386
  ``` cpp
 
388
  ```
389
 
390
  *Returns:* The value of the imaginary component.
391
 
392
  ``` cpp
393
+ constexpr void imag(T val);
394
  ```
395
 
396
  *Effects:* Assigns `val` to the imaginary component.
397
 
398
+ ### Member operators <a id="complex.member.ops">[[complex.member.ops]]</a>
399
 
400
  ``` cpp
401
+ constexpr complex& operator+=(const T& rhs);
402
  ```
403
 
404
  *Effects:* Adds the scalar value `rhs` to the real part of the complex
405
  value `*this` and stores the result in the real part of `*this`, leaving
406
  the imaginary part unchanged.
407
 
408
  *Returns:* `*this`.
409
 
410
  ``` cpp
411
+ constexpr complex& operator-=(const T& rhs);
412
  ```
413
 
414
  *Effects:* Subtracts the scalar value `rhs` from the real part of the
415
  complex value `*this` and stores the result in the real part of `*this`,
416
  leaving the imaginary part unchanged.
417
 
418
  *Returns:* `*this`.
419
 
420
  ``` cpp
421
+ constexpr complex& operator*=(const T& rhs);
422
  ```
423
 
424
  *Effects:* Multiplies the scalar value `rhs` by the complex value
425
  `*this` and stores the result in `*this`.
426
 
427
  *Returns:* `*this`.
428
 
429
  ``` cpp
430
+ constexpr complex& operator/=(const T& rhs);
431
  ```
432
 
433
  *Effects:* Divides the scalar value `rhs` into the complex value `*this`
434
  and stores the result in `*this`.
435
 
436
  *Returns:* `*this`.
437
 
438
  ``` cpp
439
+ template<class X> constexpr complex& operator+=(const complex<X>& rhs);
440
  ```
441
 
442
  *Effects:* Adds the complex value `rhs` to the complex value `*this` and
443
  stores the sum in `*this`.
444
 
445
  *Returns:* `*this`.
446
 
447
  ``` cpp
448
+ template<class X> constexpr complex& operator-=(const complex<X>& rhs);
449
  ```
450
 
451
  *Effects:* Subtracts the complex value `rhs` from the complex value
452
  `*this` and stores the difference in `*this`.
453
 
454
  *Returns:* `*this`.
455
 
456
  ``` cpp
457
+ template<class X> constexpr complex& operator*=(const complex<X>& rhs);
458
  ```
459
 
460
  *Effects:* Multiplies the complex value `rhs` by the complex value
461
  `*this` and stores the product in `*this`.
462
 
463
  *Returns:* `*this`.
464
 
465
  ``` cpp
466
+ template<class X> constexpr complex& operator/=(const complex<X>& rhs);
467
  ```
468
 
469
  *Effects:* Divides the complex value `rhs` into the complex value
470
  `*this` and stores the quotient in `*this`.
471
 
472
  *Returns:* `*this`.
473
 
474
+ ### Non-member operations <a id="complex.ops">[[complex.ops]]</a>
475
 
476
  ``` cpp
477
+ template<class T> constexpr complex<T> operator+(const complex<T>& lhs);
478
  ```
479
 
480
  *Returns:* `complex<T>(lhs)`.
481
 
 
 
482
  ``` cpp
483
+ template<class T> constexpr complex<T> operator+(const complex<T>& lhs, const complex<T>& rhs);
484
+ template<class T> constexpr complex<T> operator+(const complex<T>& lhs, const T& rhs);
485
+ template<class T> constexpr complex<T> operator+(const T& lhs, const complex<T>& rhs);
486
  ```
487
 
488
  *Returns:* `complex<T>(lhs) += rhs`.
489
 
490
  ``` cpp
491
+ template<class T> constexpr complex<T> operator-(const complex<T>& lhs);
492
  ```
493
 
494
  *Returns:* `complex<T>(-lhs.real(),-lhs.imag())`.
495
 
 
 
496
  ``` cpp
497
+ template<class T> constexpr complex<T> operator-(const complex<T>& lhs, const complex<T>& rhs);
498
+ template<class T> constexpr complex<T> operator-(const complex<T>& lhs, const T& rhs);
499
+ template<class T> constexpr complex<T> operator-(const T& lhs, const complex<T>& rhs);
500
  ```
501
 
502
  *Returns:* `complex<T>(lhs) -= rhs`.
503
 
504
  ``` cpp
505
+ template<class T> constexpr complex<T> operator*(const complex<T>& lhs, const complex<T>& rhs);
506
+ template<class T> constexpr complex<T> operator*(const complex<T>& lhs, const T& rhs);
507
+ template<class T> constexpr complex<T> operator*(const T& lhs, const complex<T>& rhs);
508
  ```
509
 
510
  *Returns:* `complex<T>(lhs) *= rhs`.
511
 
512
  ``` cpp
513
+ template<class T> constexpr complex<T> operator/(const complex<T>& lhs, const complex<T>& rhs);
514
+ template<class T> constexpr complex<T> operator/(const complex<T>& lhs, const T& rhs);
515
+ template<class T> constexpr complex<T> operator/(const T& lhs, const complex<T>& rhs);
516
  ```
517
 
518
  *Returns:* `complex<T>(lhs) /= rhs`.
519
 
520
  ``` cpp
521
  template<class T> constexpr bool operator==(const complex<T>& lhs, const complex<T>& rhs);
522
  template<class T> constexpr bool operator==(const complex<T>& lhs, const T& rhs);
 
523
  ```
524
 
525
  *Returns:* `lhs.real() == rhs.real() && lhs.imag() == rhs.imag()`.
526
 
527
  *Remarks:* The imaginary part is assumed to be `T()`, or 0.0, for the
528
  `T` arguments.
529
 
 
 
 
 
 
 
 
 
530
  ``` cpp
531
  template<class T, class charT, class traits>
532
+ basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, complex<T>& x);
 
533
  ```
534
 
535
+ *Preconditions:* The input values are convertible to `T`.
536
 
537
  *Effects:* Extracts a complex number `x` of the form: `u`, `(u)`, or
538
  `(u,v)`, where `u` is the real part and `v` is the imaginary
539
+ part [[istream.formatted]].
540
 
541
  If bad input is encountered, calls `is.setstate(ios_base::failbit)`
542
+ (which may throw `ios_base::failure` [[iostate.flags]]).
543
 
544
  *Returns:* `is`.
545
 
546
  *Remarks:* This extraction is performed as a series of simpler
547
  extractions. Therefore, the skipping of whitespace is specified to be
548
  the same for each of the simpler extractions.
549
 
550
  ``` cpp
551
  template<class T, class charT, class traits>
552
+ basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& o, const complex<T>& x);
 
553
  ```
554
 
555
  *Effects:* Inserts the complex number `x` onto the stream `o` as if it
556
  were implemented as follows:
557
 
 
568
  character, the use of comma as a field separator can be ambiguous.
569
  Inserting `showpoint` into the output stream forces all outputs to show
570
  an explicit decimal point character; as a result, all inserted sequences
571
  of complex numbers can be extracted unambiguously. — *end note*]
572
 
573
+ ### Value operations <a id="complex.value.ops">[[complex.value.ops]]</a>
574
 
575
  ``` cpp
576
  template<class T> constexpr T real(const complex<T>& x);
577
  ```
578
 
 
595
  ```
596
 
597
  *Returns:* The phase angle of `x`, or `atan2(imag(x), real(x))`.
598
 
599
  ``` cpp
600
+ template<class T> constexpr T norm(const complex<T>& x);
601
  ```
602
 
603
  *Returns:* The squared magnitude of `x`.
604
 
605
  ``` cpp
606
+ template<class T> constexpr complex<T> conj(const complex<T>& x);
607
  ```
608
 
609
  *Returns:* The complex conjugate of `x`.
610
 
611
  ``` cpp
612
  template<class T> complex<T> proj(const complex<T>& x);
613
  ```
614
 
615
  *Returns:* The projection of `x` onto the Riemann sphere.
616
 
617
+ *Remarks:* Behaves the same as the C function `cproj`. See also: ISO C
618
+ 7.3.9.5
619
 
620
  ``` cpp
621
+ template<class T> complex<T> polar(const T& rho, const T& theta = T());
622
  ```
623
 
624
+ *Preconditions:* `rho` is non-negative and non-NaN. `theta` is finite.
 
625
 
626
  *Returns:* The `complex` value corresponding to a complex number whose
627
  magnitude is `rho` and whose phase angle is `theta`.
628
 
629
+ ### Transcendentals <a id="complex.transcendentals">[[complex.transcendentals]]</a>
630
 
631
  ``` cpp
632
  template<class T> complex<T> acos(const complex<T>& x);
633
  ```
634
 
635
  *Returns:* The complex arc cosine of `x`.
636
 
637
+ *Remarks:* Behaves the same as the C function `cacos`. See also: ISO C
638
+ 7.3.5.1
639
 
640
  ``` cpp
641
  template<class T> complex<T> asin(const complex<T>& x);
642
  ```
643
 
644
  *Returns:* The complex arc sine of `x`.
645
 
646
+ *Remarks:* Behaves the same as the C function `casin`. See also: ISO C
647
+ 7.3.5.2
648
 
649
  ``` cpp
650
  template<class T> complex<T> atan(const complex<T>& x);
651
  ```
652
 
653
  *Returns:* The complex arc tangent of `x`.
654
 
655
+ *Remarks:* Behaves the same as the C function `catan`. See also: ISO C
656
+ 7.3.5.3
657
 
658
  ``` cpp
659
  template<class T> complex<T> acosh(const complex<T>& x);
660
  ```
661
 
662
  *Returns:* The complex arc hyperbolic cosine of `x`.
663
 
664
+ *Remarks:* Behaves the same as the C function `cacosh`. See also: ISO C
665
+ 7.3.6.1
666
 
667
  ``` cpp
668
  template<class T> complex<T> asinh(const complex<T>& x);
669
  ```
670
 
671
  *Returns:* The complex arc hyperbolic sine of `x`.
672
 
673
+ *Remarks:* Behaves the same as the C function `casinh`. See also: ISO C
674
+ 7.3.6.2
675
 
676
  ``` cpp
677
  template<class T> complex<T> atanh(const complex<T>& x);
678
  ```
679
 
680
  *Returns:* The complex arc hyperbolic tangent of `x`.
681
 
682
+ *Remarks:* Behaves the same as the C function `catanh`. See also: ISO C
683
+ 7.3.6.3
684
 
685
  ``` cpp
686
  template<class T> complex<T> cos(const complex<T>& x);
687
  ```
688
 
 
703
  ``` cpp
704
  template<class T> complex<T> log(const complex<T>& x);
705
  ```
706
 
707
  *Returns:* The complex natural (base-e) logarithm of `x`. For all `x`,
708
+ `imag(log(x))` lies in the interval \[-π, π\].
709
+
710
+ [*Note 1*: The semantics of this function are intended to be the same
711
+ in C++ as they are for `clog` in C. — *end note*]
712
 
713
  *Remarks:* The branch cuts are along the negative real axis.
714
 
715
  ``` cpp
716
  template<class T> complex<T> log10(const complex<T>& x);
 
748
  ``` cpp
749
  template<class T> complex<T> sqrt(const complex<T>& x);
750
  ```
751
 
752
  *Returns:* The complex square root of `x`, in the range of the right
753
+ half-plane.
754
+
755
+ [*Note 2*: The semantics of this function are intended to be the same
756
+ in C++ as they are for `csqrt` in C. — *end note*]
757
 
758
  *Remarks:* The branch cuts are along the negative real axis.
759
 
760
  ``` cpp
761
  template<class T> complex<T> tan(const complex<T>& x);
 
777
  arg norm
778
  conj proj
779
  imag real
780
  ```
781
 
782
+ where `norm`, `conj`, `imag`, and `real` are `constexpr` overloads.
783
+
784
  The additional overloads shall be sufficient to ensure:
785
 
786
+ - If the argument has type `long double`, then it is effectively cast to
787
+ `complex<long double>`.
788
+ - Otherwise, if the argument has type `double` or an integer type, then
789
+ it is effectively cast to `complex<{}double>`.
790
+ - Otherwise, if the argument has type `float`, then it is effectively
791
  cast to `complex<float>`.
792
 
793
  Function template `pow` shall have additional overloads sufficient to
794
  ensure, for a call with at least one argument of type `complex<T>`:
795
 
796
+ - If either argument has type `complex<long double>` or type `long
797
  double`, then both arguments are effectively cast to
798
  `complex<long double>`.
799
+ - Otherwise, if either argument has type `complex<double>`, `double`, or
800
+ an integer type, then both arguments are effectively cast to
801
  `complex<double>`.
802
+ - Otherwise, if either argument has type `complex<float>` or `float`,
803
  then both arguments are effectively cast to `complex<float>`.
804
 
805
  ### Suffixes for complex number literals <a id="complex.literals">[[complex.literals]]</a>
806
 
807
+ This subclause describes literal suffixes for constructing complex
808
+ number literals. The suffixes `i`, `il`, and `if` create complex numbers
809
+ of the types `complex<double>`, `complex<long double>`, and
810
+ `complex<float>` respectively, with their imaginary part denoted by the
811
+ given literal number and the real part being zero.
812
 
813
  ``` cpp
814
  constexpr complex<long double> operator""il(long double d);
815
  constexpr complex<long double> operator""il(unsigned long long d);
816
  ```
 
829
  constexpr complex<float> operator""if(unsigned long long d);
830
  ```
831
 
832
  *Returns:* `complex<float>{0.0f, static_cast<float>(d)}`.
833
 
834
+ ## Bit manipulation <a id="bit">[[bit]]</a>
835
+
836
+ ### General <a id="bit.general">[[bit.general]]</a>
837
+
838
+ The header `<bit>` provides components to access, manipulate and process
839
+ both individual bits and bit sequences.
840
+
841
+ ### Header `<bit>` synopsis <a id="bit.syn">[[bit.syn]]</a>
842
+
843
+ ``` cpp
844
+ namespace std {
845
+ // [bit.cast], bit_cast
846
+ template<class To, class From>
847
+ constexpr To bit_cast(const From& from) noexcept;
848
+
849
+ // [bit.pow.two], integral powers of 2
850
+ template<class T>
851
+ constexpr bool has_single_bit(T x) noexcept;
852
+ template<class T>
853
+ constexpr T bit_ceil(T x);
854
+ template<class T>
855
+ constexpr T bit_floor(T x) noexcept;
856
+ template<class T>
857
+ constexpr T bit_width(T x) noexcept;
858
+
859
+ // [bit.rotate], rotating
860
+ template<class T>
861
+ [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
862
+ template<class T>
863
+ [[nodiscard]] constexpr T rotr(T x, int s) noexcept;
864
+
865
+ // [bit.count], counting
866
+ template<class T>
867
+ constexpr int countl_zero(T x) noexcept;
868
+ template<class T>
869
+ constexpr int countl_one(T x) noexcept;
870
+ template<class T>
871
+ constexpr int countr_zero(T x) noexcept;
872
+ template<class T>
873
+ constexpr int countr_one(T x) noexcept;
874
+ template<class T>
875
+ constexpr int popcount(T x) noexcept;
876
+
877
+ // [bit.endian], endian
878
+ enum class endian {
879
+ little = see below,
880
+ big = see below,
881
+ native = see below
882
+ };
883
+ }
884
+ ```
885
+
886
+ ### Function template `bit_cast` <a id="bit.cast">[[bit.cast]]</a>
887
+
888
+ ``` cpp
889
+ template<class To, class From>
890
+ constexpr To bit_cast(const From& from) noexcept;
891
+ ```
892
+
893
+ *Constraints:*
894
+
895
+ - `sizeof(To) == sizeof(From)` is `true`;
896
+ - `is_trivially_copyable_v<To>` is `true`; and
897
+ - `is_trivially_copyable_v<From>` is `true`.
898
+
899
+ *Returns:* An object of type `To`. Implicitly creates objects nested
900
+ within the result [[intro.object]]. Each bit of the value representation
901
+ of the result is equal to the corresponding bit in the object
902
+ representation of `from`. Padding bits of the result are unspecified.
903
+ For the result and each object created within it, if there is no value
904
+ of the object’s type corresponding to the value representation produced,
905
+ the behavior is undefined. If there are multiple such values, which
906
+ value is produced is unspecified.
907
+
908
+ *Remarks:* This function is `constexpr` if and only if `To`, `From`, and
909
+ the types of all subobjects of `To` and `From` are types `T` such that:
910
+
911
+ - `is_union_v<T>` is `false`;
912
+ - `is_pointer_v<T>` is `false`;
913
+ - `is_member_pointer_v<T>` is `false`;
914
+ - `is_volatile_v<T>` is `false`; and
915
+ - `T` has no non-static data members of reference type.
916
+
917
+ ### Integral powers of 2 <a id="bit.pow.two">[[bit.pow.two]]</a>
918
+
919
+ ``` cpp
920
+ template<class T>
921
+ constexpr bool has_single_bit(T x) noexcept;
922
+ ```
923
+
924
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
925
+
926
+ *Returns:* `true` if `x` is an integral power of two; `false` otherwise.
927
+
928
+ ``` cpp
929
+ template<class T>
930
+ constexpr T bit_ceil(T x);
931
+ ```
932
+
933
+ Let N be the smallest power of 2 greater than or equal to `x`.
934
+
935
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
936
+
937
+ *Preconditions:* N is representable as a value of type `T`.
938
+
939
+ *Returns:* N.
940
+
941
+ *Throws:* Nothing.
942
+
943
+ *Remarks:* A function call expression that violates the precondition in
944
+ the *Preconditions:* element is not a core constant
945
+ expression [[expr.const]].
946
+
947
+ ``` cpp
948
+ template<class T>
949
+ constexpr T bit_floor(T x) noexcept;
950
+ ```
951
+
952
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
953
+
954
+ *Returns:* If `x == 0`, `0`; otherwise the maximal value `y` such that
955
+ `has_single_bit(y)` is `true` and `y <= x`.
956
+
957
+ ``` cpp
958
+ template<class T>
959
+ constexpr T bit_width(T x) noexcept;
960
+ ```
961
+
962
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
963
+
964
+ *Returns:* If `x == 0`, `0`; otherwise one plus the base-2 logarithm of
965
+ `x`, with any fractional part discarded.
966
+
967
+ ### Rotating <a id="bit.rotate">[[bit.rotate]]</a>
968
+
969
+ In the following descriptions, let `N` denote
970
+ `numeric_limits<T>::digits`.
971
+
972
+ ``` cpp
973
+ template<class T>
974
+ [[nodiscard]] constexpr T rotl(T x, int s) noexcept;
975
+ ```
976
+
977
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
978
+
979
+ Let `r` be `s % N`.
980
+
981
+ *Returns:* If `r` is `0`, `x`; if `r` is positive,
982
+ `(x << r) | (x >> (N - r))`; if `r` is negative, `rotr(x, -r)`.
983
+
984
+ ``` cpp
985
+ template<class T>
986
+ [[nodiscard]] constexpr T rotr(T x, int s) noexcept;
987
+ ```
988
+
989
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
990
+
991
+ Let `r` be `s % N`.
992
+
993
+ *Returns:* If `r` is `0`, `x`; if `r` is positive,
994
+ `(x >> r) | (x << (N - r))`; if `r` is negative, `rotl(x, -r)`.
995
+
996
+ ### Counting <a id="bit.count">[[bit.count]]</a>
997
+
998
+ In the following descriptions, let `N` denote
999
+ `numeric_limits<T>::digits`.
1000
+
1001
+ ``` cpp
1002
+ template<class T>
1003
+ constexpr int countl_zero(T x) noexcept;
1004
+ ```
1005
+
1006
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
1007
+
1008
+ *Returns:* The number of consecutive `0` bits in the value of `x`,
1009
+ starting from the most significant bit.
1010
+
1011
+ [*Note 1*: Returns `N` if `x == 0`. — *end note*]
1012
+
1013
+ ``` cpp
1014
+ template<class T>
1015
+ constexpr int countl_one(T x) noexcept;
1016
+ ```
1017
+
1018
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
1019
+
1020
+ *Returns:* The number of consecutive `1` bits in the value of `x`,
1021
+ starting from the most significant bit.
1022
+
1023
+ [*Note 2*: Returns `N` if
1024
+ `x == numeric_limits<T>::max()`. — *end note*]
1025
+
1026
+ ``` cpp
1027
+ template<class T>
1028
+ constexpr int countr_zero(T x) noexcept;
1029
+ ```
1030
+
1031
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
1032
+
1033
+ *Returns:* The number of consecutive `0` bits in the value of `x`,
1034
+ starting from the least significant bit.
1035
+
1036
+ [*Note 3*: Returns `N` if `x == 0`. — *end note*]
1037
+
1038
+ ``` cpp
1039
+ template<class T>
1040
+ constexpr int countr_one(T x) noexcept;
1041
+ ```
1042
+
1043
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
1044
+
1045
+ *Returns:* The number of consecutive `1` bits in the value of `x`,
1046
+ starting from the least significant bit.
1047
+
1048
+ [*Note 4*: Returns `N` if
1049
+ `x == numeric_limits<T>::max()`. — *end note*]
1050
+
1051
+ ``` cpp
1052
+ template<class T>
1053
+ constexpr int popcount(T x) noexcept;
1054
+ ```
1055
+
1056
+ *Constraints:* `T` is an unsigned integer type [[basic.fundamental]].
1057
+
1058
+ *Returns:* The number of `1` bits in the value of `x`.
1059
+
1060
+ ### Endian <a id="bit.endian">[[bit.endian]]</a>
1061
+
1062
+ Two common methods of byte ordering in multibyte scalar types are
1063
+ big-endian and little-endian in the execution environment. Big-endian is
1064
+ a format for storage of binary data in which the most significant byte
1065
+ is placed first, with the rest in descending order. Little-endian is a
1066
+ format for storage of binary data in which the least significant byte is
1067
+ placed first, with the rest in ascending order. This subclause describes
1068
+ the endianness of the scalar types of the execution environment.
1069
+
1070
+ ``` cpp
1071
+ enum class endian {
1072
+ little = see below,
1073
+ big = see below,
1074
+ native = see below
1075
+ };
1076
+ ```
1077
+
1078
+ If all scalar types have size 1 byte, then all of `endian::little`,
1079
+ `endian::big`, and `endian::native` have the same value. Otherwise,
1080
+ `endian::little` is not equal to `endian::big`. If all scalar types are
1081
+ big-endian, `endian::native` is equal to `endian::big`. If all scalar
1082
+ types are little-endian, `endian::native` is equal to `endian::little`.
1083
+ Otherwise, `endian::native` is not equal to either `endian::big` or
1084
+ `endian::little`.
1085
+
1086
  ## Random number generation <a id="rand">[[rand]]</a>
1087
 
1088
  This subclause defines a facility for generating (pseudo-)random
1089
  numbers.
1090
 
1091
  In addition to a few utilities, four categories of entities are
1092
  described: *uniform random bit generators*, *random number engines*,
1093
  *random number engine adaptors*, and *random number distributions*.
1094
+ These categorizations are applicable to types that meet the
1095
  corresponding requirements, to objects instantiated from such types, and
1096
  to templates producing such types when instantiated.
1097
 
1098
  [*Note 1*: These entities are specified in such a way as to permit the
1099
  binding of any uniform random bit generator object `e` as the argument
1100
  to any random number distribution object `d`, thus producing a
1101
  zero-argument function object such as given by
1102
  `bind(d,e)`. — *end note*]
1103
 
1104
  Each of the entities specified via this subclause has an associated
1105
+ arithmetic type [[basic.fundamental]] identified as `result_type`. With
1106
+ `T` as the `result_type` thus associated with such an entity, that
1107
  entity is characterized:
1108
 
1109
+ - as *boolean* or equivalently as *boolean-valued*, if `T` is `bool`;
1110
+ - otherwise as *integral* or equivalently as *integer-valued*, if
1111
+ `numeric_limits<T>::is_integer` is `true`;
1112
+ - otherwise as *floating-point* or equivalently as *real-valued*.
1113
+
1114
  If integer-valued, an entity may optionally be further characterized as
1115
  *signed* or *unsigned*, according to `numeric_limits<T>::is_signed`.
1116
 
1117
  Unless otherwise specified, all descriptions of calculations in this
1118
  subclause use mathematical real numbers.
1119
 
1120
+ Throughout this subclause, the operators , , and \xor denote the
1121
+ respective conventional bitwise operations. Further:
1122
+
1123
+ - the operator \rightshift denotes a bitwise right shift with
1124
+ zero-valued bits appearing in the high bits of the result, and
1125
+ - the operator denotes a bitwise left shift with zero-valued bits
1126
+ appearing in the low bits of the result, and whose result is always
1127
+ taken modulo 2ʷ.
1128
+
1129
+ ### Header `<random>` synopsis <a id="rand.synopsis">[[rand.synopsis]]</a>
1130
+
1131
+ ``` cpp
1132
+ #include <initializer_list>
1133
+
1134
+ namespace std {
1135
+ // [rand.req.urng], uniform random bit generator requirements
1136
+ template<class G>
1137
+ concept uniform_random_bit_generator = see below;
1138
+
1139
+ // [rand.eng.lcong], class template linear_congruential_engine
1140
+ template<class UIntType, UIntType a, UIntType c, UIntType m>
1141
+ class linear_congruential_engine;
1142
+
1143
+ // [rand.eng.mers], class template mersenne_twister_engine
1144
+ template<class UIntType, size_t w, size_t n, size_t m, size_t r,
1145
+ UIntType a, size_t u, UIntType d, size_t s,
1146
+ UIntType b, size_t t,
1147
+ UIntType c, size_t l, UIntType f>
1148
+ class mersenne_twister_engine;
1149
+
1150
+ // [rand.eng.sub], class template subtract_with_carry_engine
1151
+ template<class UIntType, size_t w, size_t s, size_t r>
1152
+ class subtract_with_carry_engine;
1153
+
1154
+ // [rand.adapt.disc], class template discard_block_engine
1155
+ template<class Engine, size_t p, size_t r>
1156
+ class discard_block_engine;
1157
+
1158
+ // [rand.adapt.ibits], class template independent_bits_engine
1159
+ template<class Engine, size_t w, class UIntType>
1160
+ class independent_bits_engine;
1161
+
1162
+ // [rand.adapt.shuf], class template shuffle_order_engine
1163
+ template<class Engine, size_t k>
1164
+ class shuffle_order_engine;
1165
+
1166
+ // [rand.predef], engines and engine adaptors with predefined parameters
1167
+ using minstd_rand0 = see below;
1168
+ using minstd_rand = see below;
1169
+ using mt19937 = see below;
1170
+ using mt19937_64 = see below;
1171
+ using ranlux24_base = see below;
1172
+ using ranlux48_base = see below;
1173
+ using ranlux24 = see below;
1174
+ using ranlux48 = see below;
1175
+ using knuth_b = see below;
1176
+
1177
+ using default_random_engine = see below;
1178
+
1179
+ // [rand.device], class random_device
1180
+ class random_device;
1181
+
1182
+ // [rand.util.seedseq], class seed_seq
1183
+ class seed_seq;
1184
+
1185
+ // [rand.util.canonical], function template generate_canonical
1186
+ template<class RealType, size_t bits, class URBG>
1187
+ RealType generate_canonical(URBG& g);
1188
+
1189
+ // [rand.dist.uni.int], class template uniform_int_distribution
1190
+ template<class IntType = int>
1191
+ class uniform_int_distribution;
1192
+
1193
+ // [rand.dist.uni.real], class template uniform_real_distribution
1194
+ template<class RealType = double>
1195
+ class uniform_real_distribution;
1196
+
1197
+ // [rand.dist.bern.bernoulli], class bernoulli_distribution
1198
+ class bernoulli_distribution;
1199
+
1200
+ // [rand.dist.bern.bin], class template binomial_distribution
1201
+ template<class IntType = int>
1202
+ class binomial_distribution;
1203
+
1204
+ // [rand.dist.bern.geo], class template geometric_distribution
1205
+ template<class IntType = int>
1206
+ class geometric_distribution;
1207
+
1208
+ // [rand.dist.bern.negbin], class template negative_binomial_distribution
1209
+ template<class IntType = int>
1210
+ class negative_binomial_distribution;
1211
+
1212
+ // [rand.dist.pois.poisson], class template poisson_distribution
1213
+ template<class IntType = int>
1214
+ class poisson_distribution;
1215
+
1216
+ // [rand.dist.pois.exp], class template exponential_distribution
1217
+ template<class RealType = double>
1218
+ class exponential_distribution;
1219
+
1220
+ // [rand.dist.pois.gamma], class template gamma_distribution
1221
+ template<class RealType = double>
1222
+ class gamma_distribution;
1223
+
1224
+ // [rand.dist.pois.weibull], class template weibull_distribution
1225
+ template<class RealType = double>
1226
+ class weibull_distribution;
1227
+
1228
+ // [rand.dist.pois.extreme], class template extreme_value_distribution
1229
+ template<class RealType = double>
1230
+ class extreme_value_distribution;
1231
+
1232
+ // [rand.dist.norm.normal], class template normal_distribution
1233
+ template<class RealType = double>
1234
+ class normal_distribution;
1235
+
1236
+ // [rand.dist.norm.lognormal], class template lognormal_distribution
1237
+ template<class RealType = double>
1238
+ class lognormal_distribution;
1239
+
1240
+ // [rand.dist.norm.chisq], class template chi_squared_distribution
1241
+ template<class RealType = double>
1242
+ class chi_squared_distribution;
1243
+
1244
+ // [rand.dist.norm.cauchy], class template cauchy_distribution
1245
+ template<class RealType = double>
1246
+ class cauchy_distribution;
1247
+
1248
+ // [rand.dist.norm.f], class template fisher_f_distribution
1249
+ template<class RealType = double>
1250
+ class fisher_f_distribution;
1251
+
1252
+ // [rand.dist.norm.t], class template student_t_distribution
1253
+ template<class RealType = double>
1254
+ class student_t_distribution;
1255
+
1256
+ // [rand.dist.samp.discrete], class template discrete_distribution
1257
+ template<class IntType = int>
1258
+ class discrete_distribution;
1259
+
1260
+ // [rand.dist.samp.pconst], class template piecewise_constant_distribution
1261
+ template<class RealType = double>
1262
+ class piecewise_constant_distribution;
1263
+
1264
+ // [rand.dist.samp.plinear], class template piecewise_linear_distribution
1265
+ template<class RealType = double>
1266
+ class piecewise_linear_distribution;
1267
+ }
1268
+ ```
1269
 
1270
  ### Requirements <a id="rand.req">[[rand.req]]</a>
1271
 
1272
  #### General requirements <a id="rand.req.genl">[[rand.req.genl]]</a>
1273
 
1274
  Throughout this subclause [[rand]], the effect of instantiating a
1275
  template:
1276
 
1277
+ - that has a template type parameter named `Sseq` is undefined unless
1278
+ the corresponding template argument is cv-unqualified and meets the
1279
+ requirements of seed sequence [[rand.req.seedseq]].
1280
+ - that has a template type parameter named `URBG` is undefined unless
1281
+ the corresponding template argument is cv-unqualified and meets the
1282
+ requirements of uniform random bit generator [[rand.req.urng]].
1283
+ - that has a template type parameter named `Engine` is undefined unless
1284
+ the corresponding template argument is cv-unqualified and meets the
1285
+ requirements of random number engine [[rand.req.eng]].
1286
+ - that has a template type parameter named `RealType` is undefined
1287
+ unless the corresponding template argument is cv-unqualified and is
1288
+ one of `float`, `double`, or `long double`.
1289
+ - that has a template type parameter named `IntType` is undefined unless
1290
+ the corresponding template argument is cv-unqualified and is one of
1291
+ `short`, `int`, `long`, `long long`, `unsigned short`, `unsigned int`,
1292
+ `unsigned long`, or `unsigned long long`.
1293
+ - that has a template type parameter named `UIntType` is undefined
1294
+ unless the corresponding template argument is cv-unqualified and is
1295
+ one of `unsigned short`, `unsigned int`, `unsigned long`, or
1296
+ `unsigned long long`.
1297
+
1298
  Throughout this subclause [[rand]], phrases of the form “`x` is an
1299
  iterator of a specific kind” shall be interpreted as equivalent to the
1300
+ more formal requirement that “`x` is a value of a type meeting the
1301
  requirements of the specified iterator type”.
1302
 
1303
  Throughout this subclause [[rand]], any constructor that can be called
1304
+ with a single argument and that meets a requirement specified in this
1305
+ subclause shall be declared `explicit`.
1306
 
1307
  #### Seed sequence requirements <a id="rand.req.seedseq">[[rand.req.seedseq]]</a>
1308
 
1309
  A *seed sequence* is an object that consumes a sequence of
1310
  integer-valued data and produces a requested number of unsigned integer
 
1313
  [*Note 1*: Such an object provides a mechanism to avoid replication of
1314
  streams of random variates. This can be useful, for example, in
1315
  applications requiring large numbers of random number
1316
  engines. — *end note*]
1317
 
1318
+ A class `S` meets the requirements of a seed sequence if the expressions
1319
+ shown in [[rand.req.seedseq]] are valid and have the indicated
1320
+ semantics, and if `S` also meets all other requirements of this
1321
+ subclause [[rand.req.seedseq]]. In that Table and throughout this
1322
+ subclause:
1323
+
1324
+ - `T` is the type named by `S`’s associated `result_type`;
1325
+ - `q` is a value of `S` and `r` is a possibly const value of `S`;
1326
+ - `ib` and `ie` are input iterators with an unsigned integer
1327
+ `value_type` of at least 32 bits;
1328
+ - `rb` and `re` are mutable random access iterators with an unsigned
1329
+ integer `value_type` of at least 32 bits;
1330
+ - `ob` is an output iterator; and
1331
+ - `il` is a value of `initializer_list<T>`.
1332
 
1333
  #### Uniform random bit generator requirements <a id="rand.req.urng">[[rand.req.urng]]</a>
1334
 
1335
  A *uniform random bit generator* `g` of type `G` is a function object
1336
  returning unsigned integer values such that each value in the range of
1337
  possible results has (ideally) equal probability of being returned.
1338
 
1339
  [*Note 1*: The degree to which `g`’s results approximate the ideal is
1340
  often determined statistically. — *end note*]
1341
 
1342
+ ``` cpp
1343
+ template<class G>
1344
+ concept uniform_random_bit_generator =
1345
+ invocable<G&> && unsigned_integral<invoke_result_t<G&>> &&
1346
+ requires {
1347
+ { G::min() } -> same_as<invoke_result_t<G&>>;
1348
+ { G::max() } -> same_as<invoke_result_t<G&>>;
1349
+ requires bool_constant<(G::min() < G::max())>::value;
1350
+ };
1351
+ ```
1352
 
1353
+ Let `g` be an object of type `G`. `G` models
1354
+ `uniform_random_bit_generator` only if
1355
+
1356
+ - `G::min() <= g()`,
1357
+ - `g() <= G::max()`, and
1358
+ - `g()` has amortized constant complexity.
1359
+
1360
+ A class `G` meets the *uniform random bit generator* requirements if `G`
1361
+ models `uniform_random_bit_generator`, `invoke_result_t<G&>` is an
1362
+ unsigned integer type [[basic.fundamental]], and `G` provides a nested
1363
+ *typedef-name* `result_type` that denotes the same type as
1364
+ `invoke_result_t<G&>`.
1365
 
1366
  #### Random number engine requirements <a id="rand.req.eng">[[rand.req.eng]]</a>
1367
 
1368
  A *random number engine* (commonly shortened to *engine*) `e` of type
1369
  `E` is a uniform random bit generator that additionally meets the
1370
  requirements (e.g., for seeding and for input/output) specified in this
1371
+ subclause.
1372
 
1373
  At any given time, `e` has a state eᵢ for some integer i ≥ 0. Upon
1374
  construction, `e` has an initial state e₀. An engine’s state may be
1375
  established via a constructor, a `seed` function, assignment, or a
1376
  suitable `operator>>`.
1377
 
1378
  `E`’s specification shall define:
1379
 
1380
+ - the size of `E`’s state in multiples of the size of `result_type`,
1381
+ given as an integral constant expression;
1382
+ - the *transition algorithm* TA by which `e`’s state eᵢ is advanced to
1383
+ its *successor state* eᵢ₊₁; and
1384
+ - the *generation algorithm* GA by which an engine’s state is mapped to
1385
+ a value of type `result_type`.
1386
+
1387
+ A class `E` that meets the requirements of a uniform random bit
1388
+ generator [[rand.req.urng]] also meets the requirements of a *random
1389
+ number engine* if the expressions shown in [[rand.req.eng]] are valid
1390
+ and have the indicated semantics, and if `E` also meets all other
1391
+ requirements of this subclause [[rand.req.eng]]. In that Table and
1392
+ throughout this subclause:
1393
+
1394
+ - `T` is the type named by `E`’s associated `result_type`;
1395
+ - `e` is a value of `E`, `v` is an lvalue of `E`, `x` and `y` are
1396
+ (possibly `const`) values of `E`;
1397
+ - `s` is a value of `T`;
1398
+ - `q` is an lvalue meeting the requirements of a seed sequence
1399
+ [[rand.req.seedseq]];
1400
+ - `z` is a value of type `unsigned long long`;
1401
+ - `os` is an lvalue of the type of some class template specialization
1402
+ `basic_ostream<charT,` `traits>`; and
1403
+ - `is` is an lvalue of the type of some class template specialization
1404
+ `basic_istream<charT,` `traits>`;
1405
+
1406
+ where `charT` and `traits` are constrained according to [[strings]] and
1407
+ [[input.output]].
1408
+
1409
+ `E` shall meet the *Cpp17CopyConstructible* (
1410
+ [[cpp17.copyconstructible]]) and *Cpp17CopyAssignable* (
1411
+ [[cpp17.copyassignable]]) requirements. These operations shall each be
1412
+ of complexity no worse than 𝑂(\text{size of state}).
1413
 
1414
  #### Random number engine adaptor requirements <a id="rand.req.adapt">[[rand.req.adapt]]</a>
1415
 
1416
  A *random number engine adaptor* (commonly shortened to *adaptor*) `a`
1417
  of type `A` is a random number engine that takes values produced by some
 
1466
  template<class Sseq> void seed(Sseq& q);
1467
  ```
1468
 
1469
  *Effects:* With `b` as the base engine, invokes `b.seed(q)`.
1470
 
1471
+ `A` shall also meet the following additional requirements:
1472
+
1473
+ - The complexity of each function shall not exceed the complexity of the
1474
+ corresponding function applied to the base engine.
1475
+ - The state of `A` shall include the state of its base engine. The size
1476
+ of `A`’s state shall be no less than the size of the base engine.
1477
+ - Copying `A`’s state (e.g., during copy construction or copy
1478
+ assignment) shall include copying the state of the base engine of `A`.
1479
+ - The textual representation of `A` shall include the textual
1480
+ representation of its base engine.
1481
 
1482
  #### Random number distribution requirements <a id="rand.req.dist">[[rand.req.dist]]</a>
1483
 
1484
  A *random number distribution* (commonly shortened to *distribution*)
1485
  `d` of type `D` is a function object returning values that are
 
1494
  context by writing, for example, p(z | a,b) or P(zᵢ | a,b), to name
1495
  specific parameters, or by writing, for example, p(z |{`p`}) or
1496
  P(zᵢ |{`p`}), to denote a distribution’s parameters `p` taken as a
1497
  whole.
1498
 
1499
+ A class `D` meets the requirements of a *random number distribution* if
1500
+ the expressions shown in [[rand.req.dist]] are valid and have the
1501
+ indicated semantics, and if `D` and its associated types also meet all
1502
+ other requirements of this subclause [[rand.req.dist]]. In that Table
1503
+ and throughout this subclause,
1504
 
1505
+ - `T` is the type named by `D`’s associated `result_type`;
1506
+ - `P` is the type named by `D`’s associated `param_type`;
1507
+ - `d` is a value of `D`, and `x` and `y` are (possibly `const`) values
1508
+ of `D`;
1509
+ - `glb` and `lub` are values of `T` respectively corresponding to the
1510
+ greatest lower bound and the least upper bound on the values
1511
+ potentially returned by `d`’s `operator()`, as determined by the
1512
+ current values of `d`’s parameters;
1513
+ - `p` is a (possibly `const`) value of `P`;
1514
+ - `g`, `g1`, and `g2` are lvalues of a type meeting the requirements of
1515
+ a uniform random bit generator [[rand.req.urng]];
1516
+ - `os` is an lvalue of the type of some class template specialization
1517
+ `basic_ostream<charT,` `traits>`; and
1518
+ - `is` is an lvalue of the type of some class template specialization
1519
+ `basic_istream<charT,` `traits>`;
1520
 
1521
+ where `charT` and `traits` are constrained according to [[strings]] and
1522
+ [[input.output]].
1523
+
1524
+ `D` shall meet the *Cpp17CopyConstructible* (
1525
+ [[cpp17.copyconstructible]]) and *Cpp17CopyAssignable* (
1526
+ [[cpp17.copyassignable]]) requirements.
1527
 
1528
  The sequence of numbers produced by repeated invocations of `d(g)` shall
1529
  be independent of any invocation of `os << d` or of any `const` member
1530
  function of `D` between any of the invocations `d(g)`.
1531
 
 
1538
  It is unspecified whether `D::param_type` is declared as a (nested)
1539
  `class` or via a `typedef`. In this subclause [[rand]], declarations of
1540
  `D::param_type` are in the form of `typedef`s for convenience of
1541
  exposition only.
1542
 
1543
+ `P` shall meet the *Cpp17CopyConstructible* (
1544
+ [[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
1545
+ [[cpp17.copyassignable]]), and *Cpp17EqualityComparable* (
1546
+ [[cpp17.equalitycomparable]]) requirements.
1547
 
1548
  For each of the constructors of `D` taking arguments corresponding to
1549
  parameters of the distribution, `P` shall have a corresponding
1550
  constructor subject to the same requirements and taking arguments
1551
  identical in number, type, and default values. Moreover, for each of the
 
1557
 
1558
  ``` cpp
1559
  using distribution_type = D;
1560
  ```
1561
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1562
  ### Random number engine class templates <a id="rand.eng">[[rand.eng]]</a>
1563
 
1564
+ Each type instantiated from a class template specified in this
1565
+ subclause  [[rand.eng]] meets the requirements of a random number engine
1566
+ [[rand.req.eng]] type.
1567
 
1568
  Except where specified otherwise, the complexity of each function
1569
+ specified in this subclause  [[rand.eng]] is constant.
1570
 
1571
+ Except where specified otherwise, no function described in this
1572
+ subclause  [[rand.eng]] throws an exception.
1573
 
1574
+ Every function described in this subclause  [[rand.eng]] that has a
1575
  function parameter `q` of type `Sseq&` for a template type parameter
1576
  named `Sseq` that is different from type `seed_seq` throws what and when
1577
  the invocation of `q.generate` throws.
1578
 
1579
+ Descriptions are provided in this subclause  [[rand.eng]] only for
1580
+ engine operations that are not described in [[rand.req.eng]] or for
1581
+ operations where there is additional semantic information. In
1582
+ particular, declarations for copy constructors, for copy assignment
1583
+ operators, for streaming operators, and for equality and inequality
1584
+ operators are not shown in the synopses.
1585
 
1586
+ Each template specified in this subclause  [[rand.eng]] requires one or
1587
  more relationships, involving the value(s) of its non-type template
1588
  parameter(s), to hold. A program instantiating any of these templates is
1589
  ill-formed if any such required relationship fails to hold.
1590
 
1591
  For every random number engine and for every random number engine
1592
+ adaptor `X` defined in this subclause [[rand.eng]] and in subclause 
1593
  [[rand.adapt]]:
1594
 
1595
  - if the constructor
1596
  ``` cpp
1597
  template<class Sseq> explicit X(Sseq& q);
 
1635
  static constexpr result_type min() { return c == 0u ? 1u: 0u; }
1636
  static constexpr result_type max() { return m - 1u; }
1637
  static constexpr result_type default_seed = 1u;
1638
 
1639
  // constructors and seeding functions
1640
+ linear_congruential_engine() : linear_congruential_engine(default_seed) {}
1641
+ explicit linear_congruential_engine(result_type s);
1642
  template<class Sseq> explicit linear_congruential_engine(Sseq& q);
1643
  void seed(result_type s = default_seed);
1644
  template<class Sseq> void seed(Sseq& q);
1645
 
1646
  // generating functions
 
1648
  void discard(unsigned long long z);
1649
  };
1650
  ```
1651
 
1652
  If the template parameter `m` is 0, the modulus m used throughout this
1653
+ subclause  [[rand.eng.lcong]] is `numeric_limits<result_type>::max()`
1654
+ plus 1.
1655
 
1656
  [*Note 1*: m need not be representable as a value of type
1657
  `result_type`. — *end note*]
1658
 
1659
  If the template parameter `m` is not 0, the following relations shall
1660
  hold: `a < m` and `c < m`.
1661
 
1662
  The textual representation consists of the value of xᵢ.
1663
 
1664
  ``` cpp
1665
+ explicit linear_congruential_engine(result_type s);
1666
  ```
1667
 
1668
+ *Effects:* If c mod m is 0 and `s` mod m is 0, sets the engine’s
1669
+ state to 1, otherwise sets the engine’s state to `s` mod m.
 
1670
 
1671
  ``` cpp
1672
  template<class Sseq> explicit linear_congruential_engine(Sseq& q);
1673
  ```
1674
 
1675
+ *Effects:* With $k = \left\lceil \frac{\log_2 m}{32} \right\rceil$ and a
1676
+ an array (or equivalent) of length k + 3, invokes
1677
+ `q.generate(`a + 0`, `a + k + 3`)` and then computes
1678
+ $S = \left(\sum_{j = 0}^{k - 1} a_{j + 3} \cdot 2^{32j} \right) \bmod m$.
1679
+ If c mod m is 0 and S is 0, sets the engine’s state to 1, else sets
1680
+ the engine’s state to S.
 
 
1681
 
1682
  #### Class template `mersenne_twister_engine` <a id="rand.eng.mers">[[rand.eng.mers]]</a>
1683
 
1684
  A `mersenne_twister_engine` random number engine[^2] produces unsigned
1685
  integer random numbers in the closed interval [0,2ʷ-1]. The state xᵢ of
 
1689
 
1690
  The transition algorithm employs a twisted generalized feedback shift
1691
  register defined by shift values n and m, a twist value r, and a
1692
  conditional xor-mask a. To improve the uniformity of the result, the
1693
  bits of the raw shift register are additionally *tempered* (i.e.,
1694
+ scrambled) according to a bit-scrambling matrix defined by values u, d,
1695
+ s, b, t, c, and ℓ.
1696
 
1697
  The state transition is performed as follows:
1698
 
1699
+ - Concatenate the upper w-r bits of Xᵢ₋ₙ with the lower r bits of
1700
+ $X_{i+1-n}$ to obtain an unsigned integer value Y.
1701
+ - With $\alpha = a \cdot (Y \bitand 1)$, set Xᵢ to
1702
+ $X_{i+m-n} \xor (Y \rightshift 1) \xor \alpha$.
1703
+
1704
  The sequence X is initialized with the help of an initialization
1705
  multiplier f.
1706
 
1707
  The generation algorithm determines the unsigned integer values
1708
  z₁, z₂, z₃, z₄ as follows, then delivers z₄ as its result:
1709
 
1710
+ - Let $z_1 = X_i \xor \bigl(( X_i \rightshift u ) \bitand d\bigr)$.
1711
+ - Let $z_2 = z_1 \xor \bigl( (z_1 \leftshift{w} s) \bitand b \bigr)$.
1712
+ - Let $z_3 = z_2 \xor \bigl( (z_2 \leftshift{w} t) \bitand c \bigr)$.
1713
+ - Let $z_4 = z_3 \xor ( z_3 \rightshift \ell )$.
1714
+
1715
  ``` cpp
1716
  template<class UIntType, size_t w, size_t n, size_t m, size_t r,
1717
  UIntType a, size_t u, UIntType d, size_t s,
1718
  UIntType b, size_t t,
1719
  UIntType c, size_t l, UIntType f>
 
1739
  static constexpr result_type min() { return 0; }
1740
  static constexpr result_type max() { return 2^w - 1; }
1741
  static constexpr result_type default_seed = 5489u;
1742
 
1743
  // constructors and seeding functions
1744
+ mersenne_twister_engine() : mersenne_twister_engine(default_seed) {}
1745
+ explicit mersenne_twister_engine(result_type value);
1746
  template<class Sseq> explicit mersenne_twister_engine(Sseq& q);
1747
  void seed(result_type value = default_seed);
1748
  template<class Sseq> void seed(Sseq& q);
1749
 
1750
  // generating functions
 
1758
  `w <= numeric_limits<UIntType>::digits`, `a <= (1u<<w) - 1u`,
1759
  `b <= (1u<<w) - 1u`, `c <= (1u<<w) - 1u`, `d <= (1u<<w) - 1u`, and
1760
  `f <= (1u<<w) - 1u`.
1761
 
1762
  The textual representation of xᵢ consists of the values of
1763
+ $X_{i - n}, \dotsc, X_{i - 1}$, in that order.
1764
 
1765
  ``` cpp
1766
+ explicit mersenne_twister_engine(result_type value);
1767
  ```
1768
 
1769
+ *Effects:* Sets X₋ₙ to `value` mod 2ʷ. Then, iteratively for
1770
+ i = 1 - n, …, -1, sets Xᵢ to $$%
1771
  \bigl[f \cdot
1772
  \bigl(X_{i-1} \xor \bigl(X_{i-1} \rightshift (w-2)\bigr)
1773
  \bigr)
1774
  + i \bmod n
1775
  \bigr] \bmod 2^w
 
1779
 
1780
  ``` cpp
1781
  template<class Sseq> explicit mersenne_twister_engine(Sseq& q);
1782
  ```
1783
 
1784
+ *Effects:* With k = ⌈ w / 32 ⌉ and a an array (or equivalent) of length
1785
+ n k, invokes `q.generate(`a+0`, `a+n ⋅ k`)` and then, iteratively for
1786
+ i = -n,…,-1, sets Xᵢ to
 
1787
  $\left(\sum_{j=0}^{k-1}a_{k(i+n)+j} \cdot 2^{32j} \right) \bmod 2^w$.
1788
  Finally, if the most significant w-r bits of X₋ₙ are zero, and if each
1789
  of the other resulting Xᵢ is 0, changes X₋ₙ to 2ʷ⁻¹.
1790
 
1791
  #### Class template `subtract_with_carry_engine` <a id="rand.eng.sub">[[rand.eng.sub]]</a>
 
1799
  additionally consists of an integer c (known as the *carry*) whose value
1800
  is either 0 or 1.
1801
 
1802
  The state transition is performed as follows:
1803
 
1804
+ - Let Y = Xᵢ₋ₛ - Xᵢ₋ᵣ - c.
1805
+ - Set Xᵢ to y = Y mod m. Set c to 1 if Y < 0, otherwise set c to 0.
1806
+
1807
  [*Note 1*: This algorithm corresponds to a modular linear function of
1808
  the form TA(xᵢ) = (a ⋅ xᵢ) mod b, where b is of the form mʳ - mˢ + 1
1809
  and a = b - (b - 1) / m. — *end note*]
1810
 
1811
  The generation algorithm is given by GA(xᵢ) = y, where y is the value
 
1825
  static constexpr result_type min() { return 0; }
1826
  static constexpr result_type max() { return m - 1; }
1827
  static constexpr result_type default_seed = 19780503u;
1828
 
1829
  // constructors and seeding functions
1830
+ subtract_with_carry_engine() : subtract_with_carry_engine(default_seed) {}
1831
+ explicit subtract_with_carry_engine(result_type value);
1832
  template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);
1833
  void seed(result_type value = default_seed);
1834
  template<class Sseq> void seed(Sseq& q);
1835
 
1836
  // generating functions
 
1844
 
1845
  The textual representation consists of the values of Xᵢ₋ᵣ, …, Xᵢ₋₁, in
1846
  that order, followed by c.
1847
 
1848
  ``` cpp
1849
+ explicit subtract_with_carry_engine(result_type value);
1850
  ```
1851
 
1852
+ *Effects:* Sets the values of X₋ᵣ, …, X₋₁, in that order, as specified
1853
+ below. If X₋₁ is then 0, sets c to 1; otherwise sets c to 0.
 
1854
 
1855
  To set the values Xₖ, first construct `e`, a
1856
  `linear_congruential_engine` object, as if by the following definition:
1857
 
1858
  ``` cpp
 
1868
 
1869
  ``` cpp
1870
  template<class Sseq> explicit subtract_with_carry_engine(Sseq& q);
1871
  ```
1872
 
1873
+ *Effects:* With k = ⌈ w / 32 ⌉ and a an array (or equivalent) of length
1874
+ r k, invokes `q.generate(`a + 0`, `a + r ⋅ k`)` and then, iteratively
1875
+ for i = -r, …, -1, sets Xᵢ to
 
1876
  $\left(\sum_{j=0}^{k-1}a_{k(i+r)+j} \cdot 2^{32j} \right) \bmod m$. If
1877
  X₋₁ is then 0, sets c to 1; otherwise sets c to 0.
1878
 
1879
  ### Random number engine adaptor class templates <a id="rand.adapt">[[rand.adapt]]</a>
1880
 
1881
  #### In general <a id="rand.adapt.general">[[rand.adapt.general]]</a>
1882
 
1883
+ Each type instantiated from a class template specified in this
1884
+ subclause  [[rand.adapt]] meets the requirements of a random number
1885
+ engine adaptor [[rand.req.adapt]] type.
1886
 
1887
  Except where specified otherwise, the complexity of each function
1888
+ specified in this subclause  [[rand.adapt]] is constant.
1889
 
1890
+ Except where specified otherwise, no function described in this
1891
+ subclause  [[rand.adapt]] throws an exception.
1892
 
1893
+ Every function described in this subclause  [[rand.adapt]] that has a
1894
  function parameter `q` of type `Sseq&` for a template type parameter
1895
  named `Sseq` that is different from type `seed_seq` throws what and when
1896
  the invocation of `q.generate` throws.
1897
 
1898
+ Descriptions are provided in this subclause  [[rand.adapt]] only for
1899
+ adaptor operations that are not described in subclause 
1900
+ [[rand.req.adapt]] or for operations where there is additional semantic
1901
+ information. In particular, declarations for copy constructors, for copy
1902
+ assignment operators, for streaming operators, and for equality and
1903
+ inequality operators are not shown in the synopses.
1904
 
1905
+ Each template specified in this subclause  [[rand.adapt]] requires one
1906
+ or more relationships, involving the value(s) of its non-type template
1907
  parameter(s), to hold. A program instantiating any of these templates is
1908
  ill-formed if any such required relationship fails to hold.
1909
 
1910
  #### Class template `discard_block_engine` <a id="rand.adapt.disc">[[rand.adapt.disc]]</a>
1911
 
 
1963
  The following relations shall hold: `0 < r` and `r <= p`.
1964
 
1965
  The textual representation consists of the textual representation of `e`
1966
  followed by the value of `n`.
1967
 
1968
+ In addition to its behavior pursuant to subclause  [[rand.req.adapt]],
1969
  each constructor that is not a copy constructor sets `n` to 0.
1970
 
1971
  #### Class template `independent_bits_engine` <a id="rand.adapt.ibits">[[rand.adapt.ibits]]</a>
1972
 
1973
  An `independent_bits_engine` random number engine adaptor combines
 
1978
  e’s state.
1979
 
1980
  The transition and generation algorithms are described in terms of the
1981
  following integral constants:
1982
 
1983
+ - Let R = `e.max() - e.min() + 1` and m = ⌊ log₂ R ⌋.
1984
+ - With n as determined below, let w₀ = ⌊ w / n ⌋, n₀ = n - w mod n,
1985
+ $y_0 = 2^{w_0} \left\lfloor R / 2^{w_0} \right\rfloor$, and
1986
+ $y_1 = 2^{w_0 + 1} \left\lfloor R / 2^{w_0 + 1} \right\rfloor$.
1987
+ - Let n = ⌈ w / m ⌉ if and only if the relation R - y₀ ≤ ⌊ y₀ / n ⌋
1988
+ holds as a result. Otherwise let n = 1 + ⌈ w / m ⌉.
1989
+
1990
  [*Note 1*: The relation w = n₀ w₀ + (n - n₀)(w₀ + 1) always
1991
  holds. — *end note*]
1992
 
1993
  The transition algorithm is carried out by invoking `e()` as often as
1994
  needed to obtain n₀ values less than y₀ + `e.min()` and n - n₀ values
 
2060
  size of the state is the size of e’s state plus k + 1.
2061
 
2062
  The transition algorithm permutes the values produced by e. The state
2063
  transition is performed as follows:
2064
 
2065
+ - Calculate an integer $j = \left\lfloor \frac{k \cdot (Y - e_{\min})}
2066
+ {e_{\max} - e_{\min} +1}
2067
+ \right\rfloor$ .
2068
+ - Set Y to Vⱼ and then set Vⱼ to `e()`.
2069
+
2070
  The generation algorithm yields the last value of `Y` produced while
2071
  advancing `e`’s state as described above.
2072
 
2073
  ``` cpp
2074
  template<class Engine, size_t k>
 
2109
  The following relation shall hold: `0 < k`.
2110
 
2111
  The textual representation consists of the textual representation of
2112
  `e`, followed by the `k` values of V, followed by the value of Y.
2113
 
2114
+ In addition to its behavior pursuant to subclause  [[rand.req.adapt]],
2115
  each constructor that is not a copy constructor initializes
2116
  `V[0]`, …, `V[k-1]` and Y, in that order, with values returned by
2117
  successive invocations of `e()`.
2118
 
2119
  ### Engines and engine adaptors with predefined parameters <a id="rand.predef">[[rand.predef]]</a>
2120
 
2121
  ``` cpp
2122
  using minstd_rand0 =
2123
+ linear_congruential_engine<uint_fast32_t, 16'807, 0, 2'147'483'647>;
2124
  ```
2125
 
2126
+ *Required behavior:* The 10000ᵗʰ consecutive invocation of a
2127
+ default-constructed object of type `minstd_rand0` produces the value
2128
+ 1043618065.
2129
 
2130
  ``` cpp
2131
  using minstd_rand =
2132
+ linear_congruential_engine<uint_fast32_t, 48'271, 0, 2'147'483'647>;
2133
  ```
2134
 
2135
+ *Required behavior:* The 10000ᵗʰ consecutive invocation of a
2136
+ default-constructed object of type `minstd_rand` produces the value
2137
  399268537.
2138
 
2139
  ``` cpp
2140
  using mt19937 =
2141
+ mersenne_twister_engine<uint_fast32_t, 32, 624, 397, 31,
2142
+ 0x9908'b0df, 11, 0xffff'ffff, 7, 0x9d2c'5680, 15, 0xefc6'0000, 18, 1'812'433'253>;
2143
  ```
2144
 
2145
+ *Required behavior:* The 10000ᵗʰ consecutive invocation of a
2146
+ default-constructed object of type `mt19937` produces the value
2147
  4123659995.
2148
 
2149
  ``` cpp
2150
  using mt19937_64 =
2151
+ mersenne_twister_engine<uint_fast64_t, 64, 312, 156, 31,
2152
+ 0xb502'6f5a'a966'19e9, 29, 0x5555'5555'5555'5555, 17,
2153
+ 0x71d6'7fff'eda6'0000, 37, 0xfff7'eee0'0000'0000, 43, 6'364'136'223'846'793'005>;
 
 
 
2154
  ```
2155
 
2156
+ *Required behavior:* The 10000ᵗʰ consecutive invocation of a
2157
+ default-constructed object of type `mt19937_64` produces the value
2158
  9981545732273789042.
2159
 
2160
  ``` cpp
2161
  using ranlux24_base =
2162
  subtract_with_carry_engine<uint_fast32_t, 24, 10, 24>;
2163
  ```
2164
 
2165
+ *Required behavior:* The 10000ᵗʰ consecutive invocation of a
2166
+ default-constructed object of type `ranlux24_base` produces the value
2167
+ 7937952.
2168
 
2169
  ``` cpp
2170
  using ranlux48_base =
2171
  subtract_with_carry_engine<uint_fast64_t, 48, 5, 12>;
2172
  ```
2173
 
2174
+ *Required behavior:* The 10000ᵗʰ consecutive invocation of a
2175
+ default-constructed object of type `ranlux48_base` produces the value
2176
+ 61839128582725.
2177
 
2178
  ``` cpp
2179
  using ranlux24 = discard_block_engine<ranlux24_base, 223, 23>;
2180
  ```
2181
 
2182
+ *Required behavior:* The 10000ᵗʰ consecutive invocation of a
2183
+ default-constructed object of type `ranlux24` produces the value
2184
  9901578.
2185
 
2186
  ``` cpp
2187
  using ranlux48 = discard_block_engine<ranlux48_base, 389, 11>;
2188
  ```
2189
 
2190
+ *Required behavior:* The 10000ᵗʰ consecutive invocation of a
2191
+ default-constructed object of type `ranlux48` produces the value
2192
  249142670248501.
2193
 
2194
  ``` cpp
2195
  using knuth_b = shuffle_order_engine<minstd_rand0,256>;
2196
  ```
2197
 
2198
+ *Required behavior:* The 10000ᵗʰ consecutive invocation of a
2199
+ default-constructed object of type `knuth_b` produces the value
2200
  1112339016.
2201
 
2202
  ``` cpp
2203
  using default_random_engine = implementation-defined;
2204
  ```
 
2231
  // generator characteristics
2232
  static constexpr result_type min() { return numeric_limits<result_type>::min(); }
2233
  static constexpr result_type max() { return numeric_limits<result_type>::max(); }
2234
 
2235
  // constructors
2236
+ random_device() : random_device(implementation-defined) {}
2237
+ explicit random_device(const string& token);
2238
 
2239
  // generating functions
2240
  result_type operator()();
2241
 
2242
  // property functions
 
2247
  void operator=(const random_device&) = delete;
2248
  };
2249
  ```
2250
 
2251
  ``` cpp
2252
+ explicit random_device(const string& token);
2253
  ```
2254
 
2255
+ *Remarks:* The semantics of the `token` parameter and the token value
2256
+ used by the default constructor are *implementation-defined*. [^3]
 
2257
 
2258
  *Throws:* A value of an *implementation-defined* type derived from
2259
  `exception` if the `random_device` could not be initialized.
2260
 
2261
  ``` cpp
 
2269
  ``` cpp
2270
  result_type operator()();
2271
  ```
2272
 
2273
  *Returns:* A nondeterministic random value, uniformly distributed
2274
+ between `min()` and `max()` (inclusive). It is *implementation-defined*
2275
  how these values are generated.
2276
 
2277
  *Throws:* A value of an *implementation-defined* type derived from
2278
  `exception` if a random number could not be obtained.
2279
 
 
2314
 
2315
  ``` cpp
2316
  seed_seq();
2317
  ```
2318
 
2319
+ *Ensures:* `v.empty()` is `true`.
 
2320
 
2321
  *Throws:* Nothing.
2322
 
2323
  ``` cpp
2324
  template<class T>
2325
  seed_seq(initializer_list<T> il);
2326
  ```
2327
 
2328
+ *Mandates:* `T` is an integer type.
2329
 
2330
  *Effects:* Same as `seed_seq(il.begin(), il.end())`.
2331
 
2332
  ``` cpp
2333
  template<class InputIterator>
2334
  seed_seq(InputIterator begin, InputIterator end);
2335
  ```
2336
 
2337
+ *Mandates:* `iterator_traits<InputIterator>::value_type` is an integer
 
 
2338
  type.
2339
 
2340
+ *Preconditions:* `InputIterator` meets the *Cpp17InputIterator*
2341
+ requirements [[input.iterators]].
2342
+
2343
+ *Effects:* Initializes `v` by the following algorithm:
2344
 
2345
  ``` cpp
2346
  for (InputIterator s = begin; s != end; ++s)
2347
  v.push_back((*s) mod 2³²);
2348
  ```
 
2350
  ``` cpp
2351
  template<class RandomAccessIterator>
2352
  void generate(RandomAccessIterator begin, RandomAccessIterator end);
2353
  ```
2354
 
2355
+ *Mandates:* `iterator_traits<RandomAccessIterator>::value_type` is an
 
 
2356
  unsigned integer type capable of accommodating 32-bit quantities.
2357
 
2358
+ *Preconditions:* `RandomAccessIterator` meets the
2359
+ *Cpp17RandomAccessIterator* requirements [[random.access.iterators]] and
2360
+ the requirements of a mutable iterator.
2361
+
2362
  *Effects:* Does nothing if `begin == end`. Otherwise, with
2363
  s = `v.size()` and n = `end` - `begin`, fills the supplied range
2364
  [`begin`,`end`) according to the following algorithm in which each
2365
  operation is to be carried out modulo 2³², each indexing operator
2366
  applied to `begin` is to be taken modulo n, and T(x) is defined as
2367
+ $x \xor (x \rightshift 27)$:
2368
+
2369
+ - By way of initialization, set each element of the range to the value
2370
+ `0x8b8b8b8b`. Additionally, for use in subsequent steps, let
2371
+ p = (n - t) / 2 and let q = p + t, where $$%
2372
+ 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;$$
2373
+ - With m as the larger of s + 1 and n, transform the elements of the
2374
+ range: iteratively for k = 0, …, m - 1, calculate values
2375
+ $$\begin{aligned}
2376
+ r_1 & = &
2377
+ 1664525 \cdot T( \texttt{begin[}k\texttt{]}
2378
+ \xor \texttt{begin[}k+p\texttt{]}
2379
+ \xor \texttt{begin[}k-1 \texttt{]}
2380
+ )
2381
+ \\
2382
+ r_2 & = & r_1 + \left\{
2383
+ \begin{array}{cl}
2384
+ s & \mbox{, } k = 0
2385
+ \\
2386
+ k \bmod n + \texttt{v[}k-1\texttt{]} & \mbox{, } 0 < k \le s
2387
+ \\
2388
+ k \bmod n & \mbox{, } s < k
2389
+ \end{array}
2390
+ \right.
2391
+
2392
+ \end{aligned}$$ and, in order, increment `begin[`k+p`]` by r₁,
2393
+ increment `begin[`k+q`]` by r₂, and set `begin[`k`]` to r₂.
2394
+ - Transform the elements of the range again, beginning where the
2395
+ previous step ended: iteratively for k = m, …, m + n - 1, calculate
2396
+ values $$\begin{aligned}
2397
+ r_3 & = &
2398
+ 1566083941 \cdot T( \texttt{begin[}k \texttt{]}
2399
+ + \texttt{begin[}k+p\texttt{]}
2400
+ + \texttt{begin[}k-1\texttt{]}
2401
+ )
2402
+ \\
2403
+ r_4 & = & r_3 - (k \bmod n)
2404
+
2405
+ \end{aligned}$$ and, in order, update `begin[`k+p`]` by xoring it with
2406
+ r₃, update `begin[`k+q`]` by xoring it with r₄, and set `begin[`k`]`
2407
+ to r₄.
2408
 
2409
  *Throws:* What and when `RandomAccessIterator` operations of `begin` and
2410
  `end` throw.
2411
 
2412
  ``` cpp
 
2421
  ``` cpp
2422
  template<class OutputIterator>
2423
  void param(OutputIterator dest) const;
2424
  ```
2425
 
2426
+ *Mandates:* Values of type `result_type` are
2427
+ writable [[iterator.requirements.general]] to `dest`.
2428
+
2429
+ *Preconditions:* `OutputIterator` meets the *Cpp17OutputIterator*
2430
+ requirements [[output.iterators]].
2431
 
2432
  *Effects:* Copies the sequence of prepared 32-bit units to the given
2433
  destination, as if by executing the following statement:
2434
 
2435
  ``` cpp
 
2438
 
2439
  *Throws:* What and when `OutputIterator` operations of `dest` throw.
2440
 
2441
  #### Function template `generate_canonical` <a id="rand.util.canonical">[[rand.util.canonical]]</a>
2442
 
 
 
 
 
 
 
 
 
 
 
 
 
2443
  ``` cpp
2444
  template<class RealType, size_t bits, class URBG>
2445
  RealType generate_canonical(URBG& g);
2446
  ```
2447
 
 
2454
  $$S = \sum_{i=0}^{k-1} (g_i - \texttt{g.min()})
2455
  \cdot R^i$$ using arithmetic of type `RealType`.
2456
 
2457
  *Returns:* S / Rᵏ.
2458
 
2459
+ [*Note 1*: 0 ≤ S / Rᵏ < 1. — *end note*]
2460
+
2461
  *Throws:* What and when `g` throws.
2462
 
2463
+ [*Note 2*: If the values gᵢ produced by `g` are uniformly distributed,
2464
+ the instantiation’s results are distributed as uniformly as possible.
2465
+ Obtaining a value in this way can be a useful step in the process of
2466
+ transforming a value generated by a uniform random bit generator into a
2467
+ value that can be delivered by a random number
2468
+ distribution. — *end note*]
2469
+
2470
  ### Random number distribution class templates <a id="rand.dist">[[rand.dist]]</a>
2471
 
2472
  #### In general <a id="rand.dist.general">[[rand.dist.general]]</a>
2473
 
2474
+ Each type instantiated from a class template specified in this
2475
+ subclause  [[rand.dist]] meets the requirements of a random number
2476
+ distribution [[rand.req.dist]] type.
2477
 
2478
+ Descriptions are provided in this subclause  [[rand.dist]] only for
2479
  distribution operations that are not described in [[rand.req.dist]] or
2480
  for operations where there is additional semantic information. In
2481
  particular, declarations for copy constructors, for copy assignment
2482
  operators, for streaming operators, and for equality and inequality
2483
  operators are not shown in the synopses.
2484
 
2485
  The algorithms for producing each of the specified distributions are
2486
  *implementation-defined*.
2487
 
2488
  The value of each probability density function p(z) and of each discrete
2489
+ probability function P(zᵢ) specified in this subclause is 0 everywhere
2490
  outside its stated domain.
2491
 
2492
  #### Uniform distributions <a id="rand.dist.uni">[[rand.dist.uni]]</a>
2493
 
2494
  ##### Class template `uniform_int_distribution` <a id="rand.dist.uni.int">[[rand.dist.uni.int]]</a>
2495
 
2496
  A `uniform_int_distribution` random number distribution produces random
2497
  integers i, a ≤ i ≤ b, distributed according to the constant discrete
2498
+ probability function $$P(i\,|\,a,b) = 1 / (b - a + 1) \text{ .}$$
 
 
2499
 
2500
  ``` cpp
2501
  template<class IntType = int>
2502
  class uniform_int_distribution {
2503
  public:
2504
  // types
2505
  using result_type = IntType;
2506
  using param_type = unspecified;
2507
 
2508
  // constructors and reset functions
2509
+ uniform_int_distribution() : uniform_int_distribution(0) {}
2510
+ explicit uniform_int_distribution(IntType a, IntType b = numeric_limits<IntType>::max());
2511
  explicit uniform_int_distribution(const param_type& parm);
2512
  void reset();
2513
 
2514
  // generating functions
2515
  template<class URBG>
 
2526
  result_type max() const;
2527
  };
2528
  ```
2529
 
2530
  ``` cpp
2531
+ explicit uniform_int_distribution(IntType a, IntType b = numeric_limits<IntType>::max());
2532
  ```
2533
 
2534
+ *Preconditions:* `a` ≤ `b`.
2535
 
2536
+ *Remarks:* `a` and `b` correspond to the respective parameters of the
2537
+ distribution.
2538
 
2539
  ``` cpp
2540
  result_type a() const;
2541
  ```
2542
 
 
2552
 
2553
  ##### Class template `uniform_real_distribution` <a id="rand.dist.uni.real">[[rand.dist.uni.real]]</a>
2554
 
2555
  A `uniform_real_distribution` random number distribution produces random
2556
  numbers x, a ≤ x < b, distributed according to the constant probability
2557
+ density function $$p(x\,|\,a,b) = 1 / (b - a) \text{ .}$$
 
 
2558
 
2559
  [*Note 1*: This implies that p(x | a,b) is undefined when
2560
  `a == b`. — *end note*]
2561
 
2562
  ``` cpp
 
2566
  // types
2567
  using result_type = RealType;
2568
  using param_type = unspecified;
2569
 
2570
  // constructors and reset functions
2571
+ uniform_real_distribution() : uniform_real_distribution(0.0) {}
2572
+ explicit uniform_real_distribution(RealType a, RealType b = 1.0);
2573
  explicit uniform_real_distribution(const param_type& parm);
2574
  void reset();
2575
 
2576
  // generating functions
2577
  template<class URBG>
 
2588
  result_type max() const;
2589
  };
2590
  ```
2591
 
2592
  ``` cpp
2593
+ explicit uniform_real_distribution(RealType a, RealType b = 1.0);
2594
  ```
2595
 
2596
+ *Preconditions:* `a` ≤ `b` and
2597
+ `b` - `a` ≤ `numeric_limits<RealType>::max()`.
2598
 
2599
+ *Remarks:* `a` and `b` correspond to the respective parameters of the
2600
+ distribution.
2601
 
2602
  ``` cpp
2603
  result_type a() const;
2604
  ```
2605
 
 
2616
  #### Bernoulli distributions <a id="rand.dist.bern">[[rand.dist.bern]]</a>
2617
 
2618
  ##### Class `bernoulli_distribution` <a id="rand.dist.bern.bernoulli">[[rand.dist.bern.bernoulli]]</a>
2619
 
2620
  A `bernoulli_distribution` random number distribution produces `bool`
2621
+ values b distributed according to the discrete probability function
2622
+ $$P(b\,|\,p) = \left\{ \begin{array}{ll}
2623
+ p & \text{ if $b = \tcode{true}$, or} \\
2624
+ 1 - p & \text{ if $b = \tcode{false}$.}
2625
+ \end{array}\right.$$
 
 
2626
 
2627
  ``` cpp
2628
  class bernoulli_distribution {
2629
  public:
2630
  // types
2631
  using result_type = bool;
2632
  using param_type = unspecified;
2633
 
2634
  // constructors and reset functions
2635
+ bernoulli_distribution() : bernoulli_distribution(0.5) {}
2636
+ explicit bernoulli_distribution(double p);
2637
  explicit bernoulli_distribution(const param_type& parm);
2638
  void reset();
2639
 
2640
  // generating functions
2641
  template<class URBG>
 
2651
  result_type max() const;
2652
  };
2653
  ```
2654
 
2655
  ``` cpp
2656
+ explicit bernoulli_distribution(double p);
2657
  ```
2658
 
2659
+ *Preconditions:* 0 ≤ `p` ≤ 1.
2660
 
2661
+ *Remarks:* `p` corresponds to the parameter of the distribution.
 
2662
 
2663
  ``` cpp
2664
  double p() const;
2665
  ```
2666
 
 
2669
 
2670
  ##### Class template `binomial_distribution` <a id="rand.dist.bern.bin">[[rand.dist.bern.bin]]</a>
2671
 
2672
  A `binomial_distribution` random number distribution produces integer
2673
  values i ≥ 0 distributed according to the discrete probability function
2674
+ $$P(i\,|\,t,p) = \binom{t}{i} \cdot p^i \cdot (1-p)^{t-i} \text{ .}$$
 
 
 
2675
 
2676
  ``` cpp
2677
  template<class IntType = int>
2678
  class binomial_distribution {
2679
  public:
2680
  // types
2681
  using result_type = IntType;
2682
  using param_type = unspecified;
2683
 
2684
  // constructors and reset functions
2685
+ binomial_distribution() : binomial_distribution(1) {}
2686
+ explicit binomial_distribution(IntType t, double p = 0.5);
2687
  explicit binomial_distribution(const param_type& parm);
2688
  void reset();
2689
 
2690
  // generating functions
2691
  template<class URBG>
 
2702
  result_type max() const;
2703
  };
2704
  ```
2705
 
2706
  ``` cpp
2707
+ explicit binomial_distribution(IntType t, double p = 0.5);
2708
  ```
2709
 
2710
+ *Preconditions:* 0 ≤ `p` ≤ 1 and 0 ≤ `t`.
2711
 
2712
+ *Remarks:* `t` and `p` correspond to the respective parameters of the
2713
+ distribution.
2714
 
2715
  ``` cpp
2716
  IntType t() const;
2717
  ```
2718
 
 
2728
 
2729
  ##### Class template `geometric_distribution` <a id="rand.dist.bern.geo">[[rand.dist.bern.geo]]</a>
2730
 
2731
  A `geometric_distribution` random number distribution produces integer
2732
  values i ≥ 0 distributed according to the discrete probability function
2733
+ $$P(i\,|\,p) = p \cdot (1-p)^{i} \text{ .}$$
 
 
 
2734
 
2735
  ``` cpp
2736
  template<class IntType = int>
2737
  class geometric_distribution {
2738
  public:
2739
  // types
2740
  using result_type = IntType;
2741
  using param_type = unspecified;
2742
 
2743
  // constructors and reset functions
2744
+ geometric_distribution() : geometric_distribution(0.5) {}
2745
+ explicit geometric_distribution(double p);
2746
  explicit geometric_distribution(const param_type& parm);
2747
  void reset();
2748
 
2749
  // generating functions
2750
  template<class URBG>
 
2760
  result_type max() const;
2761
  };
2762
  ```
2763
 
2764
  ``` cpp
2765
+ explicit geometric_distribution(double p);
2766
  ```
2767
 
2768
+ *Preconditions:* 0 < `p` < 1.
2769
 
2770
+ *Remarks:* `p` corresponds to the parameter of the distribution.
 
2771
 
2772
  ``` cpp
2773
  double p() const;
2774
  ```
2775
 
 
2778
 
2779
  ##### Class template `negative_binomial_distribution` <a id="rand.dist.bern.negbin">[[rand.dist.bern.negbin]]</a>
2780
 
2781
  A `negative_binomial_distribution` random number distribution produces
2782
  random integers i ≥ 0 distributed according to the discrete probability
2783
+ function
2784
+ $$P(i\,|\,k,p) = \binom{k+i-1}{i} \cdot p^k \cdot (1-p)^i \text{ .}$$
 
 
2785
 
2786
  [*Note 1*: This implies that P(i | k,p) is undefined when
2787
  `p == 1`. — *end note*]
2788
 
2789
  ``` cpp
 
2793
  // types
2794
  using result_type = IntType;
2795
  using param_type = unspecified;
2796
 
2797
  // constructor and reset functions
2798
+ negative_binomial_distribution() : negative_binomial_distribution(1) {}
2799
+ explicit negative_binomial_distribution(IntType k, double p = 0.5);
2800
  explicit negative_binomial_distribution(const param_type& parm);
2801
  void reset();
2802
 
2803
  // generating functions
2804
  template<class URBG>
 
2815
  result_type max() const;
2816
  };
2817
  ```
2818
 
2819
  ``` cpp
2820
+ explicit negative_binomial_distribution(IntType k, double p = 0.5);
2821
  ```
2822
 
2823
+ *Preconditions:* 0 < `p` ≤ 1 and 0 < `k`.
2824
 
2825
+ *Remarks:* `k` and `p` correspond to the respective parameters of the
2826
+ distribution.
2827
 
2828
  ``` cpp
2829
  IntType k() const;
2830
  ```
2831
 
 
2843
 
2844
  ##### Class template `poisson_distribution` <a id="rand.dist.pois.poisson">[[rand.dist.pois.poisson]]</a>
2845
 
2846
  A `poisson_distribution` random number distribution produces integer
2847
  values i ≥ 0 distributed according to the discrete probability function
2848
+ $$P(i\,|\,\mu) = \frac{e^{-\mu} \mu^{i}}{i\,!} \text{ .}$$ The
2849
+ distribution parameter μ is also known as this distribution’s *mean* .
 
 
 
 
2850
 
2851
  ``` cpp
2852
  template<class IntType = int>
2853
  class poisson_distribution
2854
  {
 
2856
  // types
2857
  using result_type = IntType;
2858
  using param_type = unspecified;
2859
 
2860
  // constructors and reset functions
2861
+ poisson_distribution() : poisson_distribution(1.0) {}
2862
+ explicit poisson_distribution(double mean);
2863
  explicit poisson_distribution(const param_type& parm);
2864
  void reset();
2865
 
2866
  // generating functions
2867
  template<class URBG>
 
2877
  result_type max() const;
2878
  };
2879
  ```
2880
 
2881
  ``` cpp
2882
+ explicit poisson_distribution(double mean);
2883
  ```
2884
 
2885
+ *Preconditions:* 0 < `mean`.
2886
 
2887
+ *Remarks:* `mean` corresponds to the parameter of the distribution.
 
2888
 
2889
  ``` cpp
2890
  double mean() const;
2891
  ```
2892
 
 
2895
 
2896
  ##### Class template `exponential_distribution` <a id="rand.dist.pois.exp">[[rand.dist.pois.exp]]</a>
2897
 
2898
  An `exponential_distribution` random number distribution produces random
2899
  numbers x > 0 distributed according to the probability density function
2900
+ $$p(x\,|\,\lambda) = \lambda e^{-\lambda x} \text{ .}$$
 
 
 
2901
 
2902
  ``` cpp
2903
  template<class RealType = double>
2904
  class exponential_distribution {
2905
  public:
2906
  // types
2907
  using result_type = RealType;
2908
  using param_type = unspecified;
2909
 
2910
  // constructors and reset functions
2911
+ exponential_distribution() : exponential_distribution(1.0) {}
2912
+ explicit exponential_distribution(RealType lambda);
2913
  explicit exponential_distribution(const param_type& parm);
2914
  void reset();
2915
 
2916
  // generating functions
2917
  template<class URBG>
 
2927
  result_type max() const;
2928
  };
2929
  ```
2930
 
2931
  ``` cpp
2932
+ explicit exponential_distribution(RealType lambda);
2933
  ```
2934
 
2935
+ *Preconditions:* 0 < `lambda`.
2936
 
2937
+ *Remarks:* `lambda` corresponds to the parameter of the distribution.
 
2938
 
2939
  ``` cpp
2940
  RealType lambda() const;
2941
  ```
2942
 
 
2945
 
2946
  ##### Class template `gamma_distribution` <a id="rand.dist.pois.gamma">[[rand.dist.pois.gamma]]</a>
2947
 
2948
  A `gamma_distribution` random number distribution produces random
2949
  numbers x > 0 distributed according to the probability density function
2950
+ $$p(x\,|\,\alpha,\beta) =
2951
+ \frac{e^{-x/\beta}}{\beta^{\alpha} \cdot \Gamma(\alpha)} \, \cdot \, x^{\, \alpha-1}
2952
+ \text{ .}$$
 
 
2953
 
2954
  ``` cpp
2955
  template<class RealType = double>
2956
  class gamma_distribution {
2957
  public:
2958
  // types
2959
  using result_type = RealType;
2960
  using param_type = unspecified;
2961
 
2962
  // constructors and reset functions
2963
+ gamma_distribution() : gamma_distribution(1.0) {}
2964
+ explicit gamma_distribution(RealType alpha, RealType beta = 1.0);
2965
  explicit gamma_distribution(const param_type& parm);
2966
  void reset();
2967
 
2968
  // generating functions
2969
  template<class URBG>
 
2980
  result_type max() const;
2981
  };
2982
  ```
2983
 
2984
  ``` cpp
2985
+ explicit gamma_distribution(RealType alpha, RealType beta = 1.0);
2986
  ```
2987
 
2988
+ *Preconditions:* 0 < `alpha` and 0 < `beta`.
2989
 
2990
+ *Remarks:* `alpha` and `beta` correspond to the parameters of the
2991
+ distribution.
2992
 
2993
  ``` cpp
2994
  RealType alpha() const;
2995
  ```
2996
 
 
3006
 
3007
  ##### Class template `weibull_distribution` <a id="rand.dist.pois.weibull">[[rand.dist.pois.weibull]]</a>
3008
 
3009
  A `weibull_distribution` random number distribution produces random
3010
  numbers x ≥ 0 distributed according to the probability density function
3011
+ $$p(x\,|\,a,b) = \frac{a}{b}
 
 
3012
  \cdot \left(\frac{x}{b}\right)^{a-1}
3013
  \cdot \, \exp\left( -\left(\frac{x}{b}\right)^a\right)
3014
+ \text{ .}$$
3015
 
3016
  ``` cpp
3017
  template<class RealType = double>
3018
  class weibull_distribution {
3019
  public:
3020
  // types
3021
  using result_type = RealType;
3022
  using param_type = unspecified;
3023
 
3024
  // constructor and reset functions
3025
+ weibull_distribution() : weibull_distribution(1.0) {}
3026
+ explicit weibull_distribution(RealType a, RealType b = 1.0);
3027
  explicit weibull_distribution(const param_type& parm);
3028
  void reset();
3029
 
3030
  // generating functions
3031
  template<class URBG>
 
3042
  result_type max() const;
3043
  };
3044
  ```
3045
 
3046
  ``` cpp
3047
+ explicit weibull_distribution(RealType a, RealType b = 1.0);
3048
  ```
3049
 
3050
+ *Preconditions:* 0 < `a` and 0 < `b`.
3051
 
3052
+ *Remarks:* `a` and `b` correspond to the respective parameters of the
3053
+ distribution.
3054
 
3055
  ``` cpp
3056
  RealType a() const;
3057
  ```
3058
 
 
3068
 
3069
  ##### Class template `extreme_value_distribution` <a id="rand.dist.pois.extreme">[[rand.dist.pois.extreme]]</a>
3070
 
3071
  An `extreme_value_distribution` random number distribution produces
3072
  random numbers x distributed according to the probability density
3073
+ function[^6] $$p(x\,|\,a,b) = \frac{1}{b}
3074
+ \cdot \exp\left(\frac{a-x}{b} - \exp\left(\frac{a-x}{b}\right)\right)
3075
+ \text{ .}$$
 
 
 
 
3076
 
3077
  ``` cpp
3078
  template<class RealType = double>
3079
  class extreme_value_distribution {
3080
  public:
3081
  // types
3082
  using result_type = RealType;
3083
  using param_type = unspecified;
3084
 
3085
  // constructor and reset functions
3086
+ extreme_value_distribution() : extreme_value_distribution(0.0) {}
3087
+ explicit extreme_value_distribution(RealType a, RealType b = 1.0);
3088
  explicit extreme_value_distribution(const param_type& parm);
3089
  void reset();
3090
 
3091
  // generating functions
3092
  template<class URBG>
 
3103
  result_type max() const;
3104
  };
3105
  ```
3106
 
3107
  ``` cpp
3108
+ explicit extreme_value_distribution(RealType a, RealType b = 1.0);
3109
  ```
3110
 
3111
+ *Preconditions:* 0 < `b`.
3112
 
3113
+ *Remarks:* `a` and `b` correspond to the respective parameters of the
3114
+ distribution.
3115
 
3116
  ``` cpp
3117
  RealType a() const;
3118
  ```
3119
 
 
3139
  % e^{-(x-\mu)^2 / (2\sigma^2)}
3140
  \exp{\left(- \, \frac{(x - \mu)^2}
3141
  {2 \sigma^2}
3142
  \right)
3143
  }
3144
+ \text{ .}$$ The distribution parameters μ and σ are also known as this
3145
  distribution’s *mean* and *standard deviation* .
3146
 
3147
  ``` cpp
3148
  template<class RealType = double>
3149
  class normal_distribution {
 
3151
  // types
3152
  using result_type = RealType;
3153
  using param_type = unspecified;
3154
 
3155
  // constructors and reset functions
3156
+ normal_distribution() : normal_distribution(0.0) {}
3157
+ explicit normal_distribution(RealType mean, RealType stddev = 1.0);
3158
  explicit normal_distribution(const param_type& parm);
3159
  void reset();
3160
 
3161
  // generating functions
3162
  template<class URBG>
 
3173
  result_type max() const;
3174
  };
3175
  ```
3176
 
3177
  ``` cpp
3178
+ explicit normal_distribution(RealType mean, RealType stddev = 1.0);
3179
  ```
3180
 
3181
+ *Preconditions:* 0 < `stddev`.
3182
 
3183
+ *Remarks:* `mean` and `stddev` correspond to the respective parameters
3184
+ of the distribution.
3185
 
3186
  ``` cpp
3187
  RealType mean() const;
3188
  ```
3189
 
 
3199
 
3200
  ##### Class template `lognormal_distribution` <a id="rand.dist.norm.lognormal">[[rand.dist.norm.lognormal]]</a>
3201
 
3202
  A `lognormal_distribution` random number distribution produces random
3203
  numbers x > 0 distributed according to the probability density function
3204
+ $$p(x\,|\,m,s) = \frac{1}{s x \sqrt{2 \pi}}
3205
+ \cdot \exp{\left(-\frac{(\ln{x} - m)^2}{2 s^2}\right)}
3206
+ \text{ .}$$
 
 
 
 
 
 
 
3207
 
3208
  ``` cpp
3209
  template<class RealType = double>
3210
  class lognormal_distribution {
3211
  public:
3212
  // types
3213
  using result_type = RealType;
3214
  using param_type = unspecified;
3215
 
3216
  // constructor and reset functions
3217
+ lognormal_distribution() : lognormal_distribution(0.0) {}
3218
+ explicit lognormal_distribution(RealType m, RealType s = 1.0);
3219
  explicit lognormal_distribution(const param_type& parm);
3220
  void reset();
3221
 
3222
  // generating functions
3223
  template<class URBG>
 
3234
  result_type max() const;
3235
  };
3236
  ```
3237
 
3238
  ``` cpp
3239
+ explicit lognormal_distribution(RealType m, RealType s = 1.0);
3240
  ```
3241
 
3242
+ *Preconditions:* 0 < `s`.
3243
 
3244
+ *Remarks:* `m` and `s` correspond to the respective parameters of the
3245
+ distribution.
3246
 
3247
  ``` cpp
3248
  RealType m() const;
3249
  ```
3250
 
 
3260
 
3261
  ##### Class template `chi_squared_distribution` <a id="rand.dist.norm.chisq">[[rand.dist.norm.chisq]]</a>
3262
 
3263
  A `chi_squared_distribution` random number distribution produces random
3264
  numbers x > 0 distributed according to the probability density function
3265
+ $$p(x\,|\,n) = \frac{x^{(n/2)-1} \cdot e^{-x/2}}{\Gamma(n/2) \cdot 2^{n/2}} \text{ .}$$
 
 
 
 
3266
 
3267
  ``` cpp
3268
  template<class RealType = double>
3269
  class chi_squared_distribution {
3270
  public:
3271
  // types
3272
  using result_type = RealType;
3273
  using param_type = unspecified;
3274
 
3275
  // constructor and reset functions
3276
+ chi_squared_distribution() : chi_squared_distribution(1.0) {}
3277
+ explicit chi_squared_distribution(RealType n);
3278
  explicit chi_squared_distribution(const param_type& parm);
3279
  void reset();
3280
 
3281
  // generating functions
3282
  template<class URBG>
 
3292
  result_type max() const;
3293
  };
3294
  ```
3295
 
3296
  ``` cpp
3297
+ explicit chi_squared_distribution(RealType n);
3298
  ```
3299
 
3300
+ *Preconditions:* 0 < `n`.
3301
 
3302
+ *Remarks:* `n` corresponds to the parameter of the distribution.
 
3303
 
3304
  ``` cpp
3305
  RealType n() const;
3306
  ```
3307
 
 
3309
  constructed.
3310
 
3311
  ##### Class template `cauchy_distribution` <a id="rand.dist.norm.cauchy">[[rand.dist.norm.cauchy]]</a>
3312
 
3313
  A `cauchy_distribution` random number distribution produces random
3314
+ numbers x distributed according to the probability density function
3315
+ $$p(x\,|\,a,b) = \left(\pi b \left(1 + \left(\frac{x-a}{b} \right)^2 \, \right)\right)^{-1} \text{ .}$$
 
 
3316
 
3317
  ``` cpp
3318
  template<class RealType = double>
3319
  class cauchy_distribution {
3320
  public:
3321
  // types
3322
  using result_type = RealType;
3323
  using param_type = unspecified;
3324
 
3325
  // constructor and reset functions
3326
+ cauchy_distribution() : cauchy_distribution(0.0) {}
3327
+ explicit cauchy_distribution(RealType a, RealType b = 1.0);
3328
  explicit cauchy_distribution(const param_type& parm);
3329
  void reset();
3330
 
3331
  // generating functions
3332
  template<class URBG>
 
3343
  result_type max() const;
3344
  };
3345
  ```
3346
 
3347
  ``` cpp
3348
+ explicit cauchy_distribution(RealType a, RealType b = 1.0);
3349
  ```
3350
 
3351
+ *Preconditions:* 0 < `b`.
3352
 
3353
+ *Remarks:* `a` and `b` correspond to the respective parameters of the
3354
+ distribution.
3355
 
3356
  ``` cpp
3357
  RealType a() const;
3358
  ```
3359
 
 
3369
 
3370
  ##### Class template `fisher_f_distribution` <a id="rand.dist.norm.f">[[rand.dist.norm.f]]</a>
3371
 
3372
  A `fisher_f_distribution` random number distribution produces random
3373
  numbers x ≥ 0 distributed according to the probability density function
3374
+ $$p(x\,|\,m,n) = \frac{\Gamma\big((m+n)/2\big)}{\Gamma(m/2) \; \Gamma(n/2)}
3375
+ \cdot \left(\frac{m}{n}\right)^{m/2}
3376
+ \cdot x^{(m/2)-1}
3377
+ \cdot \left(1 + \frac{m x}{n}\right)^{-(m + n)/2}
3378
+ \text{ .}$$
 
 
 
 
 
 
3379
 
3380
  ``` cpp
3381
  template<class RealType = double>
3382
  class fisher_f_distribution {
3383
  public:
3384
  // types
3385
  using result_type = RealType;
3386
  using param_type = unspecified;
3387
 
3388
  // constructor and reset functions
3389
+ fisher_f_distribution() : fisher_f_distribution(1.0) {}
3390
+ explicit fisher_f_distribution(RealType m, RealType n = 1.0);
3391
  explicit fisher_f_distribution(const param_type& parm);
3392
  void reset();
3393
 
3394
  // generating functions
3395
  template<class URBG>
 
3406
  result_type max() const;
3407
  };
3408
  ```
3409
 
3410
  ``` cpp
3411
+ explicit fisher_f_distribution(RealType m, RealType n = 1);
3412
  ```
3413
 
3414
+ *Preconditions:* 0 < `m` and 0 < `n`.
3415
 
3416
+ *Remarks:* `m` and `n` correspond to the respective parameters of the
3417
+ distribution.
3418
 
3419
  ``` cpp
3420
  RealType m() const;
3421
  ```
3422
 
 
3431
  constructed.
3432
 
3433
  ##### Class template `student_t_distribution` <a id="rand.dist.norm.t">[[rand.dist.norm.t]]</a>
3434
 
3435
  A `student_t_distribution` random number distribution produces random
3436
+ numbers x distributed according to the probability density function
3437
+ $$p(x\,|\,n) = \frac{1}{\sqrt{n \pi}}
3438
+ \cdot \frac{\Gamma\big((n+1)/2\big)}{\Gamma(n/2)}
 
 
 
3439
  \cdot \left(1 + \frac{x^2}{n} \right)^{-(n+1)/2}
3440
+ \text{ .}$$
3441
 
3442
  ``` cpp
3443
  template<class RealType = double>
3444
  class student_t_distribution {
3445
  public:
3446
  // types
3447
  using result_type = RealType;
3448
  using param_type = unspecified;
3449
 
3450
  // constructor and reset functions
3451
+ student_t_distribution() : student_t_distribution(1.0) {}
3452
+ explicit student_t_distribution(RealType n);
3453
  explicit student_t_distribution(const param_type& parm);
3454
  void reset();
3455
 
3456
  // generating functions
3457
  template<class URBG>
 
3467
  result_type max() const;
3468
  };
3469
  ```
3470
 
3471
  ``` cpp
3472
+ explicit student_t_distribution(RealType n);
3473
  ```
3474
 
3475
+ *Preconditions:* 0 < `n`.
3476
 
3477
+ *Remarks:* `n` corresponds to the parameter of the distribution.
 
3478
 
3479
  ``` cpp
3480
  RealType n() const;
3481
  ```
3482
 
 
3487
 
3488
  ##### Class template `discrete_distribution` <a id="rand.dist.samp.discrete">[[rand.dist.samp.discrete]]</a>
3489
 
3490
  A `discrete_distribution` random number distribution produces random
3491
  integers i, 0 ≤ i < n, distributed according to the discrete probability
3492
+ function $$P(i \,|\, p_0, \dotsc, p_{n-1}) = p_i \text{ .}$$
 
 
 
3493
 
3494
  Unless specified otherwise, the distribution parameters are calculated
3495
+ as: pₖ = {wₖ / S} for k = 0, , n - 1, in which the values wₖ, commonly
3496
+ known as the *weights* , shall be non-negative, non-NaN, and
3497
+ non-infinity. Moreover, the following relation shall hold:
3498
+ $0 < S = w_0 + \dotsb + w_{n - 1}$.
3499
 
3500
  ``` cpp
3501
  template<class IntType = int>
3502
  class discrete_distribution {
3503
  public:
 
3543
  ``` cpp
3544
  template<class InputIterator>
3545
  discrete_distribution(InputIterator firstW, InputIterator lastW);
3546
  ```
3547
 
3548
+ *Mandates:*
3549
+ `is_convertible_v<iterator_traits<InputIterator>::value_type, double>`
3550
+ is `true`.
3551
+
3552
+ *Preconditions:* `InputIterator` meets the *Cpp17InputIterator*
3553
+ requirements [[input.iterators]]. If `firstW == lastW`, let n = 1 and
3554
+ w₀ = 1. Otherwise, [`firstW`, `lastW`) forms a sequence w of length
3555
+ n > 0.
3556
 
3557
  *Effects:* Constructs a `discrete_distribution` object with
3558
  probabilities given by the formula above.
3559
 
3560
  ``` cpp
 
3566
  ``` cpp
3567
  template<class UnaryOperation>
3568
  discrete_distribution(size_t nw, double xmin, double xmax, UnaryOperation fw);
3569
  ```
3570
 
3571
+ *Mandates:* `is_invocable_r_v<double, UnaryOperation&, double>` is
3572
+ `true`.
3573
+
3574
+ *Preconditions:* If `nw` = 0, let n = 1, otherwise let n = `nw`. The
3575
+ relation 0 < δ = (`xmax` - `xmin`) / n holds.
3576
 
3577
  *Effects:* Constructs a `discrete_distribution` object with
3578
  probabilities given by the formula above, using the following values: If
3579
  `nw` = 0, let w₀ = 1. Otherwise, let wₖ = `fw`(`xmin` + k ⋅ δ + δ / 2)
3580
  for k = 0, …, n - 1.
3581
 
3582
+ *Complexity:* The number of invocations of `fw` does not exceed n.
3583
 
3584
  ``` cpp
3585
  vector<double> probabilities() const;
3586
  ```
3587
 
 
3592
  ##### Class template `piecewise_constant_distribution` <a id="rand.dist.samp.pconst">[[rand.dist.samp.pconst]]</a>
3593
 
3594
  A `piecewise_constant_distribution` random number distribution produces
3595
  random numbers x, b₀ ≤ x < bₙ, uniformly distributed over each
3596
  subinterval [ bᵢ, bᵢ₊₁ ) according to the probability density function
3597
+ $$p(x \,|\, b_0, \dotsc, b_n, \; \rho_0, \dotsc, \rho_{n-1}) = \rho_i
3598
+ \text{ , for $b_i \le x < b_{i+1}$.}$$
 
 
 
 
3599
 
3600
  The n + 1 distribution parameters bᵢ, also known as this distribution’s
3601
+ *interval boundaries* , shall satisfy the relation $b_i < b_{i + 1}$ for
3602
+ i = 0, …, n - 1. Unless specified otherwise, the remaining n
3603
+ distribution parameters are calculated as:
3604
+ $$\rho_k = \frac{w_k}{S \cdot (b_{k+1}-b_k)} \text{ for } k = 0, \dotsc, n - 1 \text{ ,}$$
3605
+ in which the values wₖ, commonly known as the *weights* , shall be
3606
+ non-negative, non-NaN, and non-infinity. Moreover, the following
3607
+ relation shall hold: 0 < S = w₀ + + wₙ₋₁.
 
 
3608
 
3609
  ``` cpp
3610
  template<class RealType = double>
3611
  class piecewise_constant_distribution {
3612
  public:
 
3654
  template<class InputIteratorB, class InputIteratorW>
3655
  piecewise_constant_distribution(InputIteratorB firstB, InputIteratorB lastB,
3656
  InputIteratorW firstW);
3657
  ```
3658
 
3659
+ *Mandates:* Both of
3660
+
3661
+ - `is_convertible_v<iterator_traits<InputIteratorB>::value_type, double>`
3662
+ - `is_convertible_v<iterator_traits<InputIteratorW>::value_type, double>`
3663
+
3664
+ are `true`.
3665
+
3666
+ *Preconditions:* `InputIteratorB` and `InputIteratorW` each meet the
3667
+ *Cpp17InputIterator* requirements [[input.iterators]]. If
3668
+ `firstB == lastB` or `++firstB == lastB`, let n = 1, w₀ = 1, b₀ = 0, and
3669
+ b₁ = 1. Otherwise, [`firstB`, `lastB`) forms a sequence b of length n+1,
3670
+ the length of the sequence w starting from `firstW` is at least n, and
3671
+ any wₖ for k ≥ n are ignored by the distribution.
3672
 
3673
  *Effects:* Constructs a `piecewise_constant_distribution` object with
3674
  parameters as specified above.
3675
 
3676
  ``` cpp
3677
  template<class UnaryOperation>
3678
  piecewise_constant_distribution(initializer_list<RealType> bl, UnaryOperation fw);
3679
  ```
3680
 
3681
+ *Mandates:* `is_invocable_r_v<double, UnaryOperation&, double>` is
3682
+ `true`.
 
 
3683
 
3684
  *Effects:* Constructs a `piecewise_constant_distribution` object with
3685
  parameters taken or calculated from the following values: If
3686
  `bl.size()` < 2, let n = 1, w₀ = 1, b₀ = 0, and b₁ = 1. Otherwise, let
3687
  [`bl.begin()`, `bl.end()`) form a sequence b₀, …, bₙ, and let
3688
  wₖ = `fw`((bₖ₊₁ + bₖ) / 2) for k = 0, …, n - 1.
3689
 
3690
+ *Complexity:* The number of invocations of `fw` does not exceed n.
3691
 
3692
  ``` cpp
3693
  template<class UnaryOperation>
3694
  piecewise_constant_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);
3695
  ```
3696
 
3697
+ *Mandates:* `is_invocable_r_v<double, UnaryOperation&, double>` is
3698
+ `true`.
3699
+
3700
+ *Preconditions:* If `nw` = 0, let n = 1, otherwise let n = `nw`. The
3701
+ relation 0 < δ = (`xmax` - `xmin`) / n holds.
3702
 
3703
  *Effects:* Constructs a `piecewise_constant_distribution` object with
3704
  parameters taken or calculated from the following values: Let
3705
  bₖ = `xmin` + k ⋅ δ for k = 0, …, n, and wₖ = `fw`(bₖ + δ / 2) for
3706
  k = 0, …, n - 1.
3707
 
3708
+ *Complexity:* The number of invocations of `fw` does not exceed n.
3709
 
3710
  ``` cpp
3711
  vector<result_type> intervals() const;
3712
  ```
3713
 
 
3725
 
3726
  ##### Class template `piecewise_linear_distribution` <a id="rand.dist.samp.plinear">[[rand.dist.samp.plinear]]</a>
3727
 
3728
  A `piecewise_linear_distribution` random number distribution produces
3729
  random numbers x, b₀ ≤ x < bₙ, distributed over each subinterval
3730
+ [bᵢ, bᵢ₊₁) according to the probability density function
3731
+ $$p(x \,|\, b_0, \dotsc, b_n, \; \rho_0, \dotsc, \rho_n)
3732
+ = \rho_{i} \cdot {\frac{b_{i+1} - x}{b_{i+1} - b_i}}
3733
  + \rho_{i+1} \cdot {\frac{x - b_i}{b_{i+1} - b_i}}
3734
+ \text{ , for $b_i \le x < b_{i+1}$.}$$
 
 
3735
 
3736
  The n + 1 distribution parameters bᵢ, also known as this distribution’s
3737
  *interval boundaries* , shall satisfy the relation bᵢ < bᵢ₊₁ for
3738
  i = 0, …, n - 1. Unless specified otherwise, the remaining n + 1
3739
+ distribution parameters are calculated as ρₖ = {wₖ / S} for k = 0, …, n,
3740
+ in which the values wₖ, commonly known as the *weights at boundaries* ,
3741
+ shall be non-negative, non-NaN, and non-infinity. Moreover, the
3742
+ following relation shall hold:
3743
+ $$0 < S = \frac{1}{2} \cdot \sum_{k=0}^{n-1} (w_k + w_{k+1}) \cdot (b_{k+1} - b_k) \text{ .}$$
 
 
 
3744
 
3745
  ``` cpp
3746
  template<class RealType = double>
3747
  class piecewise_linear_distribution {
3748
  public:
 
3789
  template<class InputIteratorB, class InputIteratorW>
3790
  piecewise_linear_distribution(InputIteratorB firstB, InputIteratorB lastB,
3791
  InputIteratorW firstW);
3792
  ```
3793
 
3794
+ *Mandates:* `is_invocable_r_v<double, UnaryOperation&, double>` is
3795
+ `true`.
3796
+
3797
+ *Preconditions:* `InputIteratorB` and `InputIteratorW` each meet the
3798
+ *Cpp17InputIterator* requirements [[input.iterators]]. If
3799
+ `firstB == lastB` or `++firstB == lastB`, let n = 1, ρ₀ = ρ₁ = 1,
3800
+ b₀ = 0, and b₁ = 1. Otherwise, [`firstB`, `lastB`) forms a sequence b of
3801
+ length n+1, the length of the sequence w starting from `firstW` is at
3802
+ least n+1, and any w for k n + 1 are ignored by the distribution.
 
3803
 
3804
  *Effects:* Constructs a `piecewise_linear_distribution` object with
3805
  parameters as specified above.
3806
 
3807
  ``` cpp
3808
  template<class UnaryOperation>
3809
  piecewise_linear_distribution(initializer_list<RealType> bl, UnaryOperation fw);
3810
  ```
3811
 
3812
+ *Mandates:* `is_invocable_r_v<double, UnaryOperation&, double>` is
3813
+ `true`.
 
 
3814
 
3815
  *Effects:* Constructs a `piecewise_linear_distribution` object with
3816
  parameters taken or calculated from the following values: If
3817
  `bl.size()` < 2, let n = 1, ρ₀ = ρ₁ = 1, b₀ = 0, and b₁ = 1. Otherwise,
3818
  let [`bl.begin(),` `bl.end()`) form a sequence b₀, …, bₙ, and let
3819
  wₖ = `fw`(bₖ) for k = 0, …, n.
3820
 
3821
+ *Complexity:* The number of invocations of `fw` does not exceed n+1.
3822
 
3823
  ``` cpp
3824
  template<class UnaryOperation>
3825
  piecewise_linear_distribution(size_t nw, RealType xmin, RealType xmax, UnaryOperation fw);
3826
  ```
3827
 
3828
+ *Mandates:* `is_invocable_r_v<double, UnaryOperation&, double>` is
3829
+ `true`.
3830
+
3831
+ *Preconditions:* If `nw` = 0, let n = 1, otherwise let n = `nw`. The
3832
+ relation 0 < δ = (`xmax` - `xmin`) / n holds.
3833
 
3834
  *Effects:* Constructs a `piecewise_linear_distribution` object with
3835
  parameters taken or calculated from the following values: Let
3836
  bₖ = `xmin` + k ⋅ δ for k = 0, …, n, and wₖ = `fw`(bₖ) for k = 0, …, n.
3837
 
3838
+ *Complexity:* The number of invocations of `fw` does not exceed n+1.
3839
 
3840
  ``` cpp
3841
  vector<result_type> intervals() const;
3842
  ```
3843
 
 
3853
  whose `operator[]` member returns ρₖ when invoked with argument k for
3854
  k = 0, …, n.
3855
 
3856
  ### Low-quality random number generation <a id="c.math.rand">[[c.math.rand]]</a>
3857
 
3858
+ [*Note 1*: The header `<cstdlib>` declares the functions described in
3859
+ this subclause. — *end note*]
3860
 
3861
  ``` cpp
3862
  int rand();
3863
  void srand(unsigned int seed);
3864
  ```
 
3866
  *Effects:* The `rand` and `srand` functions have the semantics specified
3867
  in the C standard library.
3868
 
3869
  *Remarks:* The implementation may specify that particular library
3870
  functions may call `rand`. It is *implementation-defined* whether the
3871
+ `rand` function may introduce data races [[res.on.data.races]].
3872
 
3873
  [*Note 1*: The other random number generation facilities in this
3874
+ document [[rand]] are often preferable to `rand`, because `rand`’s
3875
+ underlying algorithm is unspecified. Use of `rand` therefore continues
3876
+ to be non-portable, with unpredictable and oft-questionable quality and
3877
+ performance. — *end note*]
3878
 
3879
+ See also: ISO C 7.22.2
3880
 
3881
  ## Numeric arrays <a id="numarray">[[numarray]]</a>
3882
 
3883
  ### Header `<valarray>` synopsis <a id="valarray.syn">[[valarray.syn]]</a>
3884
 
 
3895
  template<class T> class indirect_array; // an indirected array
3896
 
3897
  template<class T> void swap(valarray<T>&, valarray<T>&) noexcept;
3898
 
3899
  template<class T> valarray<T> operator* (const valarray<T>&, const valarray<T>&);
3900
+ template<class T> valarray<T> operator* (const valarray<T>&,
3901
+ const typename valarray<T>::value_type&);
3902
+ template<class T> valarray<T> operator* (const typename valarray<T>::value_type&,
3903
+ const valarray<T>&);
3904
 
3905
  template<class T> valarray<T> operator/ (const valarray<T>&, const valarray<T>&);
3906
+ template<class T> valarray<T> operator/ (const valarray<T>&,
3907
+ const typename valarray<T>::value_type&);
3908
+ template<class T> valarray<T> operator/ (const typename valarray<T>::value_type&,
3909
+ const valarray<T>&);
3910
 
3911
  template<class T> valarray<T> operator% (const valarray<T>&, const valarray<T>&);
3912
+ template<class T> valarray<T> operator% (const valarray<T>&,
3913
+ const typename valarray<T>::value_type&);
3914
+ template<class T> valarray<T> operator% (const typename valarray<T>::value_type&,
3915
+ const valarray<T>&);
3916
 
3917
  template<class T> valarray<T> operator+ (const valarray<T>&, const valarray<T>&);
3918
+ template<class T> valarray<T> operator+ (const valarray<T>&,
3919
+ const typename valarray<T>::value_type&);
3920
+ template<class T> valarray<T> operator+ (const typename valarray<T>::value_type&,
3921
+ const valarray<T>&);
3922
 
3923
  template<class T> valarray<T> operator- (const valarray<T>&, const valarray<T>&);
3924
+ template<class T> valarray<T> operator- (const valarray<T>&,
3925
+ const typename valarray<T>::value_type&);
3926
+ template<class T> valarray<T> operator- (const typename valarray<T>::value_type&,
3927
+ const valarray<T>&);
3928
 
3929
  template<class T> valarray<T> operator^ (const valarray<T>&, const valarray<T>&);
3930
+ template<class T> valarray<T> operator^ (const valarray<T>&,
3931
+ const typename valarray<T>::value_type&);
3932
+ template<class T> valarray<T> operator^ (const typename valarray<T>::value_type&,
3933
+ const valarray<T>&);
3934
 
3935
  template<class T> valarray<T> operator& (const valarray<T>&, const valarray<T>&);
3936
+ template<class T> valarray<T> operator& (const valarray<T>&,
3937
+ const typename valarray<T>::value_type&);
3938
+ template<class T> valarray<T> operator& (const typename valarray<T>::value_type&,
3939
+ const valarray<T>&);
3940
 
3941
  template<class T> valarray<T> operator| (const valarray<T>&, const valarray<T>&);
3942
+ template<class T> valarray<T> operator| (const valarray<T>&,
3943
+ const typename valarray<T>::value_type&);
3944
+ template<class T> valarray<T> operator| (const typename valarray<T>::value_type&,
3945
+ const valarray<T>&);
3946
 
3947
  template<class T> valarray<T> operator<<(const valarray<T>&, const valarray<T>&);
3948
+ template<class T> valarray<T> operator<<(const valarray<T>&,
3949
+ const typename valarray<T>::value_type&);
3950
+ template<class T> valarray<T> operator<<(const typename valarray<T>::value_type&,
3951
+ const valarray<T>&);
3952
 
3953
  template<class T> valarray<T> operator>>(const valarray<T>&, const valarray<T>&);
3954
+ template<class T> valarray<T> operator>>(const valarray<T>&,
3955
+ const typename valarray<T>::value_type&);
3956
+ template<class T> valarray<T> operator>>(const typename valarray<T>::value_type&,
3957
+ const valarray<T>&);
3958
 
3959
  template<class T> valarray<bool> operator&&(const valarray<T>&, const valarray<T>&);
3960
+ template<class T> valarray<bool> operator&&(const valarray<T>&,
3961
+ const typename valarray<T>::value_type&);
3962
+ template<class T> valarray<bool> operator&&(const typename valarray<T>::value_type&,
3963
+ const valarray<T>&);
3964
 
3965
  template<class T> valarray<bool> operator||(const valarray<T>&, const valarray<T>&);
3966
+ template<class T> valarray<bool> operator||(const valarray<T>&,
3967
+ const typename valarray<T>::value_type&);
3968
+ template<class T> valarray<bool> operator||(const typename valarray<T>::value_type&,
3969
+ const valarray<T>&);
3970
 
3971
+ template<class T> valarray<bool> operator==(const valarray<T>&, const valarray<T>&);
3972
+ template<class T> valarray<bool> operator==(const valarray<T>&,
3973
+ const typename valarray<T>::value_type&);
3974
+ template<class T> valarray<bool> operator==(const typename valarray<T>::value_type&,
3975
+ const valarray<T>&);
3976
+ template<class T> valarray<bool> operator!=(const valarray<T>&, const valarray<T>&);
3977
+ template<class T> valarray<bool> operator!=(const valarray<T>&,
3978
+ const typename valarray<T>::value_type&);
3979
+ template<class T> valarray<bool> operator!=(const typename valarray<T>::value_type&,
3980
+ const valarray<T>&);
3981
 
3982
+ template<class T> valarray<bool> operator< (const valarray<T>&, const valarray<T>&);
3983
+ template<class T> valarray<bool> operator< (const valarray<T>&,
3984
+ const typename valarray<T>::value_type&);
3985
+ template<class T> valarray<bool> operator< (const typename valarray<T>::value_type&,
3986
+ const valarray<T>&);
3987
+ template<class T> valarray<bool> operator> (const valarray<T>&, const valarray<T>&);
3988
+ template<class T> valarray<bool> operator> (const valarray<T>&,
3989
+ const typename valarray<T>::value_type&);
3990
+ template<class T> valarray<bool> operator> (const typename valarray<T>::value_type&,
3991
+ const valarray<T>&);
3992
+ template<class T> valarray<bool> operator<=(const valarray<T>&, const valarray<T>&);
3993
+ template<class T> valarray<bool> operator<=(const valarray<T>&,
3994
+ const typename valarray<T>::value_type&);
3995
+ template<class T> valarray<bool> operator<=(const typename valarray<T>::value_type&,
3996
+ const valarray<T>&);
3997
+ template<class T> valarray<bool> operator>=(const valarray<T>&, const valarray<T>&);
3998
+ template<class T> valarray<bool> operator>=(const valarray<T>&,
3999
+ const typename valarray<T>::value_type&);
4000
+ template<class T> valarray<bool> operator>=(const typename valarray<T>::value_type&,
4001
+ const valarray<T>&);
4002
 
4003
  template<class T> valarray<T> abs (const valarray<T>&);
4004
  template<class T> valarray<T> acos (const valarray<T>&);
4005
  template<class T> valarray<T> asin (const valarray<T>&);
4006
  template<class T> valarray<T> atan (const valarray<T>&);
4007
 
4008
  template<class T> valarray<T> atan2(const valarray<T>&, const valarray<T>&);
4009
+ template<class T> valarray<T> atan2(const valarray<T>&,
4010
+ const typename valarray<T>::value_type&);
4011
+ template<class T> valarray<T> atan2(const typename valarray<T>::value_type&,
4012
+ const valarray<T>&);
4013
 
4014
  template<class T> valarray<T> cos (const valarray<T>&);
4015
  template<class T> valarray<T> cosh (const valarray<T>&);
4016
  template<class T> valarray<T> exp (const valarray<T>&);
4017
  template<class T> valarray<T> log (const valarray<T>&);
4018
  template<class T> valarray<T> log10(const valarray<T>&);
4019
 
4020
  template<class T> valarray<T> pow(const valarray<T>&, const valarray<T>&);
4021
+ template<class T> valarray<T> pow(const valarray<T>&, const typename valarray<T>::value_type&);
4022
+ template<class T> valarray<T> pow(const typename valarray<T>::value_type&, const valarray<T>&);
4023
 
4024
  template<class T> valarray<T> sin (const valarray<T>&);
4025
  template<class T> valarray<T> sinh (const valarray<T>&);
4026
  template<class T> valarray<T> sqrt (const valarray<T>&);
4027
  template<class T> valarray<T> tan (const valarray<T>&);
 
4050
 
4051
  Implementations introducing such replacement types shall provide
4052
  additional functions and operators as follows:
4053
 
4054
  - for every function taking a `const valarray<T>&` other than `begin`
4055
+ and `end` [[valarray.range]], identical functions taking the
4056
  replacement types shall be added;
4057
  - for every function taking two `const valarray<T>&` arguments,
4058
  identical functions taking every combination of `const valarray<T>&`
4059
  and replacement types shall be added.
4060
 
4061
  In particular, an implementation shall allow a `valarray<T>` to be
4062
  constructed from such replacement types and shall allow assignments and
4063
  compound assignments of such types to `valarray<T>`, `slice_array<T>`,
4064
  `gslice_array<T>`, `mask_array<T>` and `indirect_array<T>` objects.
4065
 
4066
+ These library functions are permitted to throw a `bad_alloc`
4067
+ [[bad.alloc]] exception if there are not sufficient resources available
4068
  to carry out the operation. Note that the exception is not mandated.
4069
 
4070
  ### Class template `valarray` <a id="template.valarray">[[template.valarray]]</a>
4071
 
4072
+ #### Overview <a id="template.valarray.overview">[[template.valarray.overview]]</a>
4073
 
4074
  ``` cpp
4075
  namespace std {
4076
  template<class T> class valarray {
4077
  public:
 
4171
  remainder of  [[numarray]]. The illusion of higher dimensionality may be
4172
  produced by the familiar idiom of computed indices, together with the
4173
  powerful subsetting capabilities provided by the generalized subscript
4174
  operators.[^8]
4175
 
4176
+ #### Constructors <a id="valarray.cons">[[valarray.cons]]</a>
 
 
 
4177
 
4178
  ``` cpp
4179
  valarray();
4180
  ```
4181
 
 
4184
  ``` cpp
4185
  explicit valarray(size_t n);
4186
  ```
4187
 
4188
  *Effects:* Constructs a `valarray` that has length `n`. Each element of
4189
+ the array is value-initialized [[dcl.init]].
4190
 
4191
  ``` cpp
4192
  valarray(const T& v, size_t n);
4193
  ```
4194
 
 
4197
 
4198
  ``` cpp
4199
  valarray(const T* p, size_t n);
4200
  ```
4201
 
4202
+ *Preconditions:* \[`p`, `p + n`) is a valid range.
 
4203
 
4204
  *Effects:* Constructs a `valarray` that has length `n`. The values of
4205
  the elements of the array are initialized with the first `n` values
4206
  pointed to by the first argument.[^10]
4207
 
 
4244
  ```
4245
 
4246
  *Effects:* The destructor is applied to every element of `*this`; an
4247
  implementation may return all allocated memory.
4248
 
4249
+ #### Assignment <a id="valarray.assign">[[valarray.assign]]</a>
4250
 
4251
  ``` cpp
4252
  valarray& operator=(const valarray& v);
4253
  ```
4254
 
 
4256
  the corresponding element of `v`. If the length of `v` is not equal to
4257
  the length of `*this`, resizes `*this` to make the two arrays the same
4258
  length, as if by calling `resize(v.size())`, before performing the
4259
  assignment.
4260
 
4261
+ *Ensures:* `size() == v.size()`.
4262
 
4263
  *Returns:* `*this`.
4264
 
4265
  ``` cpp
4266
  valarray& operator=(valarray&& v) noexcept;
 
4292
  valarray& operator=(const gslice_array<T>&);
4293
  valarray& operator=(const mask_array<T>&);
4294
  valarray& operator=(const indirect_array<T>&);
4295
  ```
4296
 
4297
+ *Preconditions:* The length of the array to which the argument refers
4298
+ equals `size()`. The value of an element in the left-hand side of a
4299
+ `valarray` assignment operator does not depend on the value of another
4300
+ element in that left-hand side.
4301
 
4302
  These operators allow the results of a generalized subscripting
4303
  operation to be assigned directly to a `valarray`.
4304
 
4305
+ #### Element access <a id="valarray.access">[[valarray.access]]</a>
4306
 
4307
  ``` cpp
4308
  const T& operator[](size_t n) const;
4309
  T& operator[](size_t n);
4310
  ```
4311
 
4312
+ *Preconditions:* `n < size()` is `true`.
4313
 
4314
  *Returns:* A reference to the corresponding element of the array.
4315
 
4316
  [*Note 1*: The expression `(a[i] = q, a[i]) == q` evaluates to `true`
4317
  for any non-constant `valarray<T> a`, any `T q`, and for any `size_t i`
4318
  such that the value of `i` is less than the length of
4319
  `a`. — *end note*]
4320
 
4321
+ *Remarks:* The expression `addressof(a[i+j]) == addressof(a[i]) + j`
4322
+ evaluates to `true` for all `size_t i` and `size_t j` such that
4323
+ `i+j < a.size()`.
4324
 
4325
+ The expression `addressof(a[i]) != addressof(b[j])` evaluates to `true`
4326
+ for any two arrays `a` and `b` and for any `size_t i` and `size_t j`
4327
+ such that `i < a.size()` and `j < b.size()`.
4328
 
4329
  [*Note 2*: This property indicates an absence of aliasing and may be
4330
  used to advantage by optimizing compilers. Compilers may take advantage
4331
  of inlining, constant propagation, loop fusion, tracking of pointers
4332
  obtained from `operator new`, and other techniques to generate efficient
4333
  `valarray`s. — *end note*]
4334
 
4335
  The reference returned by the subscript operator for an array shall be
4336
+ valid until the member function `resize(size_t, T)` [[valarray.members]]
4337
+ is called for that array or until the lifetime of that array ends,
4338
+ whichever happens first.
4339
 
4340
+ #### Subset operations <a id="valarray.sub">[[valarray.sub]]</a>
4341
 
4342
  The member `operator[]` is overloaded to provide several ways to select
4343
  sequences of elements from among those controlled by `*this`. Each of
4344
  these operations returns a subset of the array. The const-qualified
4345
  versions return this subset as a new `valarray` object. The non-const
4346
  versions return a class template object which has reference semantics to
4347
  the original array, working in conjunction with various overloads of
4348
  `operator=` and other assigning operators to allow selective replacement
4349
  (slicing) of the controlled sequence. In each case the selected
4350
+ element(s) shall exist.
4351
 
4352
  ``` cpp
4353
  valarray operator[](slice slicearr) const;
4354
  ```
4355
 
 
4496
  // v0 == valarray<char>("abCDeBgAEjklmnop", 16)
4497
  ```
4498
 
4499
  — *end example*]
4500
 
4501
+ #### Unary operators <a id="valarray.unary">[[valarray.unary]]</a>
4502
 
4503
  ``` cpp
4504
  valarray operator+() const;
4505
  valarray operator-() const;
4506
  valarray operator~() const;
4507
  valarray<bool> operator!() const;
4508
  ```
4509
 
4510
+ *Mandates:* The indicated operator can be applied to operands of type
4511
+ `T` and returns a value of type `T` (`bool` for `operator!`) or which
4512
+ may be unambiguously implicitly converted to type `T` (`bool` for
4513
+ `operator!`).
 
4514
 
4515
  *Returns:* A `valarray` whose length is `size()`. Each element of the
4516
  returned array is initialized with the result of applying the indicated
4517
  operator to the corresponding element of the array.
4518
 
4519
+ #### Compound assignment <a id="valarray.cassign">[[valarray.cassign]]</a>
4520
 
4521
  ``` cpp
4522
  valarray& operator*= (const valarray& v);
4523
  valarray& operator/= (const valarray& v);
4524
  valarray& operator%= (const valarray& v);
 
4529
  valarray& operator|= (const valarray& v);
4530
  valarray& operator<<=(const valarray& v);
4531
  valarray& operator>>=(const valarray& v);
4532
  ```
4533
 
4534
+ *Mandates:* The indicated operator can be applied to two operands of
4535
+ type `T`.
4536
+
4537
+ *Preconditions:* `size() == v.size()` is `true`.
4538
+
4539
+ The value of an element in the left-hand side of a valarray compound
4540
+ assignment operator does not depend on the value of another element in
4541
+ that left hand side.
4542
 
4543
  *Effects:* Each of these operators performs the indicated operation on
4544
  each of the elements of `*this` and the corresponding element of `v`.
4545
 
4546
  *Returns:* `*this`.
 
4559
  valarray& operator|= (const T& v);
4560
  valarray& operator<<=(const T& v);
4561
  valarray& operator>>=(const T& v);
4562
  ```
4563
 
4564
+ *Mandates:* The indicated operator can be applied to two operands of
4565
+ type `T`.
 
4566
 
4567
  *Effects:* Each of these operators applies the indicated operation to
4568
  each element of `*this` and `v`.
4569
 
4570
  *Returns:* `*this`
4571
 
4572
  *Remarks:* The appearance of an array on the left-hand side of a
4573
  compound assignment does not invalidate references or pointers to the
4574
  elements of the array.
4575
 
4576
+ #### Member functions <a id="valarray.members">[[valarray.members]]</a>
4577
 
4578
  ``` cpp
4579
  void swap(valarray& v) noexcept;
4580
  ```
4581
 
 
4594
 
4595
  ``` cpp
4596
  T sum() const;
4597
  ```
4598
 
4599
+ *Mandates:* `operator+=` can be applied to operands of type `T`.
4600
+
4601
+ *Preconditions:* `size() > 0` is `true`.
4602
 
4603
  *Returns:* The sum of all the elements of the array. If the array has
4604
  length 1, returns the value of element 0. Otherwise, the returned value
4605
  is calculated by applying `operator+=` to a copy of an element of the
4606
  array and all other elements of the array in an unspecified order.
4607
 
4608
  ``` cpp
4609
  T min() const;
4610
  ```
4611
 
4612
+ *Preconditions:* `size() > 0` is `true`.
4613
 
4614
  *Returns:* The minimum value contained in `*this`. For an array of
4615
  length 1, the value of element 0 is returned. For all other array
4616
  lengths, the determination is made using `operator<`.
4617
 
4618
  ``` cpp
4619
  T max() const;
4620
  ```
4621
 
4622
+ *Preconditions:* `size() > 0` is `true`.
4623
 
4624
  *Returns:* The maximum value contained in `*this`. For an array of
4625
  length 1, the value of element 0 is returned. For all other array
4626
  lengths, the determination is made using `operator<`.
4627
 
 
4636
  [*Note 1*: If element zero is taken as the leftmost element, a positive
4637
  value of `n` shifts the elements left `n` places, with zero
4638
  fill. — *end note*]
4639
 
4640
  [*Example 1*: If the argument has the value -2, the first two elements
4641
+ of the result will be value-initialized [[dcl.init]]; the third element
4642
+ of the result will be assigned the value of the first element of the
4643
+ argument; etc. — *end example*]
4644
 
4645
  ``` cpp
4646
  valarray cshift(int n) const;
4647
  ```
4648
 
 
4668
  assigns to each element the value of the second argument. Resizing
4669
  invalidates all pointers and references to elements in the array.
4670
 
4671
  ### `valarray` non-member operations <a id="valarray.nonmembers">[[valarray.nonmembers]]</a>
4672
 
4673
+ #### Binary operators <a id="valarray.binary">[[valarray.binary]]</a>
4674
 
4675
  ``` cpp
4676
+ template<class T> valarray<T> operator* (const valarray<T>&, const valarray<T>&);
4677
+ template<class T> valarray<T> operator/ (const valarray<T>&, const valarray<T>&);
4678
+ template<class T> valarray<T> operator% (const valarray<T>&, const valarray<T>&);
4679
+ template<class T> valarray<T> operator+ (const valarray<T>&, const valarray<T>&);
4680
+ template<class T> valarray<T> operator- (const valarray<T>&, const valarray<T>&);
4681
+ template<class T> valarray<T> operator^ (const valarray<T>&, const valarray<T>&);
4682
+ template<class T> valarray<T> operator& (const valarray<T>&, const valarray<T>&);
4683
+ template<class T> valarray<T> operator| (const valarray<T>&, const valarray<T>&);
4684
+ template<class T> valarray<T> operator<<(const valarray<T>&, const valarray<T>&);
4685
+ template<class T> valarray<T> operator>>(const valarray<T>&, const valarray<T>&);
 
 
 
 
 
 
 
 
 
 
4686
  ```
4687
 
4688
+ *Mandates:* The indicated operator can be applied to operands of type
4689
+ `T` and returns a value of type `T` or which can be unambiguously
4690
+ implicitly converted to `T`.
4691
+
4692
+ *Preconditions:* The argument arrays have the same length.
4693
 
4694
  *Returns:* A `valarray` whose length is equal to the lengths of the
4695
  argument arrays. Each element of the returned array is initialized with
4696
  the result of applying the indicated operator to the corresponding
4697
  elements of the argument arrays.
4698
 
4699
  ``` cpp
4700
+ template<class T> valarray<T> operator* (const valarray<T>&,
4701
+ const typename valarray<T>::value_type&);
4702
+ template<class T> valarray<T> operator* (const typename valarray<T>::value_type&,
4703
+ const valarray<T>&);
4704
+ template<class T> valarray<T> operator/ (const valarray<T>&,
4705
+ const typename valarray<T>::value_type&);
4706
+ template<class T> valarray<T> operator/ (const typename valarray<T>::value_type&,
4707
+ const valarray<T>&);
4708
+ template<class T> valarray<T> operator% (const valarray<T>&,
4709
+ const typename valarray<T>::value_type&);
4710
+ template<class T> valarray<T> operator% (const typename valarray<T>::value_type&,
4711
+ const valarray<T>&);
4712
+ template<class T> valarray<T> operator+ (const valarray<T>&,
4713
+ const typename valarray<T>::value_type&);
4714
+ template<class T> valarray<T> operator+ (const typename valarray<T>::value_type&,
4715
+ const valarray<T>&);
4716
+ template<class T> valarray<T> operator- (const valarray<T>&,
4717
+ const typename valarray<T>::value_type&);
4718
+ template<class T> valarray<T> operator- (const typename valarray<T>::value_type&,
4719
+ const valarray<T>&);
4720
+ template<class T> valarray<T> operator^ (const valarray<T>&,
4721
+ const typename valarray<T>::value_type&);
4722
+ template<class T> valarray<T> operator^ (const typename valarray<T>::value_type&,
4723
+ const valarray<T>&);
4724
+ template<class T> valarray<T> operator& (const valarray<T>&,
4725
+ const typename valarray<T>::value_type&);
4726
+ template<class T> valarray<T> operator& (const typename valarray<T>::value_type&,
4727
+ const valarray<T>&);
4728
+ template<class T> valarray<T> operator| (const valarray<T>&,
4729
+ const typename valarray<T>::value_type&);
4730
+ template<class T> valarray<T> operator| (const typename valarray<T>::value_type&,
4731
+ const valarray<T>&);
4732
+ template<class T> valarray<T> operator<<(const valarray<T>&,
4733
+ const typename valarray<T>::value_type&);
4734
+ template<class T> valarray<T> operator<<(const typename valarray<T>::value_type&,
4735
+ const valarray<T>&);
4736
+ template<class T> valarray<T> operator>>(const valarray<T>&,
4737
+ const typename valarray<T>::value_type&);
4738
+ template<class T> valarray<T> operator>>(const typename valarray<T>::value_type&,
4739
+ const valarray<T>&);
4740
  ```
4741
 
4742
+ *Mandates:* The indicated operator can be applied to operands of type
4743
+ `T` and returns a value of type `T` or which can be unambiguously
4744
+ implicitly converted to `T`.
 
4745
 
4746
  *Returns:* A `valarray` whose length is equal to the length of the array
4747
  argument. Each element of the returned array is initialized with the
4748
  result of applying the indicated operator to the corresponding element
4749
  of the array argument and the non-array argument.
4750
 
4751
+ #### Logical operators <a id="valarray.comparison">[[valarray.comparison]]</a>
4752
 
4753
  ``` cpp
4754
+ template<class T> valarray<bool> operator==(const valarray<T>&, const valarray<T>&);
4755
+ template<class T> valarray<bool> operator!=(const valarray<T>&, const valarray<T>&);
4756
+ template<class T> valarray<bool> operator< (const valarray<T>&, const valarray<T>&);
4757
+ template<class T> valarray<bool> operator> (const valarray<T>&, const valarray<T>&);
4758
+ template<class T> valarray<bool> operator<=(const valarray<T>&, const valarray<T>&);
4759
+ template<class T> valarray<bool> operator>=(const valarray<T>&, const valarray<T>&);
4760
+ template<class T> valarray<bool> operator&&(const valarray<T>&, const valarray<T>&);
4761
+ template<class T> valarray<bool> operator||(const valarray<T>&, const valarray<T>&);
 
 
 
 
 
 
 
 
4762
  ```
4763
 
4764
+ *Mandates:* The indicated operator can be applied to operands of type
4765
+ `T` and returns a value of type `bool` or which can be unambiguously
4766
+ implicitly converted to `bool`.
4767
+
4768
+ *Preconditions:* The two array arguments have the same length.
4769
 
4770
  *Returns:* A `valarray<bool>` whose length is equal to the length of the
4771
  array arguments. Each element of the returned array is initialized with
4772
  the result of applying the indicated operator to the corresponding
4773
  elements of the argument arrays.
4774
 
4775
  ``` cpp
4776
+ template<class T> valarray<bool> operator==(const valarray<T>&,
4777
+ const typename valarray<T>::value_type&);
4778
+ template<class T> valarray<bool> operator==(const typename valarray<T>::value_type&,
4779
+ const valarray<T>&);
4780
+ template<class T> valarray<bool> operator!=(const valarray<T>&,
4781
+ const typename valarray<T>::value_type&);
4782
+ template<class T> valarray<bool> operator!=(const typename valarray<T>::value_type&,
4783
+ const valarray<T>&);
4784
+ template<class T> valarray<bool> operator< (const valarray<T>&,
4785
+ const typename valarray<T>::value_type&);
4786
+ template<class T> valarray<bool> operator< (const typename valarray<T>::value_type&,
4787
+ const valarray<T>&);
4788
+ template<class T> valarray<bool> operator> (const valarray<T>&,
4789
+ const typename valarray<T>::value_type&);
4790
+ template<class T> valarray<bool> operator> (const typename valarray<T>::value_type&,
4791
+ const valarray<T>&);
4792
+ template<class T> valarray<bool> operator<=(const valarray<T>&,
4793
+ const typename valarray<T>::value_type&);
4794
+ template<class T> valarray<bool> operator<=(const typename valarray<T>::value_type&,
4795
+ const valarray<T>&);
4796
+ template<class T> valarray<bool> operator>=(const valarray<T>&,
4797
+ const typename valarray<T>::value_type&);
4798
+ template<class T> valarray<bool> operator>=(const typename valarray<T>::value_type&,
4799
+ const valarray<T>&);
4800
+ template<class T> valarray<bool> operator&&(const valarray<T>&,
4801
+ const typename valarray<T>::value_type&);
4802
+ template<class T> valarray<bool> operator&&(const typename valarray<T>::value_type&,
4803
+ const valarray<T>&);
4804
+ template<class T> valarray<bool> operator||(const valarray<T>&,
4805
+ const typename valarray<T>::value_type&);
4806
+ template<class T> valarray<bool> operator||(const typename valarray<T>::value_type&,
4807
+ const valarray<T>&);
4808
  ```
4809
 
4810
+ *Mandates:* The indicated operator can be applied to operands of type
4811
+ `T` and returns a value of type `bool` or which can be unambiguously
4812
+ implicitly converted to `bool`.
 
4813
 
4814
  *Returns:* A `valarray<bool>` whose length is equal to the length of the
4815
  array argument. Each element of the returned array is initialized with
4816
  the result of applying the indicated operator to the corresponding
4817
  element of the array and the non-array argument.
4818
 
4819
+ #### Transcendentals <a id="valarray.transcend">[[valarray.transcend]]</a>
4820
 
4821
  ``` cpp
4822
  template<class T> valarray<T> abs (const valarray<T>&);
4823
  template<class T> valarray<T> acos (const valarray<T>&);
4824
  template<class T> valarray<T> asin (const valarray<T>&);
4825
  template<class T> valarray<T> atan (const valarray<T>&);
4826
+ template<class T> valarray<T> atan2(const valarray<T>&, const valarray<T>&);
4827
+ template<class T> valarray<T> atan2(const valarray<T>&, const typename valarray<T>::value_type&);
4828
+ template<class T> valarray<T> atan2(const typename valarray<T>::value_type&, const valarray<T>&);
 
4829
  template<class T> valarray<T> cos (const valarray<T>&);
4830
  template<class T> valarray<T> cosh (const valarray<T>&);
4831
  template<class T> valarray<T> exp (const valarray<T>&);
4832
  template<class T> valarray<T> log (const valarray<T>&);
4833
  template<class T> valarray<T> log10(const valarray<T>&);
4834
+ template<class T> valarray<T> pow (const valarray<T>&, const valarray<T>&);
4835
+ template<class T> valarray<T> pow (const valarray<T>&, const typename valarray<T>::value_type&);
4836
+ template<class T> valarray<T> pow (const typename valarray<T>::value_type&, const valarray<T>&);
 
4837
  template<class T> valarray<T> sin (const valarray<T>&);
4838
  template<class T> valarray<T> sinh (const valarray<T>&);
4839
  template<class T> valarray<T> sqrt (const valarray<T>&);
4840
  template<class T> valarray<T> tan (const valarray<T>&);
4841
  template<class T> valarray<T> tanh (const valarray<T>&);
4842
  ```
4843
 
4844
+ *Mandates:* A unique function with the indicated name can be applied
4845
+ (unqualified) to an operand of type `T`. This function returns a value
4846
+ of type `T` or which can be unambiguously implicitly converted to type
4847
+ `T`.
4848
 
4849
+ #### Specialized algorithms <a id="valarray.special">[[valarray.special]]</a>
4850
 
4851
  ``` cpp
4852
  template<class T> void swap(valarray<T>& x, valarray<T>& y) noexcept;
4853
  ```
4854
 
4855
  *Effects:* Equivalent to `x.swap(y)`.
4856
 
4857
  ### Class `slice` <a id="class.slice">[[class.slice]]</a>
4858
 
4859
+ #### Overview <a id="class.slice.overview">[[class.slice.overview]]</a>
4860
 
4861
  ``` cpp
4862
  namespace std {
4863
  class slice {
4864
  public:
 
4866
  slice(size_t, size_t, size_t);
4867
 
4868
  size_t start() const;
4869
  size_t size() const;
4870
  size_t stride() const;
4871
+
4872
+ friend bool operator==(const slice& x, const slice& y);
4873
  };
4874
  }
4875
  ```
4876
 
4877
  The `slice` class represents a BLAS-like slice from an array. Such a
4878
  slice is specified by a starting index, a length, and a stride.[^12]
4879
 
4880
+ #### Constructors <a id="cons.slice">[[cons.slice]]</a>
4881
 
4882
  ``` cpp
4883
  slice();
4884
  slice(size_t start, size_t length, size_t stride);
4885
  slice(const slice&);
 
4889
  constructor is provided only to permit the declaration of arrays of
4890
  slices. The constructor with arguments for a slice takes a start,
4891
  length, and stride parameter.
4892
 
4893
  [*Example 1*: `slice(3, 8, 2)` constructs a slice which selects
4894
+ elements 3, 5, 7, …, 17 from an array. — *end example*]
4895
 
4896
+ #### Access functions <a id="slice.access">[[slice.access]]</a>
4897
 
4898
  ``` cpp
4899
  size_t start() const;
4900
  size_t size() const;
4901
  size_t stride() const;
 
4903
 
4904
  *Returns:* The start, length, or stride specified by a `slice` object.
4905
 
4906
  *Complexity:* Constant time.
4907
 
4908
+ #### Operators <a id="slice.ops">[[slice.ops]]</a>
4909
+
4910
+ ``` cpp
4911
+ friend bool operator==(const slice& x, const slice& y);
4912
+ ```
4913
+
4914
+ *Effects:* Equivalent to:
4915
+
4916
+ ``` cpp
4917
+ return x.start() == y.start() && x.size() == y.size() && x.stride() == y.stride();
4918
+ ```
4919
+
4920
  ### Class template `slice_array` <a id="template.slice.array">[[template.slice.array]]</a>
4921
 
4922
+ #### Overview <a id="template.slice.array.overview">[[template.slice.array.overview]]</a>
4923
 
4924
  ``` cpp
4925
  namespace std {
4926
  template<class T> class slice_array {
4927
  public:
 
4947
  slice_array() = delete; // as implied by declaring copy constructor above
4948
  };
4949
  }
4950
  ```
4951
 
4952
+ This template is a helper template used by the `slice` subscript
4953
+ operator
4954
 
4955
  ``` cpp
4956
  slice_array<T> valarray<T>::operator[](slice);
4957
  ```
4958
 
4959
  It has reference semantics to a subset of an array specified by a
4960
  `slice` object.
4961
 
4962
  [*Example 1*: The expression `a[slice(1, 5, 3)] = b;` has the effect of
4963
  assigning the elements of `b` to a slice of the elements in `a`. For the
4964
+ slice shown, the elements selected from `a` are
4965
+ 1, 4, …, 13. — *end example*]
4966
 
4967
+ #### Assignment <a id="slice.arr.assign">[[slice.arr.assign]]</a>
4968
 
4969
  ``` cpp
4970
  void operator=(const valarray<T>&) const;
4971
  const slice_array& operator=(const slice_array&) const;
4972
  ```
4973
 
4974
  These assignment operators have reference semantics, assigning the
4975
  values of the argument array elements to selected elements of the
4976
  `valarray<T>` object to which the `slice_array` object refers.
4977
 
4978
+ #### Compound assignment <a id="slice.arr.comp.assign">[[slice.arr.comp.assign]]</a>
4979
 
4980
  ``` cpp
4981
  void operator*= (const valarray<T>&) const;
4982
  void operator/= (const valarray<T>&) const;
4983
  void operator%= (const valarray<T>&) const;
 
4993
  These compound assignments have reference semantics, applying the
4994
  indicated operation to the elements of the argument array and selected
4995
  elements of the `valarray<T>` object to which the `slice_array` object
4996
  refers.
4997
 
4998
+ #### Fill function <a id="slice.arr.fill">[[slice.arr.fill]]</a>
4999
 
5000
  ``` cpp
5001
  void operator=(const T&) const;
5002
  ```
5003
 
 
5005
  argument to the elements of the `valarray<T>` object to which the
5006
  `slice_array` object refers.
5007
 
5008
  ### The `gslice` class <a id="class.gslice">[[class.gslice]]</a>
5009
 
5010
+ #### Overview <a id="class.gslice.overview">[[class.gslice.overview]]</a>
5011
 
5012
  ``` cpp
5013
  namespace std {
5014
  class gslice {
5015
  public:
 
5063
  — *end example*]
5064
 
5065
  If a degenerate slice is used as the argument to the non-`const` version
5066
  of `operator[](const gslice&)`, the behavior is undefined.
5067
 
5068
+ #### Constructors <a id="gslice.cons">[[gslice.cons]]</a>
5069
 
5070
  ``` cpp
5071
  gslice();
5072
  gslice(size_t start, const valarray<size_t>& lengths,
5073
  const valarray<size_t>& strides);
 
5075
  ```
5076
 
5077
  The default constructor is equivalent to
5078
  `gslice(0, valarray<size_t>(), valarray<size_t>())`. The constructor
5079
  with arguments builds a `gslice` based on a specification of start,
5080
+ lengths, and strides, as explained in the previous subclause.
5081
 
5082
+ #### Access functions <a id="gslice.access">[[gslice.access]]</a>
5083
 
5084
  ``` cpp
5085
  size_t start() const;
5086
  valarray<size_t> size() const;
5087
  valarray<size_t> stride() const;
 
5093
  *Complexity:* `start()` is constant time. `size()` and `stride()` are
5094
  linear in the number of strides.
5095
 
5096
  ### Class template `gslice_array` <a id="template.gslice.array">[[template.gslice.array]]</a>
5097
 
5098
+ #### Overview <a id="template.gslice.array.overview">[[template.gslice.array.overview]]</a>
5099
 
5100
  ``` cpp
5101
  namespace std {
5102
  template<class T> class gslice_array {
5103
  public:
 
5123
  gslice_array() = delete; // as implied by declaring copy constructor above
5124
  };
5125
  }
5126
  ```
5127
 
5128
+ This template is a helper template used by the `gslice` subscript
5129
  operator
5130
 
5131
  ``` cpp
5132
  gslice_array<T> valarray<T>::operator[](const gslice&);
5133
  ```
5134
 
5135
  It has reference semantics to a subset of an array specified by a
5136
+ `gslice` object. Thus, the expression `a[gslice(1, length, stride)] = b`
5137
+ has the effect of assigning the elements of `b` to a generalized slice
5138
+ of the elements in `a`.
5139
 
5140
+ #### Assignment <a id="gslice.array.assign">[[gslice.array.assign]]</a>
 
 
 
 
5141
 
5142
  ``` cpp
5143
  void operator=(const valarray<T>&) const;
5144
  const gslice_array& operator=(const gslice_array&) const;
5145
  ```
5146
 
5147
  These assignment operators have reference semantics, assigning the
5148
  values of the argument array elements to selected elements of the
5149
  `valarray<T>` object to which the `gslice_array` refers.
5150
 
5151
+ #### Compound assignment <a id="gslice.array.comp.assign">[[gslice.array.comp.assign]]</a>
5152
 
5153
  ``` cpp
5154
  void operator*= (const valarray<T>&) const;
5155
  void operator/= (const valarray<T>&) const;
5156
  void operator%= (const valarray<T>&) const;
 
5166
  These compound assignments have reference semantics, applying the
5167
  indicated operation to the elements of the argument array and selected
5168
  elements of the `valarray<T>` object to which the `gslice_array` object
5169
  refers.
5170
 
5171
+ #### Fill function <a id="gslice.array.fill">[[gslice.array.fill]]</a>
5172
 
5173
  ``` cpp
5174
  void operator=(const T&) const;
5175
  ```
5176
 
 
5178
  argument to the elements of the `valarray<T>` object to which the
5179
  `gslice_array` object refers.
5180
 
5181
  ### Class template `mask_array` <a id="template.mask.array">[[template.mask.array]]</a>
5182
 
5183
+ #### Overview <a id="template.mask.array.overview">[[template.mask.array.overview]]</a>
5184
 
5185
  ``` cpp
5186
  namespace std {
5187
  template<class T> class mask_array {
5188
  public:
 
5217
  ```
5218
 
5219
  It has reference semantics to a subset of an array specified by a
5220
  boolean mask. Thus, the expression `a[mask] = b;` has the effect of
5221
  assigning the elements of `b` to the masked elements in `a` (those for
5222
+ which the corresponding element in `mask` is `true`).
5223
 
5224
+ #### Assignment <a id="mask.array.assign">[[mask.array.assign]]</a>
5225
 
5226
  ``` cpp
5227
  void operator=(const valarray<T>&) const;
5228
  const mask_array& operator=(const mask_array&) const;
5229
  ```
5230
 
5231
  These assignment operators have reference semantics, assigning the
5232
  values of the argument array elements to selected elements of the
5233
  `valarray<T>` object to which it refers.
5234
 
5235
+ #### Compound assignment <a id="mask.array.comp.assign">[[mask.array.comp.assign]]</a>
5236
 
5237
  ``` cpp
5238
  void operator*= (const valarray<T>&) const;
5239
  void operator/= (const valarray<T>&) const;
5240
  void operator%= (const valarray<T>&) const;
 
5249
 
5250
  These compound assignments have reference semantics, applying the
5251
  indicated operation to the elements of the argument array and selected
5252
  elements of the `valarray<T>` object to which the mask object refers.
5253
 
5254
+ #### Fill function <a id="mask.array.fill">[[mask.array.fill]]</a>
5255
 
5256
  ``` cpp
5257
  void operator=(const T&) const;
5258
  ```
5259
 
 
5261
  argument to the elements of the `valarray<T>` object to which the
5262
  `mask_array` object refers.
5263
 
5264
  ### Class template `indirect_array` <a id="template.indirect.array">[[template.indirect.array]]</a>
5265
 
5266
+ #### Overview <a id="template.indirect.array.overview">[[template.indirect.array.overview]]</a>
5267
 
5268
  ``` cpp
5269
  namespace std {
5270
  template<class T> class indirect_array {
5271
  public:
 
5299
  ``` cpp
5300
  indirect_array<T> valarray<T>::operator[](const valarray<size_t>&).
5301
  ```
5302
 
5303
  It has reference semantics to a subset of an array specified by an
5304
+ `indirect_array`. Thus, the expression `a[{}indirect] = b;` has the
5305
+ effect of assigning the elements of `b` to the elements in `a` whose
5306
+ indices appear in `indirect`.
5307
 
5308
+ #### Assignment <a id="indirect.array.assign">[[indirect.array.assign]]</a>
5309
 
5310
  ``` cpp
5311
  void operator=(const valarray<T>&) const;
5312
  const indirect_array& operator=(const indirect_array&) const;
5313
  ```
 
5331
  results in undefined behavior since element 4 is specified twice in the
5332
  indirection.
5333
 
5334
  — *end example*]
5335
 
5336
+ #### Compound assignment <a id="indirect.array.comp.assign">[[indirect.array.comp.assign]]</a>
5337
 
5338
  ``` cpp
5339
  void operator*= (const valarray<T>&) const;
5340
  void operator/= (const valarray<T>&) const;
5341
  void operator%= (const valarray<T>&) const;
 
5354
  object refers.
5355
 
5356
  If the `indirect_array` specifies an element in the `valarray<T>` object
5357
  to which it refers more than once, the behavior is undefined.
5358
 
5359
+ #### Fill function <a id="indirect.array.fill">[[indirect.array.fill]]</a>
5360
 
5361
  ``` cpp
5362
  void operator=(const T&) const;
5363
  ```
5364
 
 
5367
  `indirect_array` object refers.
5368
 
5369
  ### `valarray` range access <a id="valarray.range">[[valarray.range]]</a>
5370
 
5371
  In the `begin` and `end` function templates that follow, *unspecified*1
5372
+ is a type that meets the requirements of a mutable
5373
+ *Cpp17RandomAccessIterator* [[random.access.iterators]] and models
5374
+ `contiguous_iterator` [[iterator.concept.contiguous]], whose
5375
+ `value_type` is the template parameter `T` and whose `reference` type is
5376
+ `T&`. *unspecified*2 is a type that meets the requirements of a constant
5377
+ *Cpp17RandomAccessIterator* and models `contiguous_iterator`, whose
5378
+ `value_type` is the template parameter `T` and whose `reference` type is
5379
+ `const T&`.
5380
 
5381
  The iterators returned by `begin` and `end` for an array are guaranteed
5382
+ to be valid until the member function `resize(size_t, T)`
5383
+ [[valarray.members]] is called for that array or until the lifetime of
5384
  that array ends, whichever happens first.
5385
 
5386
  ``` cpp
5387
  template<class T> unspecified{1} begin(valarray<T>& v);
5388
  template<class T> unspecified{2} begin(const valarray<T>& v);
 
5395
  template<class T> unspecified{2} end(const valarray<T>& v);
5396
  ```
5397
 
5398
  *Returns:* An iterator referencing one past the last value in the array.
5399
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
5400
  ## Mathematical functions for floating-point types <a id="c.math">[[c.math]]</a>
5401
 
5402
  ### Header `<cmath>` synopsis <a id="cmath.syn">[[cmath.syn]]</a>
5403
 
5404
  ``` cpp
 
5610
  float fabsf(float x);
5611
  long double fabsl(long double x);
5612
 
5613
  float hypot(float x, float y); // see [library.c]
5614
  double hypot(double x, double y);
5615
+ long double hypot(long double x, long double y); // see [library.c]
5616
  float hypotf(float x, float y);
5617
  long double hypotl(long double x, long double y);
5618
 
5619
  // [c.math.hypot3], three-dimensional hypotenuse
5620
  float hypot(float x, float y, float z);
 
5779
  double fma(double x, double y, double z);
5780
  long double fma(long double x, long double y, long double z); // see [library.c]
5781
  float fmaf(float x, float y, float z);
5782
  long double fmal(long double x, long double y, long double z);
5783
 
5784
+ // [c.math.lerp], linear interpolation
5785
+ constexpr float lerp(float a, float b, float t) noexcept;
5786
+ constexpr double lerp(double a, double b, double t) noexcept;
5787
+ constexpr long double lerp(long double a, long double b, long double t) noexcept;
5788
+
5789
  // [c.math.fpclass], classification / comparison functions
5790
  int fpclassify(float x);
5791
  int fpclassify(double x);
5792
  int fpclassify(long double x);
5793
 
5794
+ bool isfinite(float x);
5795
+ bool isfinite(double x);
5796
+ bool isfinite(long double x);
5797
 
5798
+ bool isinf(float x);
5799
+ bool isinf(double x);
5800
+ bool isinf(long double x);
5801
 
5802
+ bool isnan(float x);
5803
+ bool isnan(double x);
5804
+ bool isnan(long double x);
5805
 
5806
+ bool isnormal(float x);
5807
+ bool isnormal(double x);
5808
+ bool isnormal(long double x);
5809
 
5810
+ bool signbit(float x);
5811
+ bool signbit(double x);
5812
+ bool signbit(long double x);
5813
 
5814
+ bool isgreater(float x, float y);
5815
+ bool isgreater(double x, double y);
5816
+ bool isgreater(long double x, long double y);
5817
 
5818
+ bool isgreaterequal(float x, float y);
5819
+ bool isgreaterequal(double x, double y);
5820
+ bool isgreaterequal(long double x, long double y);
5821
 
5822
+ bool isless(float x, float y);
5823
+ bool isless(double x, double y);
5824
+ bool isless(long double x, long double y);
5825
 
5826
+ bool islessequal(float x, float y);
5827
+ bool islessequal(double x, double y);
5828
+ bool islessequal(long double x, long double y);
5829
 
5830
+ bool islessgreater(float x, float y);
5831
+ bool islessgreater(double x, double y);
5832
+ bool islessgreater(long double x, long double y);
5833
 
5834
+ bool isunordered(float x, float y);
5835
+ bool isunordered(double x, double y);
5836
+ bool isunordered(long double x, long double y);
5837
 
5838
  // [sf.cmath], mathematical special functions
5839
 
5840
+ // [sf.cmath.assoc.laguerre], associated Laguerre polynomials
5841
  double assoc_laguerre(unsigned n, unsigned m, double x);
5842
  float assoc_laguerref(unsigned n, unsigned m, float x);
5843
  long double assoc_laguerrel(unsigned n, unsigned m, long double x);
5844
 
5845
+ // [sf.cmath.assoc.legendre], associated Legendre functions
5846
  double assoc_legendre(unsigned l, unsigned m, double x);
5847
  float assoc_legendref(unsigned l, unsigned m, float x);
5848
  long double assoc_legendrel(unsigned l, unsigned m, long double x);
5849
 
5850
  // [sf.cmath.beta], beta function
5851
  double beta(double x, double y);
5852
  float betaf(float x, float y);
5853
  long double betal(long double x, long double y);
5854
 
5855
+ // [sf.cmath.comp.ellint.1], complete elliptic integral of the first kind
5856
  double comp_ellint_1(double k);
5857
  float comp_ellint_1f(float k);
5858
  long double comp_ellint_1l(long double k);
5859
 
5860
+ // [sf.cmath.comp.ellint.2], complete elliptic integral of the second kind
5861
  double comp_ellint_2(double k);
5862
  float comp_ellint_2f(float k);
5863
  long double comp_ellint_2l(long double k);
5864
 
5865
+ // [sf.cmath.comp.ellint.3], complete elliptic integral of the third kind
5866
  double comp_ellint_3(double k, double nu);
5867
  float comp_ellint_3f(float k, float nu);
5868
  long double comp_ellint_3l(long double k, long double nu);
5869
 
5870
+ // [sf.cmath.cyl.bessel.i], regular modified cylindrical Bessel functions
5871
  double cyl_bessel_i(double nu, double x);
5872
  float cyl_bessel_if(float nu, float x);
5873
  long double cyl_bessel_il(long double nu, long double x);
5874
 
5875
+ // [sf.cmath.cyl.bessel.j], cylindrical Bessel functions of the first kind
5876
  double cyl_bessel_j(double nu, double x);
5877
  float cyl_bessel_jf(float nu, float x);
5878
  long double cyl_bessel_jl(long double nu, long double x);
5879
 
5880
+ // [sf.cmath.cyl.bessel.k], irregular modified cylindrical Bessel functions
5881
  double cyl_bessel_k(double nu, double x);
5882
  float cyl_bessel_kf(float nu, float x);
5883
  long double cyl_bessel_kl(long double nu, long double x);
5884
 
5885
+ // [sf.cmath.cyl.neumann], cylindrical Neumann functions;
5886
  // cylindrical Bessel functions of the second kind
5887
  double cyl_neumann(double nu, double x);
5888
  float cyl_neumannf(float nu, float x);
5889
  long double cyl_neumannl(long double nu, long double x);
5890
 
5891
+ // [sf.cmath.ellint.1], incomplete elliptic integral of the first kind
5892
  double ellint_1(double k, double phi);
5893
  float ellint_1f(float k, float phi);
5894
  long double ellint_1l(long double k, long double phi);
5895
 
5896
+ // [sf.cmath.ellint.2], incomplete elliptic integral of the second kind
5897
  double ellint_2(double k, double phi);
5898
  float ellint_2f(float k, float phi);
5899
  long double ellint_2l(long double k, long double phi);
5900
 
5901
+ // [sf.cmath.ellint.3], incomplete elliptic integral of the third kind
5902
  double ellint_3(double k, double nu, double phi);
5903
  float ellint_3f(float k, float nu, float phi);
5904
  long double ellint_3l(long double k, long double nu, long double phi);
5905
 
5906
  // [sf.cmath.expint], exponential integral
 
5921
  // [sf.cmath.legendre], Legendre polynomials
5922
  double legendre(unsigned l, double x);
5923
  float legendref(unsigned l, float x);
5924
  long double legendrel(unsigned l, long double x);
5925
 
5926
+ // [sf.cmath.riemann.zeta], Riemann zeta function
5927
  double riemann_zeta(double x);
5928
  float riemann_zetaf(float x);
5929
  long double riemann_zetal(long double x);
5930
 
5931
+ // [sf.cmath.sph.bessel], spherical Bessel functions of the first kind
5932
  double sph_bessel(unsigned n, double x);
5933
  float sph_besself(unsigned n, float x);
5934
  long double sph_bessell(unsigned n, long double x);
5935
 
5936
+ // [sf.cmath.sph.legendre], spherical associated Legendre functions
5937
  double sph_legendre(unsigned l, unsigned m, double theta);
5938
  float sph_legendref(unsigned l, unsigned m, float theta);
5939
  long double sph_legendrel(unsigned l, unsigned m, long double theta);
5940
 
5941
+ // [sf.cmath.sph.neumann], spherical Neumann functions;
5942
+ // spherical Bessel functions of the second kind
5943
  double sph_neumann(unsigned n, double x);
5944
  float sph_neumannf(unsigned n, float x);
5945
  long double sph_neumannl(unsigned n, long double x);
5946
  }
5947
  ```
 
5950
  standard library header `<math.h>`, with the addition of a
5951
  three-dimensional hypotenuse function ([[c.math.hypot3]]) and the
5952
  mathematical special functions described in [[sf.cmath]].
5953
 
5954
  [*Note 1*: Several functions have additional overloads in this
5955
+ document, but they have the same behavior as in the C standard library
5956
+ [[library.c]]. — *end note*]
5957
 
5958
  For each set of overloaded functions within `<cmath>`, with the
5959
  exception of `abs`, there shall be additional overloads sufficient to
5960
  ensure:
5961
 
5962
+ - If any argument of arithmetic type corresponding to a `double`
5963
  parameter has type `long double`, then all arguments of arithmetic
5964
+ type [[basic.fundamental]] corresponding to `double` parameters are
5965
+ effectively cast to `long double`.
5966
+ - Otherwise, if any argument of arithmetic type corresponding to a
5967
  `double` parameter has type `double` or an integer type, then all
5968
+ arguments of arithmetic type corresponding to `double` parameters are
5969
+ effectively cast to `double`.
5970
+ - \[*Note 2*: Otherwise, all arguments of arithmetic type corresponding
5971
+ to `double` parameters have type `float`. — *end note*]
5972
 
5973
+ [*Note 3*: `abs` is exempted from these rules in order to stay
5974
  compatible with C. — *end note*]
5975
 
5976
  ISO C 7.12
5977
 
5978
  ### Absolute values <a id="c.math.abs">[[c.math.abs]]</a>
5979
 
5980
+ [*Note 1*: The headers `<cstdlib>` and `<cmath>` declare the functions
5981
+ described in this subclause. *end note*]
 
5982
 
5983
  ``` cpp
5984
  int abs(int j);
5985
  long int abs(long int j);
5986
  long long int abs(long long int j);
 
5993
  standard library for the functions `abs`, `labs`, `llabs`, `fabsf`,
5994
  `fabs`, and `fabsl`.
5995
 
5996
  *Remarks:* If `abs()` is called with an argument of type `X` for which
5997
  `is_unsigned_v<X>` is `true` and if `X` cannot be converted to `int` by
5998
+ integral promotion [[conv.prom]], the program is ill-formed.
5999
 
6000
  [*Note 1*: Arguments that can be promoted to `int` are permitted for
6001
  compatibility with C. — *end note*]
6002
 
6003
+ See also: ISO C 7.12.7.2, 7.22.6.1
6004
 
6005
  ### Three-dimensional hypotenuse <a id="c.math.hypot3">[[c.math.hypot3]]</a>
6006
 
6007
  ``` cpp
6008
  float hypot(float x, float y, float z);
 
6010
  long double hypot(long double x, long double y, long double z);
6011
  ```
6012
 
6013
  *Returns:* $\sqrt{x^2+y^2+z^2}$.
6014
 
6015
+ ### Linear interpolation <a id="c.math.lerp">[[c.math.lerp]]</a>
6016
+
6017
+ ``` cpp
6018
+ constexpr float lerp(float a, float b, float t) noexcept;
6019
+ constexpr double lerp(double a, double b, double t) noexcept;
6020
+ constexpr long double lerp(long double a, long double b, long double t) noexcept;
6021
+ ```
6022
+
6023
+ *Returns:* a+t(b-a).
6024
+
6025
+ *Remarks:* Let `r` be the value returned. If
6026
+ `isfinite(a) && isfinite(b)`, then:
6027
+
6028
+ - If `t == 0`, then `r == a`.
6029
+ - If `t == 1`, then `r == b`.
6030
+ - If `t >= 0 && t <= 1`, then `isfinite(r)`.
6031
+ - If `isfinite(t) && a == b`, then `r == a`.
6032
+ - If `isfinite(t) || !isnan(t) && b-a != 0`, then `!isnan(r)`.
6033
+
6034
+ Let *`CMP`*`(x,y)` be `1` if `x > y`, `-1` if `x < y`, and `0`
6035
+ otherwise. For any `t1` and `t2`, the product of
6036
+ *`CMP`*`(lerp(a, b, t2), lerp(a, b, t1))`, *`CMP`*`(t2, t1)`, and
6037
+ *`CMP`*`(b, a)` is non-negative.
6038
+
6039
  ### Classification / comparison functions <a id="c.math.fpclass">[[c.math.fpclass]]</a>
6040
 
6041
  The classification / comparison functions behave the same as the C
6042
  macros with the corresponding names defined in the C standard library.
6043
  Each function is overloaded for the three floating-point types.
 
6054
  - the function description’s *Returns:* clause explicitly specifies a
6055
  domain and those argument values fall outside the specified domain, or
6056
  - the corresponding mathematical function value has a nonzero imaginary
6057
  component, or
6058
  - the corresponding mathematical function is not mathematically
6059
+ defined.[^13]
6060
 
6061
  Unless otherwise specified, each function is defined for all finite
6062
  values, for negative infinity, and for positive infinity.
6063
 
6064
+ #### Associated Laguerre polynomials <a id="sf.cmath.assoc.laguerre">[[sf.cmath.assoc.laguerre]]</a>
6065
 
6066
  ``` cpp
6067
  double assoc_laguerre(unsigned n, unsigned m, double x);
6068
  float assoc_laguerref(unsigned n, unsigned m, float x);
6069
  long double assoc_laguerrel(unsigned n, unsigned m, long double x);
6070
  ```
6071
 
6072
  *Effects:* These functions compute the associated Laguerre polynomials
6073
  of their respective arguments `n`, `m`, and `x`.
6074
 
6075
+ *Returns:* $$\mathsf{L}_n^m(x) =
6076
+ (-1)^m \frac{\mathsf{d} ^ m}{\mathsf{d}x ^ m} \, \mathsf{L}_{n+m}(x)
6077
+ \text{ ,\quad for $x \ge 0$,}$$ where n is `n`, m is `m`, and x is
 
 
6078
  `x`.
6079
 
6080
  *Remarks:* The effect of calling each of these functions is
6081
  *implementation-defined* if `n >= 128` or if `m >= 128`.
6082
 
6083
+ #### Associated Legendre functions <a id="sf.cmath.assoc.legendre">[[sf.cmath.assoc.legendre]]</a>
6084
 
6085
  ``` cpp
6086
  double assoc_legendre(unsigned l, unsigned m, double x);
6087
  float assoc_legendref(unsigned l, unsigned m, float x);
6088
  long double assoc_legendrel(unsigned l, unsigned m, long double x);
6089
  ```
6090
 
6091
  *Effects:* These functions compute the associated Legendre functions of
6092
  their respective arguments `l`, `m`, and `x`.
6093
 
6094
+ *Returns:* $$\mathsf{P}_\ell^m(x) = (1 - x^2) ^ {m/2} \:
6095
+ \frac{\mathsf{d} ^ m}{\mathsf{d}x ^ m} \, \mathsf{P}_\ell(x)
6096
+ \text{ ,\quad for $|x| \le 1$,}$$ where l is `l`, m is `m`, and x is
 
 
 
 
6097
  `x`.
6098
 
6099
  *Remarks:* The effect of calling each of these functions is
6100
  *implementation-defined* if `l >= 128`.
6101
 
 
6108
  ```
6109
 
6110
  *Effects:* These functions compute the beta function of their respective
6111
  arguments `x` and `y`.
6112
 
6113
+ *Returns:*
6114
+ $$\mathsf{B}(x, y) = \frac{\Gamma(x) \, \Gamma(y)}{\Gamma(x + y)}
6115
+ \text{ ,\quad for $x > 0$,\, $y > 0$,}$$ where x is `x` and y is `y`.
 
 
 
6116
 
6117
+ #### Complete elliptic integral of the first kind <a id="sf.cmath.comp.ellint.1">[[sf.cmath.comp.ellint.1]]</a>
6118
 
6119
  ``` cpp
6120
  double comp_ellint_1(double k);
6121
  float comp_ellint_1f(float k);
6122
  long double comp_ellint_1l(long double k);
6123
  ```
6124
 
6125
  *Effects:* These functions compute the complete elliptic integral of the
6126
  first kind of their respective arguments `k`.
6127
 
6128
+ *Returns:*
6129
+ $$\mathsf{K}(k) = \mathsf{F}(k, \pi / 2) \text{ ,\quad for $|k| \le 1$,}$$
6130
+ where k is `k`.
 
6131
 
6132
+ See also [[sf.cmath.ellint.1]].
6133
 
6134
+ #### Complete elliptic integral of the second kind <a id="sf.cmath.comp.ellint.2">[[sf.cmath.comp.ellint.2]]</a>
6135
 
6136
  ``` cpp
6137
  double comp_ellint_2(double k);
6138
  float comp_ellint_2f(float k);
6139
  long double comp_ellint_2l(long double k);
6140
  ```
6141
 
6142
  *Effects:* These functions compute the complete elliptic integral of the
6143
  second kind of their respective arguments `k`.
6144
 
6145
+ *Returns:*
6146
+ $$\mathsf{E}(k) = \mathsf{E}(k, \pi / 2) \text{ ,\quad for $|k| \le 1$,}$$
6147
+ where k is `k`.
 
6148
 
6149
+ See also [[sf.cmath.ellint.2]].
6150
 
6151
+ #### Complete elliptic integral of the third kind <a id="sf.cmath.comp.ellint.3">[[sf.cmath.comp.ellint.3]]</a>
6152
 
6153
  ``` cpp
6154
  double comp_ellint_3(double k, double nu);
6155
  float comp_ellint_3f(float k, float nu);
6156
  long double comp_ellint_3l(long double k, long double nu);
6157
  ```
6158
 
6159
  *Effects:* These functions compute the complete elliptic integral of the
6160
  third kind of their respective arguments `k` and `nu`.
6161
 
6162
+ *Returns:*
6163
+ $$\mathsf{\Pi}(\nu, k) = \mathsf{\Pi}(\nu, k, \pi / 2) \text{ ,\quad for $|k| \le 1$,}$$
6164
+ where k is `k` and $\nu$ is `nu`.
6165
 
6166
+ See also [[sf.cmath.ellint.3]].
6167
 
6168
+ #### Regular modified cylindrical Bessel functions <a id="sf.cmath.cyl.bessel.i">[[sf.cmath.cyl.bessel.i]]</a>
6169
 
6170
  ``` cpp
6171
  double cyl_bessel_i(double nu, double x);
6172
  float cyl_bessel_if(float nu, float x);
6173
  long double cyl_bessel_il(long double nu, long double x);
6174
  ```
6175
 
6176
  *Effects:* These functions compute the regular modified cylindrical
6177
  Bessel functions of their respective arguments `nu` and `x`.
6178
 
6179
+ *Returns:* $$\mathsf{I}_\nu(x) =
6180
+ i^{-\nu} \mathsf{J}_\nu(ix) =
6181
+ \sum_{k=0}^\infty \frac{(x/2)^{\nu+2k}}{k! \: \Gamma(\nu+k+1)}
6182
+ \text{ ,\quad for $x \ge 0$,}$$ where $\nu$ is `nu` and x is `x`.
 
 
 
6183
 
6184
  *Remarks:* The effect of calling each of these functions is
6185
  *implementation-defined* if `nu >= 128`.
6186
 
6187
+ See also [[sf.cmath.cyl.bessel.j]].
6188
 
6189
+ #### Cylindrical Bessel functions of the first kind <a id="sf.cmath.cyl.bessel.j">[[sf.cmath.cyl.bessel.j]]</a>
6190
 
6191
  ``` cpp
6192
  double cyl_bessel_j(double nu, double x);
6193
  float cyl_bessel_jf(float nu, float x);
6194
  long double cyl_bessel_jl(long double nu, long double x);
6195
  ```
6196
 
6197
  *Effects:* These functions compute the cylindrical Bessel functions of
6198
  the first kind of their respective arguments `nu` and `x`.
6199
 
6200
+ *Returns:* $$\mathsf{J}_\nu(x) =
6201
+ \sum_{k=0}^\infty \frac{(-1)^k (x/2)^{\nu+2k}}{k! \: \Gamma(\nu+k+1)}
6202
+ \text{ ,\quad for $x \ge 0$,}$$ where $\nu$ is `nu` and x is `x`.
 
 
6203
 
6204
  *Remarks:* The effect of calling each of these functions is
6205
  *implementation-defined* if `nu >= 128`.
6206
 
6207
+ #### Irregular modified cylindrical Bessel functions <a id="sf.cmath.cyl.bessel.k">[[sf.cmath.cyl.bessel.k]]</a>
6208
 
6209
  ``` cpp
6210
  double cyl_bessel_k(double nu, double x);
6211
  float cyl_bessel_kf(float nu, float x);
6212
  long double cyl_bessel_kl(long double nu, long double x);
 
6239
  \right.$$ where $\nu$ is `nu` and x is `x`.
6240
 
6241
  *Remarks:* The effect of calling each of these functions is
6242
  *implementation-defined* if `nu >= 128`.
6243
 
6244
+ See also [[sf.cmath.cyl.bessel.i]], [[sf.cmath.cyl.bessel.j]],
6245
+ [[sf.cmath.cyl.neumann]].
6246
 
6247
+ #### Cylindrical Neumann functions <a id="sf.cmath.cyl.neumann">[[sf.cmath.cyl.neumann]]</a>
6248
 
6249
  ``` cpp
6250
  double cyl_neumann(double nu, double x);
6251
  float cyl_neumannf(float nu, float x);
6252
  long double cyl_neumannl(long double nu, long double x);
 
6274
  \right.$$ where $\nu$ is `nu` and x is `x`.
6275
 
6276
  *Remarks:* The effect of calling each of these functions is
6277
  *implementation-defined* if `nu >= 128`.
6278
 
6279
+ See also [[sf.cmath.cyl.bessel.j]].
6280
 
6281
+ #### Incomplete elliptic integral of the first kind <a id="sf.cmath.ellint.1">[[sf.cmath.ellint.1]]</a>
6282
 
6283
  ``` cpp
6284
  double ellint_1(double k, double phi);
6285
  float ellint_1f(float k, float phi);
6286
  long double ellint_1l(long double k, long double phi);
 
6288
 
6289
  *Effects:* These functions compute the incomplete elliptic integral of
6290
  the first kind of their respective arguments `k` and `phi` (`phi`
6291
  measured in radians).
6292
 
6293
+ *Returns:* $$\mathsf{F}(k, \phi) =
6294
+ \int_0^\phi \! \frac{\mathsf{d}\theta}{\sqrt{1 - k^2 \sin^2 \theta}}
6295
+ \text{ ,\quad for $|k| \le 1$,}$$ where k is `k` and φ is `phi`.
 
 
6296
 
6297
+ #### Incomplete elliptic integral of the second kind <a id="sf.cmath.ellint.2">[[sf.cmath.ellint.2]]</a>
6298
 
6299
  ``` cpp
6300
  double ellint_2(double k, double phi);
6301
  float ellint_2f(float k, float phi);
6302
  long double ellint_2l(long double k, long double phi);
 
6304
 
6305
  *Effects:* These functions compute the incomplete elliptic integral of
6306
  the second kind of their respective arguments `k` and `phi` (`phi`
6307
  measured in radians).
6308
 
6309
+ *Returns:*
6310
+ $$\mathsf{E}(k, \phi) = \int_0^\phi \! \sqrt{1 - k^2 \sin^2 \theta} \, \mathsf{d}\theta
6311
+ \text{ ,\quad for $|k| \le 1$,}$$ where k is `k` and φ is `phi`.
 
6312
 
6313
+ #### Incomplete elliptic integral of the third kind <a id="sf.cmath.ellint.3">[[sf.cmath.ellint.3]]</a>
6314
 
6315
  ``` cpp
6316
  double ellint_3(double k, double nu, double phi);
6317
  float ellint_3f(float k, float nu, float phi);
6318
  long double ellint_3l(long double k, long double nu, long double phi);
 
6320
 
6321
  *Effects:* These functions compute the incomplete elliptic integral of
6322
  the third kind of their respective arguments `k`, `nu`, and `phi` (`phi`
6323
  measured in radians).
6324
 
6325
+ *Returns:* $$\mathsf{\Pi}(\nu, k, \phi) = \int_0^\phi \!
6326
+ \frac{ \mathsf{d}\theta }{ (1 - \nu \, \sin^2 \theta) \sqrt{1 - k^2 \sin^2 \theta} } \text{ ,\quad for $|k| \le 1$,}$$
6327
+ where $\nu$ is `nu`, k is `k`, and φ is `phi`.
 
 
 
6328
 
6329
  #### Exponential integral <a id="sf.cmath.expint">[[sf.cmath.expint]]</a>
6330
 
6331
  ``` cpp
6332
  double expint(double x);
 
6372
  ```
6373
 
6374
  *Effects:* These functions compute the Laguerre polynomials of their
6375
  respective arguments `n` and `x`.
6376
 
6377
+ *Returns:* $$\mathsf{L}_n(x) =
6378
+ \frac{e^x}{n!} \frac{\mathsf{d}^n}{\mathsf{d}x^n} \, (x^n e^{-x})
6379
+ \text{ ,\quad for $x \ge 0$,}$$ where n is `n` and x is `x`.
 
 
6380
 
6381
  *Remarks:* The effect of calling each of these functions is
6382
  *implementation-defined* if `n >= 128`.
6383
 
6384
  #### Legendre polynomials <a id="sf.cmath.legendre">[[sf.cmath.legendre]]</a>
 
6390
  ```
6391
 
6392
  *Effects:* These functions compute the Legendre polynomials of their
6393
  respective arguments `l` and `x`.
6394
 
6395
+ *Returns:* $$\mathsf{P}_\ell(x) =
6396
+ \frac{1}{2^\ell \, \ell!}
6397
+ \frac{\mathsf{d}^\ell}{\mathsf{d}x^\ell} \, (x^2 - 1) ^ \ell
6398
+ \text{ ,\quad for $|x| \le 1$,}$$ where l is `l` and x is `x`.
 
 
 
6399
 
6400
  *Remarks:* The effect of calling each of these functions is
6401
  *implementation-defined* if `l >= 128`.
6402
 
6403
+ #### Riemann zeta function <a id="sf.cmath.riemann.zeta">[[sf.cmath.riemann.zeta]]</a>
6404
 
6405
  ``` cpp
6406
  double riemann_zeta(double x);
6407
  float riemann_zetaf(float x);
6408
  long double riemann_zetal(long double x);
 
6432
  & \mbox{for $x < 0$}
6433
  \end{array}
6434
  \right.
6435
  \;$$ where x is `x`.
6436
 
6437
+ #### Spherical Bessel functions of the first kind <a id="sf.cmath.sph.bessel">[[sf.cmath.sph.bessel]]</a>
6438
 
6439
  ``` cpp
6440
  double sph_bessel(unsigned n, double x);
6441
  float sph_besself(unsigned n, float x);
6442
  long double sph_bessell(unsigned n, long double x);
6443
  ```
6444
 
6445
  *Effects:* These functions compute the spherical Bessel functions of the
6446
  first kind of their respective arguments `n` and `x`.
6447
 
6448
+ *Returns:*
6449
+ $$\mathsf{j}_n(x) = (\pi/2x)^{1\!/\!2} \mathsf{J}_{n + 1\!/\!2}(x) \text{ ,\quad for $x \ge 0$,}$$
6450
+ where n is `n` and x is `x`.
 
6451
 
6452
  *Remarks:* The effect of calling each of these functions is
6453
  *implementation-defined* if `n >= 128`.
6454
 
6455
+ See also [[sf.cmath.cyl.bessel.j]].
6456
 
6457
+ #### Spherical associated Legendre functions <a id="sf.cmath.sph.legendre">[[sf.cmath.sph.legendre]]</a>
6458
 
6459
  ``` cpp
6460
  double sph_legendre(unsigned l, unsigned m, double theta);
6461
  float sph_legendref(unsigned l, unsigned m, float theta);
6462
  long double sph_legendrel(unsigned l, unsigned m, long double theta);
 
6464
 
6465
  *Effects:* These functions compute the spherical associated Legendre
6466
  functions of their respective arguments `l`, `m`, and `theta` (`theta`
6467
  measured in radians).
6468
 
6469
+ *Returns:* $$\mathsf{Y}_\ell^m(\theta, 0)$$ where
6470
+ $$\mathsf{Y}_\ell^m(\theta, \phi) =
6471
+ (-1)^m \left[\frac{(2 \ell + 1)}{4 \pi} \frac{(\ell - m)!}{(\ell + m)!}\right]^{1/2}
6472
+ \mathsf{P}_\ell^m (\cos\theta) e^{i m \phi}
6473
+ \text{ ,\quad for $|m| \le \ell$,}$$ and l is `l`, m is `m`, and θ
 
 
 
 
 
 
 
6474
  is `theta`.
6475
 
6476
  *Remarks:* The effect of calling each of these functions is
6477
  *implementation-defined* if `l >= 128`.
6478
 
6479
+ See also [[sf.cmath.assoc.legendre]].
6480
 
6481
+ #### Spherical Neumann functions <a id="sf.cmath.sph.neumann">[[sf.cmath.sph.neumann]]</a>
6482
 
6483
  ``` cpp
6484
  double sph_neumann(unsigned n, double x);
6485
  float sph_neumannf(unsigned n, float x);
6486
  long double sph_neumannl(unsigned n, long double x);
 
6488
 
6489
  *Effects:* These functions compute the spherical Neumann functions, also
6490
  known as the spherical Bessel functions of the second kind, of their
6491
  respective arguments `n` and `x`.
6492
 
6493
+ *Returns:*
6494
+ $$\mathsf{n}_n(x) = (\pi/2x)^{1\!/\!2} \mathsf{N}_{n + 1\!/\!2}(x)
6495
+ \text{ ,\quad for $x \ge 0$,}$$ where n is `n` and x is `x`.
 
6496
 
6497
  *Remarks:* The effect of calling each of these functions is
6498
  *implementation-defined* if `n >= 128`.
6499
 
6500
+ See also [[sf.cmath.cyl.neumann]].
6501
+
6502
+ ## Numbers <a id="numbers">[[numbers]]</a>
6503
+
6504
+ ### Header `<numbers>` synopsis <a id="numbers.syn">[[numbers.syn]]</a>
6505
+
6506
+ ``` cpp
6507
+ namespace std::numbers {
6508
+ template<class T> inline constexpr T e_v = unspecified;
6509
+ template<class T> inline constexpr T log2e_v = unspecified;
6510
+ template<class T> inline constexpr T log10e_v = unspecified;
6511
+ template<class T> inline constexpr T pi_v = unspecified;
6512
+ template<class T> inline constexpr T inv_pi_v = unspecified;
6513
+ template<class T> inline constexpr T inv_sqrtpi_v = unspecified;
6514
+ template<class T> inline constexpr T ln2_v = unspecified;
6515
+ template<class T> inline constexpr T ln10_v = unspecified;
6516
+ template<class T> inline constexpr T sqrt2_v = unspecified;
6517
+ template<class T> inline constexpr T sqrt3_v = unspecified;
6518
+ template<class T> inline constexpr T inv_sqrt3_v = unspecified;
6519
+ template<class T> inline constexpr T egamma_v = unspecified;
6520
+ template<class T> inline constexpr T phi_v = unspecified;
6521
+
6522
+ template<floating_point T> inline constexpr T e_v<T> = see below;
6523
+ template<floating_point T> inline constexpr T log2e_v<T> = see below;
6524
+ template<floating_point T> inline constexpr T log10e_v<T> = see below;
6525
+ template<floating_point T> inline constexpr T pi_v<T> = see below;
6526
+ template<floating_point T> inline constexpr T inv_pi_v<T> = see below;
6527
+ template<floating_point T> inline constexpr T inv_sqrtpi_v<T> = see below;
6528
+ template<floating_point T> inline constexpr T ln2_v<T> = see below;
6529
+ template<floating_point T> inline constexpr T ln10_v<T> = see below;
6530
+ template<floating_point T> inline constexpr T sqrt2_v<T> = see below;
6531
+ template<floating_point T> inline constexpr T sqrt3_v<T> = see below;
6532
+ template<floating_point T> inline constexpr T inv_sqrt3_v<T> = see below;
6533
+ template<floating_point T> inline constexpr T egamma_v<T> = see below;
6534
+ template<floating_point T> inline constexpr T phi_v<T> = see below;
6535
+
6536
+ inline constexpr double e = e_v<double>;
6537
+ inline constexpr double log2e = log2e_v<double>;
6538
+ inline constexpr double log10e = log10e_v<double>;
6539
+ inline constexpr double pi = pi_v<double>;
6540
+ inline constexpr double inv_pi = inv_pi_v<double>;
6541
+ inline constexpr double inv_sqrtpi = inv_sqrtpi_v<double>;
6542
+ inline constexpr double ln2 = ln2_v<double>;
6543
+ inline constexpr double ln10 = ln10_v<double>;
6544
+ inline constexpr double sqrt2 = sqrt2_v<double>;
6545
+ inline constexpr double sqrt3 = sqrt3_v<double>;
6546
+ inline constexpr double inv_sqrt3 = inv_sqrt3_v<double>;
6547
+ inline constexpr double egamma = egamma_v<double>;
6548
+ inline constexpr double phi = phi_v<double>;
6549
+ }
6550
+ ```
6551
+
6552
+ ### Mathematical constants <a id="math.constants">[[math.constants]]</a>
6553
+
6554
+ The library-defined partial specializations of mathematical constant
6555
+ variable templates are initialized with the nearest representable values
6556
+ of e, log₂ e, log₁₀ e, π, $\frac{1}{\pi}$, $\frac{1}{\sqrt{\pi}}$,
6557
+ $\ln 2$, $\ln 10$, $\sqrt{2}$, $\sqrt{3}$, $\frac{1}{\sqrt{3}}$, the
6558
+ Euler-Mascheroni γ constant, and the golden ratio φ constant
6559
+ $\frac{1+\sqrt{5}}{2}$, respectively.
6560
+
6561
+ Pursuant to [[namespace.std]], a program may partially or explicitly
6562
+ specialize a mathematical constant variable template provided that the
6563
+ specialization depends on a program-defined type.
6564
+
6565
+ A program that instantiates a primary template of a mathematical
6566
+ constant variable template is ill-formed.
6567
 
6568
  <!-- Link reference definitions -->
6569
+ [bad.alloc]: support.md#bad.alloc
 
 
 
6570
  [basic.fundamental]: basic.md#basic.fundamental
6571
  [basic.stc.thread]: basic.md#basic.stc.thread
6572
  [basic.types]: basic.md#basic.types
6573
+ [bit]: #bit
6574
+ [bit.cast]: #bit.cast
6575
+ [bit.count]: #bit.count
6576
+ [bit.endian]: #bit.endian
6577
+ [bit.general]: #bit.general
6578
+ [bit.pow.two]: #bit.pow.two
6579
+ [bit.rotate]: #bit.rotate
6580
+ [bit.syn]: #bit.syn
6581
  [c.math]: #c.math
6582
  [c.math.abs]: #c.math.abs
6583
  [c.math.fpclass]: #c.math.fpclass
6584
  [c.math.hypot3]: #c.math.hypot3
6585
+ [c.math.lerp]: #c.math.lerp
6586
  [c.math.rand]: #c.math.rand
6587
  [cfenv]: #cfenv
6588
  [cfenv.syn]: #cfenv.syn
6589
  [class.gslice]: #class.gslice
6590
  [class.gslice.overview]: #class.gslice.overview
 
6601
  [complex.special]: #complex.special
6602
  [complex.syn]: #complex.syn
6603
  [complex.transcendentals]: #complex.transcendentals
6604
  [complex.value.ops]: #complex.value.ops
6605
  [cons.slice]: #cons.slice
6606
+ [conv.prom]: expr.md#conv.prom
6607
  [cpp.pragma]: cpp.md#cpp.pragma
6608
+ [cpp17.copyassignable]: #cpp17.copyassignable
6609
+ [cpp17.copyconstructible]: #cpp17.copyconstructible
6610
+ [cpp17.equalitycomparable]: #cpp17.equalitycomparable
6611
  [dcl.init]: dcl.md#dcl.init
6612
+ [expr.const]: expr.md#expr.const
 
6613
  [gslice.access]: #gslice.access
6614
  [gslice.array.assign]: #gslice.array.assign
6615
  [gslice.array.comp.assign]: #gslice.array.comp.assign
6616
  [gslice.array.fill]: #gslice.array.fill
6617
  [gslice.cons]: #gslice.cons
6618
  [implimits]: limits.md#implimits
 
6619
  [indirect.array.assign]: #indirect.array.assign
6620
  [indirect.array.comp.assign]: #indirect.array.comp.assign
6621
  [indirect.array.fill]: #indirect.array.fill
 
6622
  [input.iterators]: iterators.md#input.iterators
6623
  [input.output]: input.md#input.output
6624
+ [intro.object]: basic.md#intro.object
6625
  [iostate.flags]: input.md#iostate.flags
6626
  [istream.formatted]: input.md#istream.formatted
6627
+ [iterator.concept.contiguous]: iterators.md#iterator.concept.contiguous
6628
  [iterator.requirements.general]: iterators.md#iterator.requirements.general
6629
  [library.c]: library.md#library.c
6630
  [mask.array.assign]: #mask.array.assign
6631
  [mask.array.comp.assign]: #mask.array.comp.assign
6632
  [mask.array.fill]: #mask.array.fill
6633
+ [math.constants]: #math.constants
6634
+ [namespace.std]: library.md#namespace.std
6635
  [numarray]: #numarray
6636
+ [numbers]: #numbers
6637
+ [numbers.syn]: #numbers.syn
 
 
 
6638
  [numeric.requirements]: #numeric.requirements
6639
  [numerics]: #numerics
 
6640
  [numerics.general]: #numerics.general
6641
+ [numerics.summary]: #numerics.summary
6642
  [output.iterators]: iterators.md#output.iterators
 
6643
  [rand]: #rand
6644
  [rand.adapt]: #rand.adapt
6645
  [rand.adapt.disc]: #rand.adapt.disc
6646
  [rand.adapt.general]: #rand.adapt.general
6647
  [rand.adapt.ibits]: #rand.adapt.ibits
 
6689
  [rand.synopsis]: #rand.synopsis
6690
  [rand.util]: #rand.util
6691
  [rand.util.canonical]: #rand.util.canonical
6692
  [rand.util.seedseq]: #rand.util.seedseq
6693
  [random.access.iterators]: iterators.md#random.access.iterators
 
6694
  [res.on.data.races]: library.md#res.on.data.races
6695
  [sf.cmath]: #sf.cmath
6696
+ [sf.cmath.assoc.laguerre]: #sf.cmath.assoc.laguerre
6697
+ [sf.cmath.assoc.legendre]: #sf.cmath.assoc.legendre
6698
  [sf.cmath.beta]: #sf.cmath.beta
6699
+ [sf.cmath.comp.ellint.1]: #sf.cmath.comp.ellint.1
6700
+ [sf.cmath.comp.ellint.2]: #sf.cmath.comp.ellint.2
6701
+ [sf.cmath.comp.ellint.3]: #sf.cmath.comp.ellint.3
6702
+ [sf.cmath.cyl.bessel.i]: #sf.cmath.cyl.bessel.i
6703
+ [sf.cmath.cyl.bessel.j]: #sf.cmath.cyl.bessel.j
6704
+ [sf.cmath.cyl.bessel.k]: #sf.cmath.cyl.bessel.k
6705
+ [sf.cmath.cyl.neumann]: #sf.cmath.cyl.neumann
6706
+ [sf.cmath.ellint.1]: #sf.cmath.ellint.1
6707
+ [sf.cmath.ellint.2]: #sf.cmath.ellint.2
6708
+ [sf.cmath.ellint.3]: #sf.cmath.ellint.3
6709
  [sf.cmath.expint]: #sf.cmath.expint
6710
  [sf.cmath.hermite]: #sf.cmath.hermite
6711
  [sf.cmath.laguerre]: #sf.cmath.laguerre
6712
  [sf.cmath.legendre]: #sf.cmath.legendre
6713
+ [sf.cmath.riemann.zeta]: #sf.cmath.riemann.zeta
6714
+ [sf.cmath.sph.bessel]: #sf.cmath.sph.bessel
6715
+ [sf.cmath.sph.legendre]: #sf.cmath.sph.legendre
6716
+ [sf.cmath.sph.neumann]: #sf.cmath.sph.neumann
6717
  [slice.access]: #slice.access
6718
  [slice.arr.assign]: #slice.arr.assign
6719
  [slice.arr.comp.assign]: #slice.arr.comp.assign
6720
  [slice.arr.fill]: #slice.arr.fill
6721
+ [slice.ops]: #slice.ops
6722
  [strings]: strings.md#strings
 
 
 
 
 
 
 
 
 
 
 
6723
  [template.gslice.array]: #template.gslice.array
6724
  [template.gslice.array.overview]: #template.gslice.array.overview
6725
  [template.indirect.array]: #template.indirect.array
6726
  [template.indirect.array.overview]: #template.indirect.array.overview
6727
  [template.mask.array]: #template.mask.array
6728
  [template.mask.array.overview]: #template.mask.array.overview
6729
  [template.slice.array]: #template.slice.array
6730
  [template.slice.array.overview]: #template.slice.array.overview
6731
  [template.valarray]: #template.valarray
6732
  [template.valarray.overview]: #template.valarray.overview
6733
+ [thread.jthread.class]: thread.md#thread.jthread.class
6734
  [thread.thread.class]: thread.md#thread.thread.class
6735
+ [utility.arg.requirements]: library.md#utility.arg.requirements
 
 
6736
  [valarray.access]: #valarray.access
6737
  [valarray.assign]: #valarray.assign
6738
  [valarray.binary]: #valarray.binary
6739
  [valarray.cassign]: #valarray.cassign
6740
  [valarray.comparison]: #valarray.comparison
 
6745
  [valarray.special]: #valarray.special
6746
  [valarray.sub]: #valarray.sub
6747
  [valarray.syn]: #valarray.syn
6748
  [valarray.transcend]: #valarray.transcend
6749
  [valarray.unary]: #valarray.unary
 
6750
 
6751
  [^1]: In other words, value types. These include arithmetic types,
6752
  pointers, the library class `complex`, and instantiations of
6753
  `valarray` for value types.
6754
 
 
6769
  [^6]: The distribution corresponding to this probability density
6770
  function is also known (with a possible change of variable) as the
6771
  Gumbel Type I, the log-Weibull, or the Fisher-Tippett Type I
6772
  distribution.
6773
 
6774
+ [^7]: [[implimits]] recommends a minimum number of recursively nested
6775
+ template instantiations. This requirement thus indirectly suggests a
6776
+ minimum allowable complexity for valarray expressions.
6777
 
6778
  [^8]: The intent is to specify an array template that has the minimum
6779
  functionality necessary to address aliasing ambiguities and the
6780
+ proliferation of temporary objects. Thus, the `valarray` template is
6781
  neither a matrix class nor a field class. However, it is a very
6782
  useful building block for designing such classes.
6783
 
6784
  [^9]: This default constructor is essential, since arrays of `valarray`
6785
  may be useful. After initialization, the length of an empty array
 
6788
  [^10]: This constructor is the preferred method for converting a C array
6789
  to a `valarray` object.
6790
 
6791
  [^11]: This copy constructor creates a distinct array rather than an
6792
  alias. Implementations in which arrays share storage are permitted,
6793
+ but they would need to implement a copy-on-reference mechanism to
6794
+ ensure that arrays are conceptually distinct.
6795
 
6796
  [^12]: BLAS stands for *Basic Linear Algebra Subprograms.* C++ programs
6797
  may instantiate this class. See, for example, Dongarra, Du Croz,
6798
  Duff, and Hammerling: *A set of Level 3 Basic Linear Algebra
6799
  Subprograms*; Technical Report MCS-P1-0888, Argonne National
6800
  Laboratory (USA), Mathematics and Computer Science Division, August,
6801
  1988.
6802
 
6803
+ [^13]: A mathematical function is mathematically defined for a given set
 
 
 
 
 
 
 
 
 
 
 
 
 
6804
  of argument values (a) if it is explicitly defined for that set of
6805
  argument values, or (b) if its limiting value exists and does not
6806
  depend on the direction of approach.