Rounding Functions (The GNU C Library)

#### 20.8.3 Rounding Functions ¶

The functions listed here perform operations such as rounding and truncation of floating-point values. Some of these functions convert floating point numbers to integer values. They are all declared in `math.h`.

You can also convert floating-point numbers to integers simply by casting them to `int`. This discards the fractional part, effectively rounding towards zero. However, this only works if the result can actually be represented as an `int`—for very large numbers, this is impossible. The functions listed here return the result as a `double` instead to get around this problem.

The `fromfp` functions use the following macros, from TS 18661-1:2014, to specify the direction of rounding. These correspond to the rounding directions defined in IEEE 754-2008.

`FP_INT_UPWARD` ¶

  Round toward +∞.

`FP_INT_DOWNWARD` ¶

  Round toward -∞.

`FP_INT_TOWARDZERO` ¶

  Round toward zero.

`FP_INT_TONEARESTFROMZERO` ¶

  Round to nearest, ties round away from zero.

`FP_INT_TONEAREST` ¶

  Round to nearest, ties round to even.

Function: `double` ceil `(double x)` ¶
Function: `float` ceilf `(float x)` ¶
Function: `long double` ceill `(long double x)` ¶
Function: `_FloatN` ceilfN `(_FloatN x)` ¶
Function: `_FloatNx` ceilfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions round x upwards to the nearest integer, returning that value as a `double`. Thus, `ceil (1.5)` is `2.0`.

Function: `double` floor `(double x)` ¶
Function: `float` floorf `(float x)` ¶
Function: `long double` floorl `(long double x)` ¶
Function: `_FloatN` floorfN `(_FloatN x)` ¶
Function: `_FloatNx` floorfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions round x downwards to the nearest integer, returning that value as a `double`. Thus, `floor (1.5)` is `1.0` and `floor (-1.5)` is `-2.0`.

Function: `double` trunc `(double x)` ¶
Function: `float` truncf `(float x)` ¶
Function: `long double` truncl `(long double x)` ¶
Function: `_FloatN` truncfN `(_FloatN x)` ¶
Function: `_FloatNx` truncfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  The `trunc` functions round x towards zero to the nearest integer (returned in floating-point format). Thus, `trunc (1.5)` is `1.0` and `trunc (-1.5)` is `-1.0`.

Function: `double` rint `(double x)` ¶
Function: `float` rintf `(float x)` ¶
Function: `long double` rintl `(long double x)` ¶
Function: `_FloatN` rintfN `(_FloatN x)` ¶
Function: `_FloatNx` rintfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions round x to an integer value according to the current rounding mode. See Floating Point Parameters, for information about the various rounding modes. The default rounding mode is to round to the nearest integer; some machines support other modes, but round-to-nearest is always used unless you explicitly select another.

  If x was not initially an integer, these functions raise the inexact exception.

Function: `double` nearbyint `(double x)` ¶
Function: `float` nearbyintf `(float x)` ¶
Function: `long double` nearbyintl `(long double x)` ¶
Function: `_FloatN` nearbyintfN `(_FloatN x)` ¶
Function: `_FloatNx` nearbyintfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions return the same value as the `rint` functions, but do not raise the inexact exception if x is not an integer.

Function: `double` round `(double x)` ¶
Function: `float` roundf `(float x)` ¶
Function: `long double` roundl `(long double x)` ¶
Function: `_FloatN` roundfN `(_FloatN x)` ¶
Function: `_FloatNx` roundfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions are similar to `rint`, but they round halfway cases away from zero instead of to the nearest integer (or other current rounding mode).

Function: `double` roundeven `(double x)` ¶
Function: `float` roundevenf `(float x)` ¶
Function: `long double` roundevenl `(long double x)` ¶
Function: `_FloatN` roundevenfN `(_FloatN x)` ¶
Function: `_FloatNx` roundevenfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions, from TS 18661-1:2014 and TS 18661-3:2015, are similar to `round`, but they round halfway cases to even instead of away from zero.

Function: `long int` lrint `(double x)` ¶
Function: `long int` lrintf `(float x)` ¶
Function: `long int` lrintl `(long double x)` ¶
Function: `long int` lrintfN `(_FloatN x)` ¶
Function: `long int` lrintfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions are just like `rint`, but they return a `long int` instead of a floating-point number.

