Representation Limits
*********************

This chapter contains information about constants and parameters that characterize the representation of the various integer and floating-point types supported by the GNU C library.

Integer Representation Limits
=============================

Sometimes it is necessary for programs to know about the internal representation of various integer subtypes.  For example, if you want your program to be careful not to overflow an int counter variable, you need to know what the largest representable value that fits in an int is.  These kinds of parameters can vary from compiler to compiler and machine to machine.  Another typical use of this kind of parameter is in conditionalizing data structure definitions with #ifdef to select the most appropriate integer subtype that can represent the required range of values.

Macros representing the minimum and maximum limits of the integer types are defined in the header file limits.h.  The values of these macros are all integer constant expressions.

 -- Macro: int CHAR_BIT
     This is the number of bits in a char, usually eight.

 -- Macro: int SCHAR_MIN
     This is the minimum value that can be represented by a signed char.

 -- Macro: int SCHAR_MAX
     This is the maximum value that can be represented by a signed char.

 -- Macro: int UCHAR_MAX
     This is the maximum value that can be represented by a unsigned char. (The minimum value of an unsigned char is zero.)

 -- Macro: int CHAR_MIN
     This is the minimum value that can be represented by a char. It's equal to SCHAR_MIN if char is signed, or zero otherwise.

 -- Macro: int CHAR_MAX
     This is the maximum value that can be represented by a char. It's equal to SCHAR_MAX if char is signed, or UCHAR_MAX otherwise.

 -- Macro: int SHRT_MIN
     This is the minimum value that can be represented by a signed short int.  On most machines that the GNU C library runs on, short integers are 16-bit quantities.

 -- Macro: int SHRT_MAX
     This is the maximum value that can be represented by a signed short int.

 -- Macro: int USHRT_MAX
     This is the maximum value that can be represented by an unsigned short int.  (The minimum value of an unsigned short int is zero.)

 -- Macro: int INT_MIN
     This is the minimum value that can be represented by a signed int.  On most machines that the GNU C system runs on, an int is a 32-bit quantity.

 -- Macro: int INT_MAX
     This is the maximum value that can be represented by a signed int.

 -- Macro: unsigned int UINT_MAX
     This is the maximum value that can be represented by an unsigned int.  (The minimum value of an unsigned int is zero.)

 -- Macro: long int LONG_MIN
     This is the minimum value that can be represented by a signed long int.  On most machines that the GNU C system runs on, long integers are 32-bit quantities, the same size as int.

 -- Macro: long int LONG_MAX
     This is the maximum value that can be represented by a signed long int.

 -- Macro: unsigned long int ULONG_MAX
     This is the maximum value that can be represented by an unsigned long int.  (The minimum value of an unsigned long int is zero.)

Incomplete:  There should be corresponding limits for the GNU C Compiler's long long type, too.  (But they are not now present in the header file.)

The header file limits.h also defines some additional constants that parameterize various operating system and file system limits.  These constants are described in System Parameters and File System Parameters.

Floating-Point Limits
=====================

Because floating-point numbers are represented internally as approximate quantities, algorithms for manipulating floating-point data often need to be parameterized in terms of the accuracy of the representation. Some of the functions in the C library itself need this information; for example, the algorithms for printing and reading floating-point numbers (see I/O on Streams) and for calculating trigonometric and irrational functions (see Mathematics) use information about the underlying floating-point representation to avoid round-off error and loss of accuracy.  User programs that implement numerical analysis techniques also often need to be parameterized in this way in order to minimize or compute error bounds.

The specific representation of floating-point numbers varies from machine to machine.  The GNU C library defines a set of parameters which characterize each of the supported floating-point representations on a particular system.

Floating-Point Representation
-----------------------------

This section introduces the terminology used to characterize the representation of floating-point numbers.

You are probably already familiar with most of these concepts in terms of scientific or exponential notation for floating-point numbers.  For example, the number 123456.0 could be expressed in exponential notation as 1.23456e+05, a shorthand notation indicating that the mantissa 1.23456 is multiplied by the base 10 raised to power 5.

