21 Language support library [language.support]

21.3 Implementation properties [support.limits]

21.3.4 Class template numeric_­limits [numeric.limits]

1
#
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;
  };

  template<class T> class numeric_limits<const T>;
  template<class T> class numeric_limits<volatile T>;
  template<class T> class numeric_limits<const volatile T>;
}
2
#
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.
3
#
The default numeric_­limits<T> template shall have all members, but with 0 or false values.
4
#
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.
5
#
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.
6
#
Non-arithmetic standard types, such as complex<T> ([complex]), shall not have specializations.

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

1
#
Each member function defined in this subclause is signal-safe ([csignal.syn]).
static constexpr T min() noexcept;
2
#
Minimum finite value.188
3
#
For floating types with subnormal numbers, returns the minimum positive normalized value.
4
#
Meaningful for all specializations in which is_­bounded != false, or is_­bounded == false && is_­signed == false.
static constexpr T max() noexcept;
5
#
Maximum finite value.189
6
#
Meaningful for all specializations in which is_­bounded != false.
static constexpr T lowest() noexcept;
7
#
A finite value x such that there is no other finite value y where y < x.190
8
#
Meaningful for all specializations in which is_­bounded != false.
static constexpr int digits;
9
#
Number of radix digits that can be represented without change.
10
#
For integer types, the number of non-sign bits in the representation.
11
#
For floating-point types, the number of radix digits in the mantissa.191
static constexpr int digits10;
12
#
Number of base 10 digits that can be represented without change.192
13
#
Meaningful for all specializations in which is_­bounded != false.
static constexpr int max_digits10;
14
#
Number of base 10 digits required to ensure that values which differ are always differentiated.
15
#
Meaningful for all floating-point types.
static constexpr bool is_signed;
16
#
true if the type is signed.
17
#
Meaningful for all specializations.
static constexpr bool is_integer;
18
#
true if the type is integer.
19
#
Meaningful for all specializations.
static constexpr bool is_exact;
20
#
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.
21
#
Meaningful for all specializations.
static constexpr int radix;
22
#
For floating types, specifies the base or radix of the exponent representation (often 2).193
23
#
For integer types, specifies the base of the representation.194
24
#
Meaningful for all specializations.
static constexpr T epsilon() noexcept;
25
#
Machine epsilon: the difference between 1 and the least value greater than 1 that is representable.195
26
#
Meaningful for all floating-point types.
static constexpr T round_error() noexcept;
27
#
Measure of the maximum rounding error.196
static constexpr int min_exponent;
28
#
Minimum negative integer such that radix raised to the power of one less than that integer is a normalized floating-point number.197
29
#
Meaningful for all floating-point types.
static constexpr int min_exponent10;
30
#
Minimum negative integer such that 10 raised to that power is in the range of normalized floating-point numbers.198
31
#
Meaningful for all floating-point types.
static constexpr int max_exponent;
32
#
Maximum positive integer such that radix raised to the power one less than that integer is a representable finite floating-point number.199
33
#
Meaningful for all floating-point types.
static constexpr int max_exponent10;
34
#
Maximum positive integer such that 10 raised to that power is in the range of representable finite floating-point numbers.200
35
#
Meaningful for all floating-point types.
static constexpr bool has_infinity;
36
#
true if the type has a representation for positive infinity.
37
#
Meaningful for all floating-point types.
38
#
Shall be true for all specializations in which is_­iec559 != false.
static constexpr bool has_quiet_NaN;
39
#
true if the type has a representation for a quiet (non-signaling) “Not a Number”.201
40
#
Meaningful for all floating-point types.
41
#
Shall be true for all specializations in which is_­iec559 != false.
static constexpr bool has_signaling_NaN;
42
#
true if the type has a representation for a signaling “Not a Number”.202
43
#
Meaningful for all floating-point types.
44
#
Shall be true for all specializations in which is_­iec559 != false.
static constexpr float_denorm_style has_denorm;
45
#
denorm_­present if the type allows subnormal values (variable number of exponent bits)203, 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.
46
#
Meaningful for all floating-point types.
static constexpr bool has_denorm_loss;
47
#
true if loss of accuracy is detected as a denormalization loss, rather than as an inexact result.204
static constexpr T infinity() noexcept;
48
#
Representation of positive infinity, if available.205
49
#
Meaningful for all specializations for which has_­infinity != false.
Required in specializations for which is_­iec559 != false.
static constexpr T quiet_NaN() noexcept;
50
#
Representation of a quiet “Not a Number”, if available.206
51
#
Meaningful for all specializations for which has_­quiet_­NaN != false.
Required in specializations for which is_­iec559 != false.
static constexpr T signaling_NaN() noexcept;
52
#
Representation of a signaling “Not a Number”, if available.207
53
#
Meaningful for all specializations for which has_­signaling_­NaN != false.
Required in specializations for which is_­iec559 != false.
static constexpr T denorm_min() noexcept;
54
#
Minimum positive subnormal value.208
55
#
Meaningful for all floating-point types.
56
#
In specializations for which has_­denorm == false, returns the minimum positive normalized value.
static constexpr bool is_iec559;
57
#
true if and only if the type adheres to ISO/IEC/IEEE 60559.209
58
#
Meaningful for all floating-point types.
static constexpr bool is_bounded;
59
#
true if the set of values representable by the type is finite.210
[ Note
:
All fundamental types ([basic.fundamental]) are bounded.
This member would be false for arbitrary precision types.
— end note
 ]
