17 Language support library [support]

17.3 Implementation properties [support.limits]

17.3.5 Class template numeric_­limits [numeric.limits]

17.3.5.1 General [numeric.limits.general]

The numeric_­limits class template provides a C++ program with information about various properties of the implementation's representation of the arithmetic types.
namespace std { template<class T> class numeric_limits { public: static constexpr bool is_specialized = false; static constexpr T min() noexcept { return T(); } static constexpr T max() noexcept { return T(); } static constexpr T lowest() noexcept { return T(); } static constexpr int digits = 0; static constexpr int digits10 = 0; static constexpr int max_digits10 = 0; static constexpr bool is_signed = false; static constexpr bool is_integer = false; static constexpr bool is_exact = false; static constexpr int radix = 0; static constexpr T epsilon() noexcept { return T(); } static constexpr T round_error() noexcept { return T(); } static constexpr int min_exponent = 0; static constexpr int min_exponent10 = 0; static constexpr int max_exponent = 0; static constexpr int max_exponent10 = 0; static constexpr bool has_infinity = false; static constexpr bool has_quiet_NaN = false; static constexpr bool has_signaling_NaN = false; static constexpr float_denorm_style has_denorm = denorm_absent; static constexpr bool has_denorm_loss = false; static constexpr T infinity() noexcept { return T(); } static constexpr T quiet_NaN() noexcept { return T(); } static constexpr T signaling_NaN() noexcept { return T(); } static constexpr T denorm_min() noexcept { return T(); } static constexpr bool is_iec559 = false; static constexpr bool is_bounded = false; static constexpr bool is_modulo = false; static constexpr bool traps = false; static constexpr bool tinyness_before = false; static constexpr float_round_style round_style = round_toward_zero; }; }
For all members declared static constexpr in the numeric_­limits template, specializations shall define these values in such a way that they are usable as constant expressions.
For the numeric_­limits primary template, all data members are value-initialized and all member functions return a value-initialized object.
[Note 1:
This means all members have zero or false values unless numeric_­limits is specialized for a type.
β€” end note]
Specializations shall be provided for each arithmetic type, both floating-point and integer, including bool.
The member is_­specialized shall be true for all such specializations of numeric_­limits.
The value of each member of a specialization of numeric_­limits on a cv-qualified type cv T shall be equal to the value of the corresponding member of the specialization on the unqualified type T.
Non-arithmetic standard types, such as complex<T>, shall not have specializations.

17.3.5.2 numeric_­limits members [numeric.limits.members]

