Working Draft, Standard for Programming Language C++ (N4713, 2017 year) - page 35
29.8.7
Exclusive scan
[exclusive.scan]
template<class InputIterator, class OutputIterator, class T>
OutputIterator exclusive_scan(InputIterator first, InputIterator last,
OutputIterator result, T init);
1
Effects: Equivalent to:
return exclusive_scan(first, last, result, init, plus<>());
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2, class T>
ForwardIterator2 exclusive_scan(ExecutionPolicy&& exec,
ForwardIterator1 first, ForwardIterator1 last,
ForwardIterator2 result, T init);
2
Effects: Equivalent to:
return exclusive_scan(std::forward<ExecutionPolicy>(exec),
first, last, result, init, plus<>());
template<class InputIterator, class OutputIterator, class T, class BinaryOperation>
OutputIterator exclusive_scan(InputIterator first, InputIterator last,
OutputIterator result, T init, BinaryOperation binary_op);
template<class ExecutionPolicy,
class ForwardIterator1, class ForwardIterator2, class T, class BinaryOperation>
ForwardIterator2 exclusive_scan(ExecutionPolicy&& exec,
ForwardIterator1 first, ForwardIterator1 last,
ForwardIterator2 result, T init, BinaryOperation binary_op);
3
Requires:
(3.1)
—
T shall be MoveConstructible (Table 23).
(3.2)
—
All of binary_op(init, init), binary_op(init, *first), and binary_op(*first, *first)
shall be convertible to T.
(3.3)
—
binary_op shall neither invalidate iterators or subranges, nor modify elements in the ranges
[first, last] or [result, result + (last - first)].
4
Effects: For each integer K in [0, last - first) assigns through result + K the value of:
GENERALIZED_NONCOMMUTATIVE_SUM(
binary_op, init, *(first + 0), *(first + 1), ..., *(first + K - 1))
5
Returns: The end of the resulting range beginning at result.
6
Complexity: O(last - first) applications of binary_op.
7
Remarks: result may be equal to first.
8
[ Note: The difference between exclusive_scan and inclusive_scan is that exclusive_scan excludes
the ith input element from the ith sum. If binary_op is not mathematically associative, the behavior
of exclusive_scan may be nondeterministic.
— end note ]
29.8.8
Inclusive scan
[inclusive.scan]
template<class InputIterator, class OutputIterator>
OutputIterator inclusive_scan(InputIterator first, InputIterator last, OutputIterator result);
1
Effects: Equivalent to:
return inclusive_scan(first, last, result, plus<>());
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
ForwardIterator2 inclusive_scan(ExecutionPolicy&& exec,
ForwardIterator1 first, ForwardIterator1 last,
ForwardIterator2 result);
2
Effects: Equivalent to:
return inclusive_scan(std::forward<ExecutionPolicy>(exec), first, last, result, plus<>());
template<class InputIterator, class OutputIterator, class BinaryOperation>
OutputIterator inclusive_scan(InputIterator first, InputIterator last,
OutputIterator result, BinaryOperation binary_op);
§ 29.8.8
1012
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
class BinaryOperation>
ForwardIterator2 inclusive_scan(ExecutionPolicy&& exec,
ForwardIterator1 first, ForwardIterator1 last,
ForwardIterator2 result, BinaryOperation binary_op);
template<class InputIterator, class OutputIterator, class BinaryOperation, class T>
OutputIterator inclusive_scan(InputIterator first, InputIterator last,
OutputIterator result, BinaryOperation binary_op, T init);
template<class ExecutionPolicy,
class ForwardIterator1, class ForwardIterator2, class BinaryOperation, class T>
ForwardIterator2 inclusive_scan(ExecutionPolicy&& exec,
ForwardIterator1 first, ForwardIterator1 last,
ForwardIterator2 result, BinaryOperation binary_op, T init);
3
Requires:
(3.1)
—
If init is provided, T shall be MoveConstructible (Table 23); otherwise, ForwardIterator1’s
value type shall be MoveConstructible.
(3.2)
—
If init is provided, all of binary_op(init, init), binary_op(init, *first), and binary_-
op(*first, *first) shall be convertible to T; otherwise, binary_op(*first, *first) shall be
convertible to ForwardIterator1’s value type.
(3.3)
—
binary_op shall neither invalidate iterators or subranges, nor modify elements in the ranges
[first, last] or [result, result + (last - first)].
4
Effects: For each integer K in [0, last - first) assigns through result + K the value of
(4.1)
—
GENERALIZED_NONCOMMUTATIVE_SUM(
binary_op, init, *(first + 0), *(first + 1), ..., *(first + K))
if init is provided, or
(4.2)
—
GENERALIZED_NONCOMMUTATIVE_SUM(
binary_op, *(first + 0), *(first + 1), ..., *(first + K))
otherwise.
5
Returns: The end of the resulting range beginning at result.
6
Complexity: O(last - first) applications of binary_op.
7
Remarks: result may be equal to first.
8
[ Note: The difference between exclusive_scan and inclusive_scan is that inclusive_scan includes
the ith input element in the ith sum. If binary_op is not mathematically associative, the behavior of
inclusive_scan may be nondeterministic. — end note ]
29.8.9
Transform exclusive scan
[transform.exclusive.scan]
template<class InputIterator, class OutputIterator, class T,
class BinaryOperation, class UnaryOperation>
OutputIterator transform_exclusive_scan(InputIterator first, InputIterator last,
OutputIterator result, T init,
BinaryOperation binary_op,UnaryOperation unary_op);
template<class ExecutionPolicy,
class ForwardIterator1, class ForwardIterator2, class T,
class BinaryOperation, class UnaryOperation>
ForwardIterator2 transform_exclusive_scan(ExecutionPolicy&& exec,
ForwardIterator1 first, ForwardIterator1 last,
ForwardIterator2 result, T init,
BinaryOperation binary_op, UnaryOperation unary_op);
1
Requires:
(1.1)
—
T shall be MoveConstructible (Table 23).
(1.2)
—
All of
(1.2.1)
—
binary_op(init, init),
(1.2.2)
—
binary_op(init, unary_op(*first)), and
§ 29.8.9
1013
(1.2.3)
—
binary_op(unary_op(*first), unary_op(*first))
shall be convertible to T.
(1.3)
—
Neither unary_op nor binary_op shall invalidate iterators or subranges, or modify elements in
the ranges [first, last] or [result, result + (last - first)].
2
Effects: For each integer K in [0, last - first) assigns through result + K the value of:
GENERALIZED_NONCOMMUTATIVE_SUM(
binary_op, init,
unary_op(*(first + 0)), unary_op(*(first + 1)), ..., unary_op(*(first + K - 1)))
3
Returns: The end of the resulting range beginning at result.
4
Complexity: O(last - first) applications each of unary_op and binary_op.
5
Remarks: result may be equal to first.
6
[Note: The difference between transform_exclusive_scan and transform_inclusive_scan is that
transform_exclusive_scan excludes the ith input element from the ith sum. If binary_op is not
mathematically associative, the behavior of transform_exclusive_scan may be nondeterministic.
transform_exclusive_scan does not apply unary_op to init. — end note ]
29.8.10
Transform inclusive scan
[transform.inclusive.scan]
template<class InputIterator, class OutputIterator,
class BinaryOperation, class UnaryOperation>
OutputIterator transform_inclusive_scan(InputIterator first, InputIterator last,
OutputIterator result,
BinaryOperation binary_op, UnaryOperation unary_op);
template<class ExecutionPolicy,
class ForwardIterator1, class ForwardIterator2,
class BinaryOperation, class UnaryOperation>
ForwardIterator2 transform_inclusive_scan(ExecutionPolicy&& exec,
ForwardIterator1 first, ForwardIterator1 last,
ForwardIterator2 result,
BinaryOperation binary_op, UnaryOperation unary_op);
template<class InputIterator, class OutputIterator,
class BinaryOperation, class UnaryOperation, class T>
OutputIterator transform_inclusive_scan(InputIterator first, InputIterator last,
OutputIterator result,
BinaryOperation binary_op, UnaryOperation unary_op,
T init);
template<class ExecutionPolicy,
class ForwardIterator1, class ForwardIterator2,
class BinaryOperation, class UnaryOperation, class T>
ForwardIterator2 transform_inclusive_scan(ExecutionPolicy&& exec,
ForwardIterator1 first, ForwardIterator1 last,
ForwardIterator2 result,
BinaryOperation binary_op, UnaryOperation unary_op,
T init);
1
Requires:
(1.1)
—
If init is provided, T shall be MoveConstructible (Table 23); otherwise, ForwardIterator1’s
value type shall be MoveConstructible.
(1.2)
—
If init is provided, all of
(1.2.1)
—
binary_op(init, init),
(1.2.2)
—
binary_op(init, unary_op(*first)), and
(1.2.3)
—
binary_op(unary_op(*first), unary_op(*first))
shall be convertible to T; otherwise, binary_op(unary_op(*first), unary_op(*first)) shall
be convertible to ForwardIterator1’s value type.
(1.3)
—
Neither unary_op nor binary_op shall invalidate iterators or subranges, nor modify elements in
the ranges [first, last] or [result, result + (last - first)].
§ 29.8.10
1014
2
Effects: For each integer K in [0, last - first) assigns through result + K the value of
(2.1)
—
GENERALIZED_NONCOMMUTATIVE_SUM(
binary_op, init,
unary_op(*(first + 0)), unary_op(*(first + 1)), ..., unary_op(*(first + K)))
if init is provided, or
(2.2)
—
GENERALIZED_NONCOMMUTATIVE_SUM(
binary_op,
unary_op(*(first + 0)), unary_op(*(first + 1)), ..., unary_op(*(first + K)))
otherwise.
3
Returns: The end of the resulting range beginning at result.
4
Complexity: O(last - first) applications each of unary_op and binary_op.
5
Remarks: result may be equal to first.
6
[Note: The difference between transform_exclusive_scan and transform_inclusive_scan is that
transform_inclusive_scan includes the ith input element in the ith sum. If binary_op is not
mathematically associative, the behavior of transform_inclusive_scan may be nondeterministic.
transform_inclusive_scan does not apply unary_op to init. — end note ]
29.8.11
Adjacent difference
[adjacent.difference]
template<class InputIterator, class OutputIterator>
OutputIterator
adjacent_difference(InputIterator first, InputIterator last, OutputIterator result);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2>
ForwardIterator2
adjacent_difference(ExecutionPolicy&& exec,
ForwardIterator1 first, ForwardIterator1 last, ForwardIterator2 result);
template<class InputIterator, class OutputIterator, class BinaryOperation>
OutputIterator
adjacent_difference(InputIterator first, InputIterator last,
OutputIterator result, BinaryOperation binary_op);
template<class ExecutionPolicy, class ForwardIterator1, class ForwardIterator2,
class BinaryOperation>
ForwardIterator2
adjacent_difference(ExecutionPolicy&& exec,
ForwardIterator1 first, ForwardIterator1 last,
ForwardIterator2 result, BinaryOperation binary_op);
1
Requires:
(1.1)
—
For the overloads with no ExecutionPolicy, InputIterator’s value type shall be MoveAssignable
(Table 25) and shall be constructible from the type of *first. acc (defined below) shall be writable
(27.2.1) to the result output iterator. The result of the expression val - std::move(acc) or
binary_op(val, std::move(acc)) shall be writable to the result output iterator.
—
(1.2)
For the overloads with an ExecutionPolicy, the value type of ForwardIterator1 shall be
CopyConstructible (Table 24), constructible from the expression *first - *first or binary_-
op(*first, *first), and assignable to the value type of ForwardIterator2.
—
(1.3)
For all overloads, in the ranges [first, last] and [result, result + (last - first)],
binary_op shall neither modify elements nor invalidate iterators or subranges.288
2
Effects: For the overloads with no ExecutionPolicy and a non-empty range, the function creates an
accumulator acc whose type is InputIterator’s value type, initializes it with *first, and assigns
the result to *result. For every iterator i in [first + 1, last) in order, creates an object val
whose type is InputIterator’s value type, initializes it with *i, computes val - std::move(acc)
or binary_op(val, std::move(acc)), assigns the result to *(result + (i - first)), and move
assigns from val to acc.
3
For the overloads with an ExecutionPolicy and a non-empty range, first the function creates an
object whose type is ForwardIterator1’s value type, initializes it with *first, and assigns the
288) The use of fully closed ranges is intentional.
§ 29.8.11
1015
result to *result. Then for every d in [1, last - first - 1], creates an object val whose type is
ForwardIterator1’s value type, initializes it with *(first + d) - *(first + d - 1) or binary_-
op(*(first + d), *(first + d - 1)), and assigns the result to *(result + d).
4
Returns: result + (last - first).
5
Complexity: Exactly (last - first) - 1 applications of the binary operation.
6
Remarks: For the overloads with no ExecutionPolicy, result may be equal to first. For the
overloads with an ExecutionPolicy, the ranges [first, last) and [result, result + (last -
first)) shall not overlap.
29.8.12
Iota
[numeric.iota]
template<class ForwardIterator, class T>
void iota(ForwardIterator first, ForwardIterator last, T value);
1
Requires: T shall be convertible to ForwardIterator’s value type. The expression ++val, where val
has type T, shall be well-formed.
2
Effects: For each element referred to by the iterator i in the range [first, last), assigns *i = value
and increments value as if by ++value.
3
Complexity: Exactly last - first increments and assignments.
29.8.13
Greatest common divisor
[numeric.ops.gcd]
template<class M, class N>
constexpr common_type_t<M,N> gcd(M m, N n);
1
Requires:
|m| and |n| shall be representable as a value of common_type_t<M, N>.
[Note: These
requirements ensure, for example, that gcd(m, m) = |m| is representable as a value of type M. — end
note ]
2
Remarks: If either M or N is not an integer type, or if either is cv bool, the program is ill-formed.
3
Returns: Zero when m and n are both zero. Otherwise, returns the greatest common divisor of |m| and
|n|.
4
Throws: Nothing.
29.8.14
Least common multiple
[numeric.ops.lcm]
template<class M, class N>
constexpr common_type_t<M,N> lcm(M m, N n);
1
Requires: |m| and |n| shall be representable as a value of common_type_t<M, N>. The least common
multiple of |m| and |n| shall be representable as a value of type common_type_t<M,N>.
2
Remarks: If either M or N is not an integer type, or if either is cv bool the program is ill-formed.
3
Returns: Zero when either m or n is zero. Otherwise, returns the least common multiple of |m| and |n|.
4
Throws: Nothing.
29.9
Mathematical functions for floating-point types
[c.math]
29.9.1
Header <cmath> synopsis
[cmath.syn]
namespace std {
using float_t = see below ;
using double_t = see below ;
}
#define HUGE_VAL see below
#define HUGE_VALF see below
#define HUGE_VALL see below
#define INFINITY see below
#define NAN see below
#define FP_INFINITE see below
#define FP_NAN see below
#define FP_NORMAL see below
§ 29.9.1
1016
#define FP_SUBNORMAL see below
#define FP_ZERO see below
#define FP_FAST_FMA see below
#define FP_FAST_FMAF see below
#define FP_FAST_FMAL see below
#define FP_ILOGB0 see below
#define FP_ILOGBNAN see below
#define MATH_ERRNO see below
#define MATH_ERREXCEPT see below
#define math_errhandling see below
namespace std {
float acos(float x);
// see 20.2
double acos(double x);
long double acos(long double x);
// see
20.2
float acosf(float x);
long double acosl(long double x);
float asin(float x);
// see 20.2
double asin(double x);
long double asin(long double x);
// see
20.2
float asinf(float x);
long double asinl(long double x);
float atan(float x);
// see 20.2
double atan(double x);
long double atan(long double x);
// see
20.2
float atanf(float x);
long double atanl(long double x);
float atan2(float y, float x);
// see 20.2
double atan2(double y, double x);
long double atan2(long double y, long double
x);
// see
20.2
float atan2f(float y, float x);
long double atan2l(long double y, long double
x);
float cos(float x);
// see 20.2
double cos(double x);
long double cos(long double x);
// see 20.2
float cosf(float x);
long double cosl(long double x);
float sin(float x);
// see 20.2
double sin(double x);
long double sin(long double x);
// see 20.2
float sinf(float x);
long double sinl(long double x);
float tan(float x);
// see 20.2
double tan(double x);
long double tan(long double x);
// see 20.2
float tanf(float x);
long double tanl(long double x);
float acosh(float x);
// see 20.2
double acosh(double x);
long double acosh(long double x);
// see 20.2
float acoshf(float x);
long double acoshl(long double x);
float asinh(float x);
// see 20.2
double asinh(double x);
long double asinh(long double x);
// see 20.2
§
29.9.1
1017
float asinhf(float x);
long double asinhl(long double x);
float atanh(float x);
// see 20.2
double atanh(double x);
long double atanh(long double x);
// see 20.2
float atanhf(float x);
long double atanhl(long double x);
float cosh(float x);
// see 20.2
double cosh(double x);
long double cosh(long double x);
// see 20.2
float coshf(float x);
long double coshl(long double x);
float sinh(float x);
// see 20.2
double sinh(double x);
long double sinh(long double x);
// see 20.2
float sinhf(float x);
long double sinhl(long double x);
float tanh(float x);
// see 20.2
double tanh(double x);
long double tanh(long double x);
// see 20.2
float tanhf(float x);
long double tanhl(long double x);
float exp(float x);
// see 20.2
double exp(double x);
long double exp(long double x);
// see 20.2
float expf(float x);
long double expl(long double x);
float exp2(float x);
// see 20.2
double exp2(double x);
long double exp2(long double x);
// see 20.2
float exp2f(float x);
long double exp2l(long double x);
float expm1(float x);
// see 20.2
double expm1(double x);
long double expm1(long double x);
// see 20.2
float expm1f(float x);
long double expm1l(long double x);
float frexp(float value, int* exp);
// see 20.2
double frexp(double value, int* exp);
long double frexp(long double value, int* exp);
// see
20.2
float frexpf(float value, int* exp);
long double frexpl(long double value, int* exp);
int ilogb(float x);
// see 20.2
int ilogb(double x);
int ilogb(long double x);
// see 20.2
int ilogbf(float x);
int ilogbl(long double x);
float ldexp(float x, int exp);
// see 20.2
double ldexp(double x, int exp);
long double ldexp(long double x, int exp);
// see 20.2
float ldexpf(float x, int exp);
long double ldexpl(long double x, int exp);
§ 29.9.1
1018
float log(float x);
// see 20.2
double log(double x);
long double log(long double x);
// see 20.2
float logf(float x);
long double logl(long double x);
float log10(float x);
// see 20.2
double log10(double x);
long double log10(long double x);
// see 20.2
float log10f(float x);
long double log10l(long double x);
float log1p(float x);
// see 20.2
double log1p(double x);
long double log1p(long double x);
// see 20.2
float log1pf(float x);
long double log1pl(long double x);
float log2(float x);
// see 20.2
double log2(double x);
long double log2(long double x);
// see 20.2
float log2f(float x);
long double log2l(long double x);
float logb(float x);
// see 20.2
double logb(double x);
long double logb(long double x);
// see 20.2
float logbf(float x);
long double logbl(long double x);
float modf(float value, float* iptr);
// see 20.2
double modf(double value, double* iptr);
long double modf(long double value, long double* iptr);
// see
20.2
float modff(float value, float* iptr);
long double modfl(long double value, long double* iptr);
float scalbn(float x, int n);
// see 20.2
double scalbn(double x, int n);
long double scalbn(long double x, int n);
// see 20.2
float scalbnf(float x, int n);
long double scalbnl(long double x, int n);
float scalbln(float x, long int n);
// see 20.2
double scalbln(double x, long int n);
long double scalbln(long double x, long int n);
// see 20.2
float scalblnf(float x, long int n);
long double scalblnl(long double x, long int n);
float cbrt(float x);
// see 20.2
double cbrt(double x);
long double cbrt(long double x);
// see 20.2
float cbrtf(float x);
long double cbrtl(long double x);
// 29.9.2, absolute values
int abs(int j);
long int abs(long int j);
long long int abs(long long int j);
float abs(float j);
double abs(double j);
long double abs(long double j);
float fabs(float x);
// see 20.2
double fabs(double x);
§
29.9.1
1019
long double fabs(long double x);
// see 20.2
float fabsf(float x);
long double fabsl(long double x);
float hypot(float x, float y);
// see 20.2
double hypot(double x, double y);
long double hypot(long double x, long double y);
// see 20.2
float hypotf(float x, float y);
long double hypotl(long double x, long double y);
// 29.9.3, three-dimensional hypotenuse
float hypot(float x, float y, float z);
double hypot(double x, double y, double z);
long double hypot(long double x, long double y,
long double
z);
float pow(float x, float y);
// see 20.2
double pow(double x, double y);
long double pow(long double x, long double y);
// see
20.2
float powf(float x, float y);
long double powl(long double x, long double y);
float sqrt(float x);
// see 20.2
double sqrt(double x);
long double sqrt(long double x);
// see 20.2
float sqrtf(float x);
long double sqrtl(long double x);
float erf(float x);
// see 20.2
double erf(double x);
long double erf(long double x);
// see 20.2
float erff(float x);
long double erfl(long double x);
float erfc(float x);
// see 20.2
double erfc(double x);
long double erfc(long double x);
// see 20.2
float erfcf(float x);
long double erfcl(long double x);
float lgamma(float x);
// see 20.2
double lgamma(double x);
long double lgamma(long double x);
// see 20.2
float lgammaf(float x);
long double lgammal(long double x);
float tgamma(float x);
// see 20.2
double tgamma(double x);
long double tgamma(long double x);
// see 20.2
float tgammaf(float x);
long double tgammal(long double x);
float ceil(float x);
// see 20.2
double ceil(double x);
long double ceil(long double x);
// see 20.2
float ceilf(float x);
long double ceill(long double x);
float floor(float x);
// see 20.2
double floor(double x);
long double floor(long double x);
// see 20.2
float floorf(float x);
long double floorl(long double x);
§ 29.9.1
1020
float nearbyint(float x);
// see 20.2
double nearbyint(double x);
long double nearbyint(long double x);
// see 20.2
float nearbyintf(float x);
long double nearbyintl(long double x);
float rint(float x);
// see 20.2
double rint(double x);
long double rint(long double x);
// see 20.2
float rintf(float x);
long double rintl(long double x);
long int lrint(float x);
// see 20.2
long int lrint(double x);
long int lrint(long double x);
// see 20.2
long int lrintf(float x);
long int lrintl(long double x);
long long int llrint(float x);
// see 20.2
long long int llrint(double x);
long long int llrint(long double x);
// see 20.2
long long int llrintf(float x);
long long int llrintl(long double x);
float round(float x);
// see 20.2
double round(double x);
long double round(long double x);
// see 20.2
float roundf(float x);
long double roundl(long double x);
long int lround(float x);
// see 20.2
long int lround(double x);
long int lround(long double x);
// see 20.2
long int lroundf(float x);
long int lroundl(long double x);
long long int llround(float x);
// see 20.2
long long int llround(double x);
long long int llround(long double x);
// see 20.2
long long int llroundf(float x);
long long int llroundl(long double x);
float trunc(float x);
// see 20.2
double trunc(double x);
long double trunc(long double x);
// see 20.2
float truncf(float x);
long double truncl(long double x);
float fmod(float x, float y);
// see 20.2
double fmod(double x, double y);
long double fmod(long double x, long double y);
// see
20.2
float fmodf(float x, float y);
long double fmodl(long double x, long double y);
float remainder(float x, float y);
// see 20.2
double remainder(double x, double y);
long double remainder(long double x, long double y);
// see
20.2
float remainderf(float x, float y);
long double remainderl(long double x, long double y);
float remquo(float x, float y, int* quo);
// see 20.2
double remquo(double x, double y, int* quo);
long double remquo(long double x, long double y, int* quo);
// see
20.2
float remquof(float x, float y, int* quo);
§
29.9.1
1021
long double remquol(long double x, long double y, int* quo);
float copysign(float x, float y);
// see 20.2
double copysign(double x, double y);
long double copysign(long double x, long double y);
// see 20.2
float copysignf(float x, float y);
long double copysignl(long double x, long double y);
double nan(const char* tagp);
float nanf(const char* tagp);
long double nanl(const char* tagp);
float nextafter(float x, float y);
// see 20.2
double nextafter(double x, double y);
long double nextafter(long double x, long double y);
// see 20.2
float nextafterf(float x, float y);
long double nextafterl(long double x, long double y);
float nexttoward(float x, long double y);
// see 20.2
double nexttoward(double x, long double y);
long double nexttoward(long double x, long double y);
// see 20.2
float nexttowardf(float x, long double y);
long double nexttowardl(long double x, long double y);
float fdim(float x, float y);
// see 20.2
double fdim(double x, double y);
long double fdim(long double x, long double y);
// see 20.2
float fdimf(float x, float y);
long double fdiml(long double x, long double y);
float fmax(float x, float y);
// see 20.2
double fmax(double x, double y);
long double fmax(long double x, long double y);
// see 20.2
float fmaxf(float x, float y);
long double fmaxl(long double x, long double y);
float fmin(float x, float y);
// see 20.2
double fmin(double x, double y);
long double fmin(long double x, long double y);
// see 20.2
float fminf(float x, float y);
long double fminl(long double x, long double y);
float fma(float x, float y, float z);
// see 20.2
double fma(double x, double y, double z);
long double fma(long double x, long double y, long double z);
// see
20.2
float fmaf(float x, float y, float z);
long double fmal(long double x, long double y, long double z);
// 29.9.4, classification / comparison functions
int fpclassify(float x);
int fpclassify(double x);
int fpclassify(long double x);
int isfinite(float x);
int isfinite(double x);
int isfinite(long double x);
int isinf(float x);
int isinf(double x);
int isinf(long double x);
int isnan(float x);
int isnan(double x);
int isnan(long double x);
§
29.9.1
1022
int
isnormal(float x);
int
isnormal(double x);
int
isnormal(long double x);
int
signbit(float x);
int
signbit(double x);
int
signbit(long double x);
int
isgreater(float x, float y);
int
isgreater(double x, double y);
int
isgreater(long double x, long double y);
int
isgreaterequal(float x, float y);
int
isgreaterequal(double x, double y);
int
isgreaterequal(long double x, long double y);
int
isless(float x, float y);
int
isless(double x, double y);
int
isless(long double x, long double y);
int
islessequal(float x, float y);
int
islessequal(double x, double y);
int
islessequal(long double x, long double y);
int
islessgreater(float x, float y);
int
islessgreater(double x, double y);
int
islessgreater(long double x, long double y);
int
isunordered(float x, float y);
int
isunordered(double x, double y);
int
isunordered(long double x, long double y);
// 29.9.5, mathematical special functions
// 29.9.5.1, associated Laguerre polynomials
double
assoc_laguerre(unsigned n, unsigned m,
double
x);
float
assoc_laguerref(unsigned n, unsigned m, float
x);
long double
assoc_laguerrel(unsigned n, unsigned m, long double
x);
// 29.9.5.2, associated Legendre functions
double
assoc_legendre(unsigned l, unsigned m, double x);
float
assoc_legendref(unsigned l, unsigned m, float x);
long double
assoc_legendrel(unsigned l, unsigned m, long double
x);
// 29.9.5.3, beta function
double
beta(double x, double y);
float
betaf(float x, float y);
long double
betal(long double x, long double y);
// 29.9.5.4, complete elliptic integral of the first kind
double
comp_ellint_1(double k);
float
comp_ellint_1f(float k);
long double
comp_ellint_1l(long double k);
// 29.9.5.5, complete elliptic integral of the second kind
double
comp_ellint_2(double k);
float
comp_ellint_2f(float k);
long double
comp_ellint_2l(long double k);
// 29.9.5.6, complete elliptic integral of the third kind
double
comp_ellint_3(double k, double nu);
float
comp_ellint_3f(float k, float nu);
long double
comp_ellint_3l(long double k, long double nu);
§
29.9.1
1023
// 29.9.5.7, regular modified cylindrical Bessel functions
double
cyl_bessel_i(double nu, double x);
float
cyl_bessel_if(float nu, float x);
long double
cyl_bessel_il(long double nu, long double x);
// 29.9.5.8, cylindrical Bessel functions of the first kind
double
cyl_bessel_j(double nu, double x);
float
cyl_bessel_jf(float nu, float x);
long double
cyl_bessel_jl(long double nu, long double x);
// 29.9.5.9, irregular modified cylindrical Bessel functions
double
cyl_bessel_k(double nu, double x);
float
cyl_bessel_kf(float nu, float x);
long double
cyl_bessel_kl(long double nu, long double x);
// 29.9.5.10, cylindrical Neumann functions;
// cylindrical Bessel functions of the second kind
double
cyl_neumann(double nu, double x);
float
cyl_neumannf(float nu, float x);
long double
cyl_neumannl(long double nu, long double x);
// 29.9.5.11, incomplete elliptic integral of the first kind
double
ellint_1(double k, double phi);
float
ellint_1f(float k, float phi);
long double
ellint_1l(long double k, long double phi);
// 29.9.5.12, incomplete elliptic integral of the second kind
double
ellint_2(double k, double phi);
float
ellint_2f(float k, float phi);
long double
ellint_2l(long double k, long double phi);
// 29.9.5.13, incomplete elliptic integral of the third kind
double
ellint_3(double k, double nu, double phi);
float
ellint_3f(float k, float nu, float phi);
long double
ellint_3l(long double k, long double nu,
long
double
phi);
// 29.9.5.14, exponential integral
double
expint(double x);
float
expintf(float x);
long double
expintl(long double x);
// 29.9.5.15, Hermite polynomials
double
hermite(unsigned n, double x);
float
hermitef(unsigned n, float x);
long double
hermitel(unsigned n, long double x);
// 29.9.5.16, Laguerre polynomials
double
laguerre(unsigned n, double x);
float
laguerref(unsigned n, float x);
long double
laguerrel(unsigned n, long double x);
// 29.9.5.17, Legendre polynomials
double
legendre(unsigned l, double x);
float
legendref(unsigned l, float x);
long double
legendrel(unsigned l, long double x);
// 29.9.5.18, Riemann zeta function
double
riemann_zeta(double x);
float
riemann_zetaf(float x);
long double
riemann_zetal(long double x);
// 29.9.5.19, spherical Bessel functions of the first kind
double
sph_bessel(unsigned n, double x);
float
sph_besself(unsigned n, float x);
§
29.9.1
1024
long double sph_bessell(unsigned n, long double x);
// 29.9.5.20, spherical associated Legendre functions
double
sph_legendre(unsigned l, unsigned m, double theta);
float
sph_legendref(unsigned l, unsigned m, float theta);
long double
sph_legendrel(unsigned l, unsigned m, long double theta);
// 29.9.5.21, spherical Neumann functions;
// spherical Bessel functions of the second kind
double
sph_neumann(unsigned n, double x);
float
sph_neumannf(unsigned n, float x);
long double
sph_neumannl(unsigned n, long double x);
}
1
The contents and meaning of the header <cmath> are the same as the C standard library header <math.h>,
with the addition of a three-dimensional hypotenuse function (29.9.3) and the mathematical special functions
described in 29.9.5. [ Note: Several functions have additional overloads in this document, but they have the
same behavior as in the C standard library (20.2).
— end note ]
2
For each set of overloaded functions within <cmath>, with the exception of abs, there shall be additional
overloads sufficient to ensure:
1. If any argument of arithmetic type corresponding to a double parameter has type long double, then
all arguments of arithmetic type (6.7.1) corresponding to double parameters are effectively cast to
long double.
2. Otherwise, if any argument of arithmetic type corresponding to a double parameter has type double
or an integer type, then all arguments of arithmetic type corresponding to double parameters are
effectively cast to double.
3. Otherwise, all arguments of arithmetic type corresponding to double parameters have type float.
[ Note: abs is exempted from these rules in order to stay compatible with C. — end note ]
See also: ISO C 7.12
29.9.2
Absolute values
[c.math.abs]
1
[ Note: The headers <cstdlib> (21.2.2) and <cmath> (29.9.1) declare the functions described in this subclause.
— end note ]
int abs(int j);
long int abs(long int j);
long long int abs(long long int j);
float abs(float j);
double abs(double j);
long double abs(long double j);
2
Effects: The abs functions have the semantics specified in the C standard library for the functions abs,
labs, llabs, fabsf, fabs, and fabsl.
3
Remarks: If abs() is called with an argument of type X for which is_unsigned_v<X> is true and if X
cannot be converted to int by integral promotion (7.6), the program is ill-formed. [ Note: Arguments
that can be promoted to int are permitted for compatibility with C. — end note ]
See also: ISO C 7.12.7.2, 7.22.6.1
29.9.3
Three-dimensional hypotenuse
[c.math.hypot3]
float hypot(float x, float y, float z);
double hypot(double x, double y, double z);
long double hypot(long double x, long double y, long double z);
√
1
Returns:
x2 + y2 + z2.
29.9.4
Classification / comparison functions
[c.math.fpclass]
1
The classification / comparison functions behave the same as the C macros with the corresponding names
defined in the C standard library. Each function is overloaded for the three floating-point types.
See also: ISO C 7.12.3, 7.12.4
§ 29.9.4
1025
29.9.5
Mathematical special functions
[sf.cmath]
1
If any argument value to any of the functions specified in this subclause is a NaN (Not a Number), the
function shall return a NaN but it shall not report a domain error. Otherwise, the function shall report a
domain error for just those argument values for which:
(1.1)
—
the function description’s Returns: clause explicitly specifies a domain and those argument values fall
outside the specified domain, or
(1.2)
—
the corresponding mathematical function value has a nonzero imaginary component, or
(1.3)
—
the corresponding mathematical function is not mathematically defined.289
2
Unless otherwise specified, each function is defined for all finite values, for negative infinity, and for positive
infinity.
29.9.5.1
Associated Laguerre polynomials
[sf.cmath.assoc_laguerre]
double
assoc_laguerre(unsigned n, unsigned m, double x);
float
assoc_laguerref(unsigned n, unsigned m, float x);
long double
assoc_laguerrel(unsigned n, unsigned m, long double x);
1
Effects: These functions compute the associated Laguerre polynomials of their respective arguments n,
m, and x.
2
Returns:
Lm
n (x)=(−1)m dm
Ln+m(x), for x ≥ 0
dxm
where n is n, m is m, and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if n >= 128 or if m >=
128.
29.9.5.2
Associated Legendre functions
[sf.cmath.assoc_legendre]
double
assoc_legendre(unsigned l, unsigned m, double x);
float
assoc_legendref(unsigned l, unsigned m, float x);
long double
assoc_legendrel(unsigned l, unsigned m, long double x);
1
Effects: These functions compute the associated Legendre functions of their respective arguments l, m,
and x.
2
Returns:
dm
Pmℓ
(x) = (1 − x2)m/2
Pℓ(x), for |x| ≤ 1
dxm
where l is l, m is m, and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if l >= 128.
29.9.5.3
Beta function
[sf.cmath.beta]
double
beta(double x, double y);
float
betaf(float x, float y);
long double
betal(long double x, long double y);
1
Effects: These functions compute the beta function of their respective arguments x and y.
2
Returns:
Γ(x) Γ(y)
B(x, y) =
,
for x > 0, y > 0
Γ(x + y)
where x is x and y is y.
289) A mathematical function is mathematically defined for a given set of argument values (a) if it is explicitly defined for that
set of argument values, or (b) if its limiting value exists and does not depend on the direction of approach.
§ 29.9.5.3
1026
29.9.5.4
Complete elliptic integral of the first kind
[sf.cmath.comp_ellint_1]
double
comp_ellint_1(double k);
float
comp_ellint_1f(float k);
long double
comp_ellint_1l(long double k);
1
Effects: These functions compute the complete elliptic integral of the first kind of their respective
arguments k.
2
Returns:
K(k) = F(k, π/2), for |k| ≤ 1
where k is k.
3
See also 29.9.5.11.
29.9.5.5
Complete elliptic integral of the second kind
[sf.cmath.comp_ellint_2]
double
comp_ellint_2(double k);
float
comp_ellint_2f(float k);
long double
comp_ellint_2l(long double k);
1
Effects: These functions compute the complete elliptic integral of the second kind of their respective
arguments k.
2
Returns:
E(k) = E(k, π/2), for |k| ≤ 1
where k is k.
3
See also 29.9.5.12.
29.9.5.6
Complete elliptic integral of the third kind
[sf.cmath.comp_ellint_3]
double
comp_ellint_3(double k, double nu);
float
comp_ellint_3f(float k, float nu);
long double
comp_ellint_3l(long double k, long double nu);
1
Effects: These functions compute the complete elliptic integral of the third kind of their respective
arguments k and nu.
2
Returns:
Π(ν, k) = Π(ν, k, π/2), for |k| ≤ 1
where k is k and ν is nu.
3
See also 29.9.5.13.
29.9.5.7
Regular modified cylindrical Bessel functions
[sf.cmath.cyl_bessel_i]
double
cyl_bessel_i(double nu, double x);
float
cyl_bessel_if(float nu, float x);
long double
cyl_bessel_il(long double nu, long double x);
1
Effects: These functions compute the regular modified cylindrical Bessel functions of their respective
arguments nu and x.
2
Returns:
∑
(x/2)ν+2k
Iν(x) = i−νJν(ix) =
k! Γ(ν + k + 1),forx≥0
k=0
where ν is nu and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if nu >= 128.
4
See also 29.9.5.8.
§ 29.9.5.7
1027
29.9.5.8
Cylindrical Bessel functions of the first kind
[sf.cmath.cyl_bessel_j]
double
cyl_bessel_j(double nu, double x);
float
cyl_bessel_jf(float nu, float x);
long double
cyl_bessel_jl(long double nu, long double x);
1
Effects: These functions compute the cylindrical Bessel functions of the first kind of their respective
arguments nu and x.
2
Returns:
∑
(−1)k (x/2)ν+2k
Jν(x) =
,
for x ≥ 0
k! Γ(ν + k + 1)
k=0
where ν is nu and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if nu >= 128.
29.9.5.9
Irregular modified cylindrical Bessel functions
[sf.cmath.cyl_bessel_k]
double
cyl_bessel_k(double nu, double x);
float
cyl_bessel_kf(float nu, float x);
long double
cyl_bessel_kl(long double nu, long double x);
1
Effects: These functions compute the irregular modified cylindrical Bessel functions of their respective
arguments nu and x.
2
Returns:
π I−ν(x) − Iν(x)
,
for x ≥ 0 and non-integral ν
2
sin νπ
Kν(x) = (π/2)iν+1(Jν(ix) + iNν(ix)) =
π
,
for x ≥ 0 and integral ν
µ→ν
sin µπ
where ν is nu and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if nu >= 128.
4
See also 29.9.5.7, 29.9.5.8, 29.9.5.10.
29.9.5.10
Cylindrical Neumann functions
[sf.cmath.cyl_neumann]
double
cyl_neumann(double nu, double x);
float
cyl_neumannf(float nu, float x);
long double
cyl_neumannl(long double nu, long double x);
1
Effects: These functions compute the cylindrical Neumann functions, also known as the cylindrical
Bessel functions of the second kind, of their respective arguments nu and x.
2
Returns:
Jν(x)cosνπ − J−ν(x)
,
for x ≥ 0 and non-integral ν
sin νπ
Nν(x) =
Jµ(x)cosµπ − J−µ(x)
lim
,
for x ≥ 0 and integral ν
µ→ν
sin µπ
where ν is nu and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if nu >= 128.
4
See also 29.9.5.8.
29.9.5.11
Incomplete elliptic integral of the first kind
[sf.cmath.ellint_1]
double
ellint_1(double k, double phi);
float
ellint_1f(float k, float phi);
long double
ellint_1l(long double k, long double phi);
1
Effects: These functions compute the incomplete elliptic integral of the first kind of their respective
arguments k and phi (phi measured in radians).
§ 29.9.5.11
1028
2
Returns:
∫ φ
dθ
F(k, φ) =
√
,
for |k| ≤ 1
0
1 − k2 sin2 θ
where k is k and φ is phi.
29.9.5.12
Incomplete elliptic integral of the second kind
[sf.cmath.ellint_2]
double
ellint_2(double k, double phi);
float
ellint_2f(float k, float phi);
long double
ellint_2l(long double k, long double phi);
1
Effects: These functions compute the incomplete elliptic integral of the second kind of their respective
arguments k and phi (phi measured in radians).
2
Returns:
∫ φ
√
E(k, φ) =
1 − k2 sin2 θdθ, for |k| ≤ 1
0
where k is k and φ is phi.
29.9.5.13
Incomplete elliptic integral of the third kind
[sf.cmath.ellint_3]
double
ellint_3(double k, double nu, double phi);
float
ellint_3f(float k, float nu, float phi);
long double
ellint_3l(long double k, long double nu, long double phi);
1
Effects: These functions compute the incomplete elliptic integral of the third kind of their respective
arguments k, nu, and phi (phi measured in radians).
2
Returns:
∫ φ
dθ
Π(ν, k, φ) =
√
,
for |k| ≤ 1
0
(1 − ν sin2 θ)
1 − k2 sin2 θ
where ν is nu, k is k, and φ is phi.
29.9.5.14
Exponential integral
[sf.cmath.expint]
double
expint(double x);
float
expintf(float x);
long double
expintl(long double x);
1
Effects: These functions compute the exponential integral of their respective arguments x.
2
Returns:
∫ ∞
e−t
Ei(x) = −
dt
−x t
where x is x.
29.9.5.15
Hermite polynomials
[sf.cmath.hermite]
double
hermite(unsigned n, double x);
float
hermitef(unsigned n, float x);
long double
hermitel(unsigned n, long double x);
1
Effects: These functions compute the Hermite polynomials of their respective arguments n and x.
2
Returns:
Hn(x) = (−1)nex2 dn
e−x2
dxn
where n is n and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if n >= 128.
§ 29.9.5.15
1029
29.9.5.16
Laguerre polynomials
[sf.cmath.laguerre]
double
laguerre(unsigned n, double x);
float
laguerref(unsigned n, float x);
long double
laguerrel(unsigned n, long double x);
1
Effects: These functions compute the Laguerre polynomials of their respective arguments n and x.
2
Returns:
ex dn
Ln(x) =
(xne−x), for x ≥ 0
n! dxn
where n is n and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if n >= 128.
29.9.5.17
Legendre polynomials
[sf.cmath.legendre]
double
legendre(unsigned l, double x);
float
legendref(unsigned l, float x);
long double
legendrel(unsigned l, long double x);
1
Effects: These functions compute the Legendre polynomials of their respective arguments l and x.
2
Returns:
ℓ
1
d
Pℓ(x) =
(x2 − 1)ℓ, for |x| ≤ 1
2ℓ ℓ! dxℓ
where l is l and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if l >= 128.
29.9.5.18
Riemann zeta function
[sf.cmath.riemann_zeta]
double
riemann_zeta(double x);
float
riemann_zetaf(float x);
long double
riemann_zetal(long double x);
1
Effects: These functions compute the Riemann zeta function of their respective arguments x.
2
Returns:
∑
k−x,
for x > 1
k=1
∑
ζ(x) =
1
(−1)k−1k−x,
for 0 ≤ x ≤ 1
1−21−x
k=1
2xπx−1 sin(πx
2 )Γ(1−x)ζ(1−x),forx<0
where x is x.
29.9.5.19
Spherical Bessel functions of the first kind
[sf.cmath.sph_bessel]
double
sph_bessel(unsigned n, double x);
float
sph_besself(unsigned n, float x);
long double
sph_bessell(unsigned n, long double x);
1
Effects: These functions compute the spherical Bessel functions of the first kind of their respective
arguments n and x.
2
Returns:
jn(x) = (π/2x)1/2Jn+1/2(x), for x ≥ 0
where n is n and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if n >= 128.
4
See also 29.9.5.8.
§ 29.9.5.19
1030
29.9.5.20
Spherical associated Legendre functions
[sf.cmath.sph_legendre]
double
sph_legendre(unsigned l, unsigned m, double theta);
float
sph_legendref(unsigned l, unsigned m, float theta);
long double
sph_legendrel(unsigned l, unsigned m, long double theta);
1
Effects: These functions compute the spherical associated Legendre functions of their respective
arguments l, m, and theta (theta measured in radians).
2
Returns:
Ymℓ
(θ, 0)
where
1/2
[ (2ℓ + 1) (ℓ − m)!]
Ymℓ
(θ, φ) = (−1)m
Pmℓ
(cos θ)eimφ, for |m| ≤ ℓ
4π
(ℓ + m)!
and l is l, m is m, and θ is theta.
3
Remarks: The effect of calling each of these functions is implementation-defined if l >= 128.
4
See also 29.9.5.2.
29.9.5.21
Spherical Neumann functions
[sf.cmath.sph_neumann]
double
sph_neumann(unsigned n, double x);
float
sph_neumannf(unsigned n, float x);
long double
sph_neumannl(unsigned n, long double x);
1
Effects: These functions compute the spherical Neumann functions, also known as the spherical Bessel
functions of the second kind, of their respective arguments n and x.
2
Returns:
nn(x) = (π/2x)1/2Nn+1/2(x), for x ≥ 0
where n is n and x is x.
3
Remarks: The effect of calling each of these functions is implementation-defined if n >= 128.
4
See also 29.9.5.10.
§ 29.9.5.21
1031
30
Input/output library
[input.output]
30.1
General
[input.output.general]
1
This Clause describes components that C++ programs may use to perform input/output operations.
2
The following subclauses describe requirements for stream parameters, and components for forward declara-
tions of iostreams, predefined iostreams objects, base iostreams classes, stream buffering, stream formatting
and manipulators, string streams, and file streams, as summarized in Table 106.
Table 106 — Input/output library summary
Subclause
Header(s)
30.2
Requirements
30.3
Forward declarations
<iosfwd>
30.4
Standard iostream objects
<iostream>
30.5
Iostreams base classes
<ios>
30.6
Stream buffers
<streambuf>
30.7
Formatting and manipulators
<istream>
<ostream>
<iomanip>
30.8
String streams
<sstream>
30.9
File streams
<fstream>
30.10
Synchronized output streams
<syncstream>
30.11
File systems
<filesystem>
30.12
C library files
<cstdio>
<cinttypes>
3
Figure 7 illustrates relationships among various types described in this clause. A line from A to B indicates
that A is an alias (e.g., a typedef) for B or that A is defined in terms of B.
char_traits<char>
char_traits<w char_t>
char_traits<char>
char_traits<w char_t>
streamsize
::pos_type
::pos_type
::off_type
::off_type
iostreams.limits.pos
iostreams.limits.pos
iostreams.limits.pos iostreams.limits.pos
stream.types
signed integer type
streampos
w streampos
streamoff
represents characters xfered
or buffer sizes
iostream.forw ard iostream.forw ard
stream.types
signed integer type
fpos<mbstate_t>
sufficient for
O/S maximum file size
Figure 7 — Stream position, offset, and size types [non-normative]
30.2
Iostreams requirements
[iostreams.requirements]
30.2.1
Imbue limitations
[iostream.limits.imbue]
1
No function described in Clause 30 except for ios_base::imbue and basic_filebuf::pubimbue causes any
instance of basic_ios::imbue or basic_streambuf::imbue to be called. If any user function called from a
function declared in Clause 30 or as an overriding virtual function of any class declared in Clause 30 calls
imbue, the behavior is undefined.
§ 30.2.1
1032
30.2.2
Positioning type limitations
[iostreams.limits.pos]
1
The classes of Clause 30 with template arguments charT and traits behave as described if traits::pos_-
type and traits::off_type are streampos and streamoff respectively. Except as noted explicitly below,
their behavior when traits::pos_type and traits::off_type are other types is implementation-defined.
2
In the classes of Clause 30, a template parameter with name charT represents a member of the set of
types containing char, wchar_t, and any other implementation-defined character types that satisfy the
requirements for a character on which any of the iostream components can be instantiated.
30.2.3
Thread safety
[iostreams.threadsafety]
1
Concurrent access to a stream object (30.8, 30.9), stream buffer object (30.6), or C Library stream (30.12) by
multiple threads may result in a data race (6.8.2) unless otherwise specified (30.4). [ Note: Data races result
in undefined behavior (6.8.2).
— end note ]
2
If one thread makes a library call a that writes a value to a stream and, as a result, another thread reads this
value from the stream through a library call b such that this does not result in a data race, then a’s write
synchronizes with b’s read.
30.3
Forward declarations
[iostream.forward]
30.3.1
Header <iosfwd> synopsis
[iosfwd.syn]
namespace std {
template<class charT> class char_traits;
template<> class char_traits<char>;
template<> class char_traits<char16_t>;
template<> class char_traits<char32_t>;
template<> class char_traits<wchar_t>;
template<class T> class allocator;
template<class charT, class traits = char_traits<charT>>
class basic_ios;
template<class charT, class traits = char_traits<charT>>
class basic_streambuf;
template<class charT, class traits = char_traits<charT>>
class basic_istream;
template<class charT, class traits = char_traits<charT>>
class basic_ostream;
template<class charT, class traits = char_traits<charT>>
class basic_iostream;
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<charT>>
class basic_stringbuf;
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<charT>>
class basic_istringstream;
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<charT>>
class basic_ostringstream;
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<charT>>
class basic_stringstream;
template<class charT, class traits = char_traits<charT>>
class basic_filebuf;
template<class charT, class traits = char_traits<charT>>
class basic_ifstream;
template<class charT, class traits = char_traits<charT>>
class basic_ofstream;
template<class charT, class traits = char_traits<charT>>
class basic_fstream;
§ 30.3.1
1033
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<charT>>
class basic_syncbuf;
template<class charT, class traits = char_traits<charT>,
class Allocator = allocator<charT>>
class basic_osyncstream;
template<class charT, class traits = char_traits<charT>>
class istreambuf_iterator;
template<class charT, class traits = char_traits<charT>>
class ostreambuf_iterator;
using
ios
= basic_ios<char>;
using
wios = basic_ios<wchar_t>;
using
streambuf = basic_streambuf<char>;
using
istream
= basic_istream<char>;
using
ostream
= basic_ostream<char>;
using
iostream
= basic_iostream<char>;
using
stringbuf
= basic_stringbuf<char>;
using
istringstream = basic_istringstream<char>;
using
ostringstream = basic_ostringstream<char>;
using
stringstream
= basic_stringstream<char>;
using
filebuf
= basic_filebuf<char>;
using
ifstream = basic_ifstream<char>;
using
ofstream = basic_ofstream<char>;
using
fstream
= basic_fstream<char>;
using
syncbuf = basic_syncbuf<char>;
using
osyncstream = basic_osyncstream<char>;
using
wstreambuf = basic_streambuf<wchar_t>;
using
wistream
= basic_istream<wchar_t>;
using
wostream
= basic_ostream<wchar_t>;
using
wiostream
= basic_iostream<wchar_t>;
using
wstringbuf
= basic_stringbuf<wchar_t>;
using
wistringstream = basic_istringstream<wchar_t>;
using
wostringstream = basic_ostringstream<wchar_t>;
using
wstringstream
= basic_stringstream<wchar_t>;
using
wfilebuf
= basic_filebuf<wchar_t>;
using
wifstream = basic_ifstream<wchar_t>;
using
wofstream = basic_ofstream<wchar_t>;
using
wfstream
= basic_fstream<wchar_t>;
using
wsyncbuf = basic_syncbuf<wchar_t>;
using
wosyncstream = basic_osyncstream<wchar_t>;
template<class state> class fpos;
using streampos
= fpos<char_traits<char>::state_type>;
using wstreampos = fpos<char_traits<wchar_t>::state_type>;
}
1
Default template arguments are described as appearing both in <iosfwd> and in the synopsis of other headers
but it is well-formed to include both <iosfwd> and one or more of the other headers.290
290) It is the implementation’s responsibility to implement headers so that including <iosfwd> and other headers does not
violate the rules about multiple occurrences of default arguments.
§ 30.3.1
1034
30.3.2
Overview
[iostream.forward.overview]
1
The class template specialization basic_ios<charT, traits> serves as a virtual base class for the class
templates basic_istream, basic_ostream, and class templates derived from them. basic_iostream is a
class template derived from both basic_istream<charT, traits> and basic_ostream<charT, traits>.
2
The class template specialization basic_streambuf<charT, traits> serves as a base class for class templates
basic_stringbuf and basic_filebuf.
3
The class template specialization basic_istream<charT, traits> serves as a base class for class templates
basic_istringstream and basic_ifstream.
4
The class template specialization basic_ostream<charT, traits> serves as a base class for class templates
basic_ostringstream and basic_ofstream.
5
The class template specialization basic_iostream<charT, traits> serves as a base class for class templates
basic_stringstream and basic_fstream.
6
Other typedef-names define instances of class templates specialized for char or wchar_t types.
7
Specializations of the class template fpos are used for specifying file position information.
8
The types streampos and wstreampos are used for positioning streams specialized on char and wchar_t
respectively.
9
[ Note: This synopsis suggests a circularity between streampos and char_traits<char>. An implementation
can avoid this circularity by substituting equivalent types. One way to do this might be
template<class stateT> class fpos { ... };
// depends on nothing
using _STATE = ... ;
// implementation private declaration of stateT
using streampos = fpos<_STATE>;
template<> struct char_traits<char> {
using pos_type = streampos;
}
— end note ]
30.4
Standard iostream objects
[iostream.objects]
30.4.1
Header <iostream> synopsis
[iostream.syn]
#include <ios>
// see 30.5.1
#include <streambuf>
// see 30.6.1
#include <istream>
// see 30.7.1
#include <ostream>
// see 30.7.2
namespace std {
extern istream cin;
extern ostream cout;
extern ostream cerr;
extern ostream clog;
extern wistream wcin;
extern wostream wcout;
extern wostream wcerr;
extern wostream wclog;
}
30.4.2
Overview
[iostream.objects.overview]
1
In this Clause, the type name FILE refers to the type FILE declared in <cstdio> (30.12.1).
2
The header <iostream> declares objects that associate objects with the standard C streams provided for by
the functions declared in <cstdio> (30.12), and includes all the headers necessary to use these objects.
3
The objects are constructed and the associations are established at some time prior to or during the first
time an object of class ios_base::Init is constructed, and in any case before the body of main (6.8.3.1)
§ 30.4.2
1035
begins execution.291 The objects are not destroyed during program execution.292 The results of including
<iostream> in a translation unit shall be as if <iostream> defined an instance of ios_base::Init with
static storage duration.
4
Mixing operations on corresponding wide- and narrow-character streams follows the same semantics as mixing
such operations on FILEs, as specified in the C standard library.
5
Concurrent access to a synchronized (30.5.3.4) standard iostream object’s formatted and unformatted
input (30.7.4.1) and output (30.7.5.1) functions or a standard C stream by multiple threads shall not result
in a data race (6.8.2). [Note: Users must still synchronize concurrent use of these objects and streams by
multiple threads if they wish to avoid interleaved characters.
— end note ]
See also: ISO C 7.21.2
30.4.3
Narrow stream objects
[narrow.stream.objects]
istream cin;
1
The object cin controls input from a stream buffer associated with the object stdin, declared in
<cstdio> (30.12.1).
2
After the object cin is initialized, cin.tie() returns &cout. Its state is otherwise the same as required
for basic_ios<char>::init (30.5.5.2).
ostream cout;
3
The object cout controls output to a stream buffer associated with the object stdout, declared in
<cstdio> (30.12.1).
ostream cerr;
4
The object cerr controls output to a stream buffer associated with the object stderr, declared in
<cstdio> (30.12.1).
5
After the object cerr is initialized, cerr.flags() & unitbuf is nonzero and cerr.tie() returns
&cout. Its state is otherwise the same as required for basic_ios<char>::init (30.5.5.2).
ostream clog;
6
The object clog controls output to a stream buffer associated with the object stderr, declared in
<cstdio> (30.12.1).
30.4.4
Wide stream objects
[wide.stream.objects]
wistream wcin;
1
The object wcin controls input from a stream buffer associated with the object stdin, declared in
<cstdio> (30.12.1).
2
After the object wcin is initialized, wcin.tie() returns &wcout. Its state is otherwise the same as
required for basic_ios<wchar_t>::init (30.5.5.2).
wostream wcout;
3
The object wcout controls output to a stream buffer associated with the object stdout, declared in
<cstdio> (30.12.1).
wostream wcerr;
4
The object wcerr controls output to a stream buffer associated with the object stderr, declared in
<cstdio> (30.12.1).
5
After the object wcerr is initialized, wcerr.flags() & unitbuf is nonzero and wcerr.tie() returns
&wcout. Its state is otherwise the same as required for basic_ios<wchar_t>::init (30.5.5.2).
wostream wclog;
6
The object wclog controls output to a stream buffer associated with the object stderr, declared in
<cstdio> (30.12.1).
291) If it is possible for them to do so, implementations should initialize the objects earlier than required.
292) Constructors and destructors for static objects can access these objects to read input from stdin or write output to stdout
or stderr.
§ 30.4.4
1036
30.5
Iostreams base classes
[iostreams.base]
30.5.1
Header <ios> synopsis
[ios.syn]
#include <iosfwd>
// see 30.3.1
namespace std {
using streamoff
= implementation-defined ;
using streamsize = implementation-defined ;
template<class stateT> class fpos;
class ios_base;
template<class charT, class traits = char_traits<charT>>
class basic_ios;
// 30.5.6, manipulators
ios_base& boolalpha
(ios_base&
str);
ios_base& noboolalpha(ios_base&
str);
ios_base& showbase
(ios_base&
str);
ios_base& noshowbase (ios_base&
str);
ios_base& showpoint
(ios_base&
str);
ios_base& noshowpoint(ios_base&
str);
ios_base& showpos
(ios_base&
str);
ios_base& noshowpos
(ios_base&
str);
ios_base& skipws
(ios_base&
str);
ios_base& noskipws
(ios_base&
str);
ios_base& uppercase
(ios_base&
str);
ios_base& nouppercase(ios_base&
str);
ios_base& unitbuf
(ios_base&
str);
ios_base& nounitbuf
(ios_base&
str);
// 30.5.6.2, adjustfield
ios_base& internal
(ios_base&
str);
ios_base& left
(ios_base&
str);
ios_base& right
(ios_base&
str);
// 30.5.6.3, basefield
ios_base& dec
(ios_base&
str);
ios_base& hex
(ios_base&
str);
ios_base& oct
(ios_base&
str);
// 30.5.6.4, floatfield
ios_base& fixed
(ios_base&
str);
ios_base& scientific (ios_base&
str);
ios_base& hexfloat
(ios_base&
str);
ios_base& defaultfloat(ios_base& str);
// 30.5.6.5, error reporting
enum class io_errc {
stream = 1
};
template<> struct is_error_code_enum<io_errc>
:
public
true_type
{
};
error_code make_error_code(io_errc e) noexcept;
error_condition make_error_condition(io_errc e)
noexcept;
const error_category& iostream_category() noexcept;
}
§ 30.5.1
1037
30.5.2
Types
[stream.types]
using streamoff = implementation-defined ;
1
The type streamoff is a synonym for one of the signed basic integral types of sufficient size to represent
the maximum possible file size for the operating system.293
using streamsize = implementation-defined ;
2
The type streamsize is a synonym for one of the signed basic integral types. It is used to represent
the number of characters transferred in an I/O operation, or the size of I/O buffers.294
30.5.3
Class ios_base
[ios.base]
namespace std {
class ios_base {
public:
class failure; // see below
// 30.5.3.1.2, fmtflags
using fmtflags = T1 ;
static constexpr fmtflags boolalpha = unspecified ;
static constexpr fmtflags dec = unspecified ;
static constexpr fmtflags fixed = unspecified ;
static constexpr fmtflags hex = unspecified ;
static constexpr fmtflags internal = unspecified ;
static constexpr fmtflags left = unspecified ;
static constexpr fmtflags oct = unspecified ;
static constexpr fmtflags right = unspecified ;
static constexpr fmtflags scientific = unspecified ;
static constexpr fmtflags showbase = unspecified ;
static constexpr fmtflags showpoint = unspecified ;
static constexpr fmtflags showpos = unspecified ;
static constexpr fmtflags skipws = unspecified ;
static constexpr fmtflags unitbuf = unspecified ;
static constexpr fmtflags uppercase = unspecified ;
static constexpr fmtflags adjustfield = see below ;
static constexpr fmtflags basefield = see below ;
static constexpr fmtflags floatfield = see below ;
// 30.5.3.1.3, iostate
using iostate = T2 ;
static constexpr iostate badbit = unspecified ;
static constexpr iostate eofbit = unspecified ;
static constexpr iostate failbit = unspecified ;
static constexpr iostate goodbit = see below ;
// 30.5.3.1.4, openmode
using openmode = T3 ;
static constexpr openmode app = unspecified ;
static constexpr openmode ate = unspecified ;
static constexpr openmode binary = unspecified ;
static constexpr openmode in = unspecified ;
static constexpr openmode out = unspecified ;
static constexpr openmode trunc = unspecified ;
// 30.5.3.1.5, seekdir
using seekdir = T4 ;
static constexpr seekdir beg = unspecified ;
static constexpr seekdir cur = unspecified ;
static constexpr seekdir end = unspecified ;
293) Typically long long.
294) streamsize is used in most places where ISO C would use size_t.
Most of the uses of streamsize could use size_t,
except for the strstreambuf constructors, which require negative values. It should probably be the signed type corresponding to
size_t (which is what Posix.2 calls ssize_t).
§ 30.5.3
1038
class Init;
// 30.5.3.2, fmtflags state
fmtflags flags() const;
fmtflags flags(fmtflags fmtfl);
fmtflags setf(fmtflags fmtfl);
fmtflags setf(fmtflags fmtfl, fmtflags
mask);
void unsetf(fmtflags mask);
streamsize precision() const;
streamsize precision(streamsize prec);
streamsize width() const;
streamsize width(streamsize wide);
// 30.5.3.3, locales
locale imbue(const locale& loc);
locale getloc() const;
// 30.5.3.5, storage
static int xalloc();
long& iword(int index);
void*& pword(int index);
// destructor
virtual ~ios_base();
// 30.5.3.6, callbacks
enum event { erase_event, imbue_event,
copyfmt_event
};
using event_callback = void (*)(event,
ios_base&, int index);
void register_callback(event_callback fn, int index);
ios_base(const ios_base&) = delete;
ios_base& operator=(const ios_base&) = delete;
static bool sync_with_stdio(bool sync = true);
protected:
ios_base();
private:
static int index;
// exposition only
long* iarray;
// exposition only
void** parray;
// exposition only
};
}
1
ios_base defines several member types:
(1.1)
—
a type failure, defined as either a class derived from system_error or a synonym for a class derived
from system_error;
(1.2)
—
a class Init;
(1.3)
—
three bitmask types, fmtflags, iostate, and openmode;
(1.4)
—
an enumerated type, seekdir.
2
It maintains several kinds of data:
(2.1)
—
state information that reflects the integrity of the stream buffer;
(2.2)
—
control information that influences how to interpret (format) input sequences and how to generate
(format) output sequences;
(2.3)
—
additional information that is stored by the program for its private use.
3
[ Note: For the sake of exposition, the maintained data is presented here as:
§ 30.5.3
1039
(3.1)
—
static int index, specifies the next available unique index for the integer or pointer arrays maintained
for the private use of the program, initialized to an unspecified value;
(3.2)
—
long* iarray, points to the first element of an arbitrary-length long array maintained for the private
use of the program;
(3.3)
—
void** parray, points to the first element of an arbitrary-length pointer array maintained for the
private use of the program.
— end note ]
30.5.3.1
Types
[ios.types]
30.5.3.1.1
Class ios_base::failure
[ios::failure]
namespace std {
class ios_base::failure : public system_error {
public:
explicit failure(const string& msg, const error_code& ec = io_errc::stream);
explicit failure(const char* msg, const error_code& ec = io_errc::stream);
};
}
1
An implementation is permitted to define ios_base::failure as a synonym for a class with equivalent
functionality to class ios_base::failure shown in this subclause. [Note: When ios_base::failure is a
synonym for another type it shall provide a nested type failure, to emulate the injected class name.
— end
note ] The class failure defines the base class for the types of all objects thrown as exceptions, by functions
in the iostreams library, to report errors detected during stream buffer operations.
2
When throwing ios_base::failure exceptions, implementations should provide values of ec that identify
the specific reason for the failure. [ Note: Errors arising from the operating system would typically be reported
as system_category() errors with an error value of the error number reported by the operating system.
Errors arising from within the stream library would typically be reported as error_code(io_errc::stream,
iostream_category()). — end note ]
explicit failure(const string& msg, const error_code& ec = io_errc::stream);
3
Effects: Constructs an object of class failure by constructing the base class with msg and ec.
explicit failure(const char* msg, const error_code& ec = io_errc::stream);
4
Effects: Constructs an object of class failure by constructing the base class with msg and ec.
30.5.3.1.2
Type ios_base::fmtflags
[ios::fmtflags]
using fmtflags = T1 ;
1
The type fmtflags is a bitmask type (20.4.2.1.4). Setting its elements has the effects indicated in
Table 107.
2
Type fmtflags also defines the constants indicated in Table 108.
30.5.3.1.3
Type ios_base::iostate
[ios::iostate]
using iostate = T2 ;
1
The type iostate is a bitmask type (20.4.2.1.4) that contains the elements indicated in Table 109.
2
Type iostate also defines the constant:
(2.1)
—
goodbit, the value zero.
30.5.3.1.4
Type ios_base::openmode
[ios::openmode]
using openmode = T3 ;
1
The type openmode is a bitmask type (20.4.2.1.4). It contains the elements indicated in Table 110.
30.5.3.1.5
Type ios_base::seekdir
[ios::seekdir]
using seekdir = T4 ;
1
The type seekdir is an enumerated type (20.4.2.1.3) that contains the elements indicated in Table 111.
§ 30.5.3.1.5
1040
Table 107 — fmtflags effects
Element
Effect(s) if set
boolalpha
insert and extract bool type in alphabetic format
dec
converts integer input or generates integer output in decimal base
fixed
generate floating-point output in fixed-point notation
hex
converts integer input or generates integer output in hexadecimal base
internal
adds fill characters at a designated internal point in certain generated output,
or identical to right if no such point is designated
left
adds fill characters on the right (final positions) of certain generated output
oct
converts integer input or generates integer output in octal base
right
adds fill characters on the left (initial positions) of certain generated output
scientific
generates floating-point output in scientific notation
showbase
generates a prefix indicating the numeric base of generated integer output
showpoint
generates a decimal-point character unconditionally in generated floating-
point output
showpos
generates a + sign in non-negative generated numeric output
skipws
skips leading whitespace before certain input operations
unitbuf
flushes output after each output operation
uppercase
replaces certain lowercase letters with their uppercase equivalents in gener-
ated output
Table 108 — fmtflags constants
Constant
Allowable values
adjustfield left | right | internal
basefield
dec | oct | hex
floatfield
scientific | fixed
Table 109 — iostate effects
Element
Effect(s) if set
badbit
indicates a loss of integrity in an input or output sequence (such as an
irrecoverable read error from a file);
eofbit
indicates that an input operation reached the end of an input sequence;
failbit
indicates that an input operation failed to read the expected characters, or
that an output operation failed to generate the desired characters.
Table 110 — openmode effects
Element
Effect(s) if set
app
seek to end before each write
ate
open and seek to end immediately after opening
binary
perform input and output in binary mode (as opposed to text mode)
in
open for input
out
open for output
trunc
truncate an existing stream when opening
Table 111 — seekdir effects
Element
Meaning
beg
request a seek (for subsequent input or output) relative to the beginning of
the stream
cur
request a seek relative to the current position within the sequence
end
request a seek relative to the current end of the sequence
§
30.5.3.1.5
1041