More formally, the internal representation of a floating-point number can be characterized in terms of the following parameters:

  * The sign is either -1 or 1.

  * The base or radix for exponentiation; an integer greater than 1.  This is a constant for the particular representation.

  * The exponent to which the base is raised.  The upper and lower bounds of the exponent value are constants for the particular representation.

     Sometimes, in the actual bits representing the floating-point number, the exponent is biased by adding a constant to it, to make it always be represented as an unsigned quantity.  This is only important if you have some reason to pick apart the bit fields making up the floating-point number by hand, which is something for which the GNU library provides no support.  So this is ignored in the discussion that follows.

  * The value of the mantissa or significand, which is an unsigned integer.

  * The precision of the mantissa.  If the base of the representation is B, then the precision is the number of base-B digits in the mantissa.  This is a constant for the particular representation.

     Many floating-point representations have an implicit hidden bit in the mantissa.  Any such hidden bits are counted in the precision. Again, the GNU library provides no facilities for dealing with such low-level aspects of the representation.

The mantissa of a floating-point number actually represents an implicit fraction whose denominator is the base raised to the power of the precision.  Since the largest representable mantissa is one less than this denominator, the value of the fraction is always strictly less than 1.  The mathematical value of a floating-point number is then the product of this fraction; the sign; and the base raised to the exponent.

If the floating-point number is normalized, the mantissa is also greater than or equal to the base raised to the power of one less than the precision (unless the number represents a floating-point zero, in which case the mantissa is zero).  The fractional quantity is therefore greater than or equal to 1/B, where B is the base.

Floating-Point Parameters
-------------------------

Incomplete:  This section needs some more concrete examples of what these parameters mean and how to use them in a program.

These macro definitions can be accessed by including the header file float.h in your program.

Macro names starting with FLT_ refer to the float type, while names beginning with DBL_ refer to the double type and names beginning with LDBL_ refer to the long double type.  (In implementations that do not support long double as a distinct data type, the values for those constants are the same as the corresponding constants for the double type.)

Of these macros, only FLT_RADIX is guaranteed to be a constant expression.  The other macros listed here cannot be reliably used in places that require constant expressions, such as #if preprocessing directives or array size specifications.