Each member function defined in this subclause is signal-safe.
static constexpr T min() noexcept;
Minimum finite value.178
For floating-point types with subnormal numbers, returns the minimum positive normalized value.
Meaningful for all specializations in which is_­bounded != false, or is_­bounded == false && is_­signed == false.
static constexpr T max() noexcept;
Maximum finite value.179
Meaningful for all specializations in which is_­bounded != false.
static constexpr T lowest() noexcept;
A finite value x such that there is no other finite value y where y < x.180
Meaningful for all specializations in which is_­bounded != false.
static constexpr int digits;
Number of radix digits that can be represented without change.
For integer types, the number of non-sign bits in the representation.
For floating-point types, the number of radix digits in the mantissa.181
static constexpr int digits10;
Number of base 10 digits that can be represented without change.182
Meaningful for all specializations in which is_­bounded != false.
static constexpr int max_digits10;
Number of base 10 digits required to ensure that values which differ are always differentiated.
Meaningful for all floating-point types.
static constexpr bool is_signed;
true if the type is signed.
Meaningful for all specializations.
static constexpr bool is_integer;
true if the type is integer.
Meaningful for all specializations.
static constexpr bool is_exact;
true if the type uses an exact representation.
All integer types are exact, but not all exact types are integer.
For example, rational and fixed-exponent representations are exact but not integer.
Meaningful for all specializations.
static constexpr int radix;
For floating-point types, specifies the base or radix of the exponent representation (often 2).183
For integer types, specifies the base of the representation.184
Meaningful for all specializations.
static constexpr T epsilon() noexcept;
Machine epsilon: the difference between 1 and the least value greater than 1 that is representable.185
Meaningful for all floating-point types.
static constexpr T round_error() noexcept;
Measure of the maximum rounding error.186
static constexpr int min_exponent;
Minimum negative integer such that radix raised to the power of one less than that integer is a normalized floating-point number.187
Meaningful for all floating-point types.
static constexpr int min_exponent10;
Minimum negative integer such that 10 raised to that power is in the range of normalized floating-point numbers.188
Meaningful for all floating-point types.
static constexpr int max_exponent;
Maximum positive integer such that radix raised to the power one less than that integer is a representable finite floating-point number.189
Meaningful for all floating-point types.
static constexpr int max_exponent10;
Maximum positive integer such that 10 raised to that power is in the range of representable finite floating-point numbers.190
Meaningful for all floating-point types.
static constexpr bool has_infinity;
true if the type has a representation for positive infinity.
Meaningful for all floating-point types.
Shall be true for all specializations in which is_­iec559 != false.
static constexpr bool has_quiet_NaN;
true if the type has a representation for a quiet (non-signaling) β€œNot a Number”.191
Meaningful for all floating-point types.
Shall be true for all specializations in which is_­iec559 != false.
static constexpr bool has_signaling_NaN;
true if the type has a representation for a signaling β€œNot a Number”.192
Meaningful for all floating-point types.
Shall be true for all specializations in which is_­iec559 != false.
static constexpr float_denorm_style has_denorm;
denorm_­present if the type allows subnormal values (variable number of exponent bits),193 denorm_­absent if the type does not allow subnormal values, and denorm_­indeterminate if it is indeterminate at compile time whether the type allows subnormal values.
Meaningful for all floating-point types.
static constexpr bool has_denorm_loss;
true if loss of accuracy is detected as a denormalization loss, rather than as an inexact result.194
static constexpr T infinity() noexcept;
Representation of positive infinity, if available.195
Meaningful for all specializations for which has_­infinity != false.
Required in specializations for which is_­iec559 != false.
static constexpr T quiet_NaN() noexcept;
Representation of a quiet β€œNot a Number”, if available.196
Meaningful for all specializations for which has_­quiet_­NaN != false.
Required in specializations for which is_­iec559 != false.
static constexpr T signaling_NaN() noexcept;
Representation of a signaling β€œNot a Number”, if available.197
Meaningful for all specializations for which has_­signaling_­NaN != false.
Required in specializations for which is_­iec559 != false.
static constexpr T denorm_min() noexcept;
Minimum positive subnormal value.198
Meaningful for all floating-point types.
In specializations for which has_­denorm == false, returns the minimum positive normalized value.
static constexpr bool is_iec559;
true if and only if the type adheres to ISO/IEC/IEEE 60559.199
Meaningful for all floating-point types.
static constexpr bool is_bounded;
true if the set of values representable by the type is finite.200
[Note 1:
All fundamental types ([basic.fundamental]) are bounded.
This member would be false for arbitrary precision types.
β€” end note]
Meaningful for all specializations.
static constexpr bool is_modulo;
true if the type is modulo.201
A type is modulo if, for any operation involving +, -, or * on values of that type whose result would fall outside the range [min(), max()], the value returned differs from the true value by an integer multiple of max() - min() + 1.
[Example 1:
is_­modulo is false for signed integer types ([basic.fundamental]) unless an implementation, as an extension to this document, defines signed integer overflow to wrap.
β€” end example]
Meaningful for all specializations.
static constexpr bool traps;
true if, at the start of the program, there exists a value of the type that would cause an arithmetic operation using that value to trap.202
Meaningful for all specializations.
static constexpr bool tinyness_before;
true if tinyness is detected before rounding.203
Meaningful for all floating-point types.
static constexpr float_round_style round_style;
The rounding style for the type.204
Meaningful for all floating-point types.
Specializations for integer types shall return round_­toward_­zero.
178)178)
Equivalent to CHAR_­MIN, SHRT_­MIN, FLT_­MIN, DBL_­MIN, etc.
179)179)
Equivalent to CHAR_­MAX, SHRT_­MAX, FLT_­MAX, DBL_­MAX, etc.
180)180)
lowest() is necessary because not all floating-point representations have a smallest (most negative) value that is the negative of the largest (most positive) finite value.
181)181)
Equivalent to FLT_­MANT_­DIG, DBL_­MANT_­DIG, LDBL_­MANT_­DIG.
182)182)
Equivalent to FLT_­DIG, DBL_­DIG, LDBL_­DIG.
183)183)
Equivalent to FLT_­RADIX.
184)184)
Distinguishes types with bases other than 2 (e.g. BCD).
185)185)
Equivalent to FLT_­EPSILON, DBL_­EPSILON, LDBL_­EPSILON.
186)186)
Rounding error is described in LIA-1 Section 5.2.4 and Annex C Rationale Section C.5.2.4 β€” Rounding and rounding constants.
187)187)
Equivalent to FLT_­MIN_­EXP, DBL_­MIN_­EXP, LDBL_­MIN_­EXP.
188)188)
Equivalent to FLT_­MIN_­10_­EXP, DBL_­MIN_­10_­EXP, LDBL_­MIN_­10_­EXP.
189)189)
Equivalent to FLT_­MAX_­EXP, DBL_­MAX_­EXP, LDBL_­MAX_­EXP.
190)190)
Equivalent to FLT_­MAX_­10_­EXP, DBL_­MAX_­10_­EXP, LDBL_­MAX_­10_­EXP.
191)191)
Required by LIA-1.
192)192)
Required by LIA-1.
193)193)
Required by LIA-1.
194)194)
See ISO/IEC/IEEE 60559.
195)195)
Required by LIA-1.
196)196)
Required by LIA-1.
197)197)
Required by LIA-1.
198)198)
Required by LIA-1.
199)199)
ISO/IEC/IEEE 60559:2011 is the same as IEEE 754-2008.
200)200)
Required by LIA-1.
201)201)
Required by LIA-1.
202)202)
Required by LIA-1.
203)203)
Refer to ISO/IEC/IEEE 60559.
Required by LIA-1.
204)204)
Equivalent to FLT_­ROUNDS.
Required by LIA-1.