Function: `long long int` llrint `(double x)` ¶
Function: `long long int` llrintf `(float x)` ¶
Function: `long long int` llrintl `(long double x)` ¶
Function: `long long int` llrintfN `(_FloatN x)` ¶
Function: `long long int` llrintfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions are just like `rint`, but they return a `long long int` instead of a floating-point number.

Function: `long int` lround `(double x)` ¶
Function: `long int` lroundf `(float x)` ¶
Function: `long int` lroundl `(long double x)` ¶
Function: `long int` lroundfN `(_FloatN x)` ¶
Function: `long int` lroundfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions are just like `round`, but they return a `long int` instead of a floating-point number.

Function: `long long int` llround `(double x)` ¶
Function: `long long int` llroundf `(float x)` ¶
Function: `long long int` llroundl `(long double x)` ¶
Function: `long long int` llroundfN `(_FloatN x)` ¶
Function: `long long int` llroundfNx `(_FloatNx x)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions are just like `round`, but they return a `long long int` instead of a floating-point number.

Function: `double` fromfp `(double x, int round, unsigned int width)` ¶
Function: `float` fromfpf `(float x, int round, unsigned int width)` ¶
Function: `long double` fromfpl `(long double x, int round, unsigned int width)` ¶
Function: `_FloatN` fromfpfN `(_FloatN x, int round, unsigned int width)` ¶
Function: `_FloatNx` fromfpfNx `(_FloatNx x, int round, unsigned int width)` ¶
Function: `double` ufromfp `(double x, int round, unsigned int width)` ¶
Function: `float` ufromfpf `(float x, int round, unsigned int width)` ¶
Function: `long double` ufromfpl `(long double x, int round, unsigned int width)` ¶
Function: `_FloatN` ufromfpfN `(_FloatN x, int round, unsigned int width)` ¶
Function: `_FloatNx` ufromfpfNx `(_FloatNx x, int round, unsigned int width)` ¶
Function: `double` fromfpx `(double x, int round, unsigned int width)` ¶
Function: `float` fromfpxf `(float x, int round, unsigned int width)` ¶
Function: `long double` fromfpxl `(long double x, int round, unsigned int width)` ¶
Function: `_FloatN` fromfpxfN `(_FloatN x, int round, unsigned int width)` ¶
Function: `_FloatNx` fromfpxfNx `(_FloatNx x, int round, unsigned int width)` ¶
Function: `double` ufromfpx `(double x, int round, unsigned int width)` ¶
Function: `float` ufromfpxf `(float x, int round, unsigned int width)` ¶
Function: `long double` ufromfpxl `(long double x, int round, unsigned int width)` ¶
Function: `_FloatN` ufromfpxfN `(_FloatN x, int round, unsigned int width)` ¶
Function: `_FloatNx` ufromfpxfNx `(_FloatNx x, int round, unsigned int width)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions, from TS 18661-1:2014 and TS 18661-3:2015, convert a floating-point number to an integer according to the rounding direction round (one of the `FP_INT_*` macros). If the integer is outside the range of a two’s complement signed or unsigned (depending on the return type of the function) integer of width width bits, or if x is infinite or NaN, or if width is zero, a domain error occurs and a NaN is returned. The functions with an ‘`x`’ in their names raise the inexact exception when a domain error does not occur and the argument is not an integer; the other functions do not raise the inexact exception.

  Following ISO C23, in the GNU C Library these functions return their result in the floating-point argument type. In TS 18661-1:2014 and TS 18661-3:2015, they were originally defined to return `intmax_t` and `uintmax_t`.

Function: `double` modf `(double value, double *integer-part)` ¶
Function: `float` modff `(float value, float *integer-part)` ¶
Function: `long double` modfl `(long double value, long double *integer-part)` ¶
Function: `_FloatN` modffN `(_FloatN value, _FloatN *integer-part)` ¶
Function: `_FloatNx` modffNx `(_FloatNx value, _FloatNx *integer-part)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions break the argument value into an integer part and a fractional part (between `-1` and `1`, exclusive). Their sum equals value. Each of the parts has the same sign as value, and the integer part is always rounded toward zero.

  `modf` stores the integer part in `*integer-part`, and returns the fractional part. For example, `modf (2.5, &intpart)` returns `0.5` and stores `2.0` into `intpart`.