Although the ANSI C standard specifies minimum and maximum values for most of these parameters, the GNU C implementation uses whatever floating-point representations are supported by the underlying hardware. So whether GNU C actually satisfies the ANSI C requirements depends on what machine it is running on.

 -- Macro: int FLT_ROUNDS
     This value characterizes the rounding mode for floating-point addition. The following values indicate standard rounding modes:

     -1
          The mode is indeterminable.

     0
          Rounding is towards zero.

     1
          Rounding is to the nearest number.

     2
          Rounding is towards positive infinity.

     3
          Rounding is towards negative infinity.

     Any other value represents a machine-dependent nonstandard rounding mode.

 -- Macro: int FLT_RADIX
     This is the value of the base, or radix, of exponent representation. This is guaranteed to be a constant expression, unlike the other macros described in this section.

 -- Macro: int FLT_MANT_DIG
     This is the number of base-FLT_RADIX digits in the floating-point mantissa for the float data type.

 -- Macro: int DBL_MANT_DIG
     This is the number of base-FLT_RADIX digits in the floating-point mantissa for the double data type.

 -- Macro: int LDBL_MANT_DIG
     This is the number of base-FLT_RADIX digits in the floating-point mantissa for the long double data type.

 -- Macro: int FLT_DIG
     This is the number of decimal digits of precision for the float data type.  Technically, if P and B are the precision and base (respectively) for the representation, then the decimal precision Q is the maximum number of decimal digits such that any floating point number with Q base 10 digits can be rounded to a floating point number with P base B digits and back again, without change to the Q decimal digits.

     The value of this macro is guaranteed to be at least 6.

 -- Macro: int DBL_DIG
     This is similar to FLT_DIG, but is for the double data type.  The value of this macro is guaranteed to be at least 10.

 -- Macro: int LDBL_DIG
     This is similar to FLT_DIG, but is for the long double data type.  The value of this macro is guaranteed to be at least 10.

 -- Macro: int FLT_MIN_EXP
     This is the minimum negative integer such that the mathematical value FLT_RADIX raised to this power minus 1 can be represented as a normalized floating-point number of type float.  In terms of the actual implementation, this is just the smallest value that can be represented in the exponent field of the number.

 -- Macro: int DBL_MIN_EXP
     This is similar to FLT_MIN_EXP, but is for the double data type.

 -- Macro: int LDBL_MIN_EXP
     This is similar to FLT_MIN_EXP, but is for the long double data type.

 -- Macro: int FLT_MIN_10_EXP
     This is the minimum negative integer such that the mathematical value 10 raised to this power minus 1 can be represented as a normalized floating-point number of type float.  This is guaranteed to be no greater than -37.

 -- Macro: int DBL_MIN_10_EXP
     This is similar to FLT_MIN_10_EXP, but is for the double data type.

 -- Macro: int LDBL_MIN_10_EXP
     This is similar to FLT_MIN_10_EXP, but is for the long double data type.

 -- Macro: int FLT_MAX_EXP
     This is the maximum negative integer such that the mathematical value FLT_RADIX raised to this power minus 1 can be represented as a floating-point number of type float.  In terms of the actual implementation, this is just the largest value that can be represented in the exponent field of the number.

 -- Macro: int DBL_MAX_EXP
     This is similar to FLT_MAX_EXP, but is for the double data type.

 -- Macro: int LDBL_MAX_EXP
     This is similar to FLT_MAX_EXP, but is for the long double data type.

 -- Macro: int FLT_MAX_10_EXP
     This is the maximum negative integer such that the mathematical value 10 raised to this power minus 1 can be represented as a normalized floating-point number of type float.  This is guaranteed to be at least 37.

 -- Macro: int DBL_MAX_10_EXP
     This is similar to FLT_MAX_10_EXP, but is for the double data type.

 -- Macro: int LDBL_MAX_10_EXP
     This is similar to FLT_MAX_10_EXP, but is for the long double data type.

 -- Macro: double FLT_MAX
     The value of this macro is the maximum representable floating-point number of type float, and is guaranteed to be at least 1E+37.

 -- Macro: double DBL_MAX
     The value of this macro is the maximum representable floating-point number of type double, and is guaranteed to be at least 1E+37.

 -- Macro: long double LDBL_MAX
     The value of this macro is the maximum representable floating-point number of type long double, and is guaranteed to be at least 1E+37.

 -- Macro: double FLT_MIN
     The value of this macro is the minimum normalized positive floating-point number that is representable by type float, and is guaranteed to be no more than 1E-37.

 -- Macro: double DBL_MIN
     The value of this macro is the minimum normalized positive floating-point number that is representable by type double, and is guaranteed to be no more than 1E-37.

 -- Macro: long double LDBL_MIN
     The value of this macro is the minimum normalized positive floating-point number that is representable by type long double, and is guaranteed to be no more than 1E-37.

 -- Macro: double FLT_EPSILON
     This is the minimum positive floating-point number of type float such that 1.0 + FLT_EPSILON != 1.0 is true.  It's guaranteed to be no greater than 1E-5.

 -- Macro: double DBL_EPSILON
     This is similar to FLT_EPSILON, but is for the double type.  The maximum value is 1E-9.

 -- Macro: long double LDBL_EPSILON
     This is similar to FLT_EPSILON, but is for the long double type.  The maximum value is 1E-9.

IEEE Floating Point
-------------------

Here is an example showing how these parameters work for a common floating point representation, specified by the IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985).  Nearly all computers today use this format.

The IEEE single-precision float representation uses a base of 2.  There is a sign bit, a mantissa with 23 bits plus one hidden bit (so the total precision is 24 base-2 digits), and an 8-bit exponent that can represent values in the range -125 to 128, inclusive.

So, for an implementation that uses this representation for the float data type, appropriate values for the corresponding parameters are:

     FLT_RADIX                             2
     FLT_MANT_DIG                         24
     FLT_DIG                               6
     FLT_MIN_EXP                        -125
     FLT_MIN_10_EXP                      -37
     FLT_MAX_EXP                         128
     FLT_MAX_10_EXP                      +38
     FLT_MIN                 1.17549435E-38F
     FLT_MAX                 3.40282347E+38F
     FLT_EPSILON             1.19209290E-07F

Here are the values for the double data type:

     DBL_MANT_DIG                         53
     DBL_DIG                              15
     DBL_MIN_EXP                       -1021
     DBL_MIN_10_EXP                     -307
     DBL_MAX_EXP                        1024
     DBL_MAX_10_EXP                      308
     DBL_MAX         1.7976931348623157E+308
     DBL_MIN         2.2250738585072014E-308
     DBL_EPSILON     2.2204460492503131E-016