17.3.5.3 numeric_­limits specializations [numeric.special]

All members shall be provided for all specializations.
However, many values are only required to be meaningful under certain conditions (for example, epsilon() is only meaningful if is_­integer is false).
Any value that is not β€œmeaningful” shall be set to 0 or false.
[Example 1: namespace std { template<> class numeric_limits<float> { public: static constexpr bool is_specialized = true; static constexpr float min() noexcept { return 1.17549435E-38F; } static constexpr float max() noexcept { return 3.40282347E+38F; } static constexpr float lowest() noexcept { return -3.40282347E+38F; } static constexpr int digits = 24; static constexpr int digits10 = 6; static constexpr int max_digits10 = 9; static constexpr bool is_signed = true; static constexpr bool is_integer = false; static constexpr bool is_exact = false; static constexpr int radix = 2; static constexpr float epsilon() noexcept { return 1.19209290E-07F; } static constexpr float round_error() noexcept { return 0.5F; } static constexpr int min_exponent = -125; static constexpr int min_exponent10 = - 37; static constexpr int max_exponent = +128; static constexpr int max_exponent10 = + 38; static constexpr bool has_infinity = true; static constexpr bool has_quiet_NaN = true; static constexpr bool has_signaling_NaN = true; static constexpr float_denorm_style has_denorm = denorm_absent; static constexpr bool has_denorm_loss = false; static constexpr float infinity() noexcept { return value; } static constexpr float quiet_NaN() noexcept { return value; } static constexpr float signaling_NaN() noexcept { return value; } static constexpr float denorm_min() noexcept { return min(); } static constexpr bool is_iec559 = true; static constexpr bool is_bounded = true; static constexpr bool is_modulo = false; static constexpr bool traps = true; static constexpr bool tinyness_before = true; static constexpr float_round_style round_style = round_to_nearest; }; } β€” end example]
The specialization for bool shall be provided as follows: namespace std { template<> class numeric_limits<bool> { public: static constexpr bool is_specialized = true; static constexpr bool min() noexcept { return false; } static constexpr bool max() noexcept { return true; } static constexpr bool lowest() noexcept { return false; } static constexpr int digits = 1; static constexpr int digits10 = 0; static constexpr int max_digits10 = 0; static constexpr bool is_signed = false; static constexpr bool is_integer = true; static constexpr bool is_exact = true; static constexpr int radix = 2; static constexpr bool epsilon() noexcept { return 0; } static constexpr bool round_error() noexcept { return 0; } static constexpr int min_exponent = 0; static constexpr int min_exponent10 = 0; static constexpr int max_exponent = 0; static constexpr int max_exponent10 = 0; static constexpr bool has_infinity = false; static constexpr bool has_quiet_NaN = false; static constexpr bool has_signaling_NaN = false; static constexpr float_denorm_style has_denorm = denorm_absent; static constexpr bool has_denorm_loss = false; static constexpr bool infinity() noexcept { return 0; } static constexpr bool quiet_NaN() noexcept { return 0; } static constexpr bool signaling_NaN() noexcept { return 0; } static constexpr bool denorm_min() noexcept { return 0; } static constexpr bool is_iec559 = false; static constexpr bool is_bounded = true; static constexpr bool is_modulo = false; static constexpr bool traps = false; static constexpr bool tinyness_before = false; static constexpr float_round_style round_style = round_toward_zero; }; }