60
#
Meaningful for all specializations.
static constexpr bool is_modulo;
61
#
true if the type is modulo.211
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.
62
#
[ Example
:
is_­modulo is false for signed integer types ([basic.fundamental]) unless an implementation, as an extension to this International Standard, defines signed integer overflow to wrap.
— end example
 ]
63
#
Meaningful for all specializations.
static constexpr bool traps;
64
#
true if, at program startup, there exists a value of the type that would cause an arithmetic operation using that value to trap.212
65
#
Meaningful for all specializations.
static constexpr bool tinyness_before;
66
#
true if tinyness is detected before rounding.213
67
#
Meaningful for all floating-point types.
static constexpr float_round_style round_style;
68
#
The rounding style for the type.214
69
#
Meaningful for all floating-point types.
Specializations for integer types shall return round_­toward_­zero.
188)
Equivalent to CHAR_­MIN, SHRT_­MIN, FLT_­MIN, DBL_­MIN, etc.
189)
Equivalent to CHAR_­MAX, SHRT_­MAX, FLT_­MAX, DBL_­MAX, etc.
190)
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.
191)
Equivalent to FLT_­MANT_­DIG, DBL_­MANT_­DIG, LDBL_­MANT_­DIG.
192)
Equivalent to FLT_­DIG, DBL_­DIG, LDBL_­DIG.
193)
Equivalent to FLT_­RADIX.
194)
Distinguishes types with bases other than 2 (e.g. BCD).
195)
Equivalent to FLT_­EPSILON, DBL_­EPSILON, LDBL_­EPSILON.
196)
Rounding error is described in LIA-1 Section 5.
2.
4 and Annex C Rationale Section C.
5.
2.
4 — Rounding and rounding constants.
197)
Equivalent to FLT_­MIN_­EXP, DBL_­MIN_­EXP, LDBL_­MIN_­EXP.
198)
Equivalent to FLT_­MIN_­10_­EXP, DBL_­MIN_­10_­EXP, LDBL_­MIN_­10_­EXP.
199)
Equivalent to FLT_­MAX_­EXP, DBL_­MAX_­EXP, LDBL_­MAX_­EXP.
200)
Equivalent to FLT_­MAX_­10_­EXP, DBL_­MAX_­10_­EXP, LDBL_­MAX_­10_­EXP.
201)
Required by LIA-1.
202)
Required by LIA-1.
203)
Required by LIA-1.
204)
See ISO/IEC/IEEE 60559.
205)
Required by LIA-1.
206)
Required by LIA-1.
207)
Required by LIA-1.
208)
Required by LIA-1.
209)
ISO/IEC/IEEE 60559:2011 is the same as IEEE 754-2008.
210)
Required by LIA-1.
211)
Required by LIA-1.
212)
Required by LIA-1.
213)
Refer to ISO/IEC/IEEE 60559.
Required by LIA-1.
214)
Equivalent to FLT_­ROUNDS.
Required by LIA-1.

21.3.4.2 numeric_­limits specializations [numeric.special]

1
#
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.
2
#
[ Example
: 
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
 ]
3
#
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;
   };
}