floor, floorf, floorl, floord32, floord64, floord128, nearest, trunc, itrunc, and uitrunc Subroutines

Purpose

The floor subroutine, floorf subroutine, floorl subroutine, nearest subroutine, trunc subroutine, floord32 subroutine, floord64 subroutine, and floord128 subroutine, round floating-point numbers to floating-point integer values.

The itrunc subroutine and uitrunc subroutine round floating-point numbers to signed and unsigned integers, respectively.

Libraries

IEEE Math Library (libm.a) or System V Math Library (libmsaa.a) Standard C Library (libc.a) (separate syntax follows)

Syntax

#include <math.h>
double floor ( x)
double x;
float floorf (x)
float x;
long double floorl (x)
long double x;
_Decimal32 floord32(x)
_Decimal32 x;

_Decimal64 floord64(x)
_Decimal64 x;

_Decimal128 floord128(x)
_Decimal128 x;
double nearest (x)
double x;
double trunc (x)
double x;

Standard C Library (libc.a)

#include <stdlib.h>
#include <limits.h>
int itrunc (x)
double x;
unsigned int uitrunc (x)
double x;

Description

The floor, floorf, floorl, floord32, floord64, and floord128 subroutines return the largest floating-point integer value that is not greater than the x parameter.

An application wishing to check for error situations should set errno to zero and call feclearexcept(FE_ALL_EXCEPT) before calling these subroutines. Upon return, if errno is nonzero or fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW) is nonzero, an error has occurred.

The nearest subroutine returns the nearest floating-point integer value to the x parameter. If x lies exactly halfway between the two nearest floating-point integer values, an even floating-point integer is returned.

The trunc subroutine returns the nearest floating-point integer value to the x parameter in the direction of 0. This is equivalent to truncating off the fraction bits of the x parameter.

Note: The default floating-point rounding mode is round to nearest. All C main programs begin with the rounding mode set to round to nearest.

The itrunc subroutine returns the nearest signed integer to the x parameter in the direction of 0. This is equivalent to truncating the fraction bits from the x parameter and then converting x to a signed integer.

The uitrunc subroutine returns the nearest unsigned integer to the x parameter in the direction of 0. This action is equivalent to truncating off the fraction bits of the x parameter and then converting x to an unsigned integer.

Note: Compile any routine that uses subroutines from the libm.a library with the -lm flag. To compile the floor.c file, for example, enter:
cc floor.c -lm

The itrunc, uitrunc, trunc, and nearest subroutines are not part of the ANSI C Library.

Parameters

Item Description
x Specifies a double-precision floating-point value. For the floorl subroutine, specifies a long double-precision floating-point value.
Item Description
y Specifies a double-precision floating-point value. For the floorl subroutine, specifies some long double-precision floating-point value.

Return Values

Upon successful completion, the floor, floorf, floorl, floord32, floord64, and floord128 subroutines return the largest integral value that is not greater than x, expressed as a double, float, long double, _Decimal32, _Decimal64, or _Decimal128, as appropriate for the return type of the function.

If x is NaN, a NaN is returned.

If x is ±0 or ±Inf, x is returned.

If the correct value would cause overflow, a range error occurs and thefloor, floorf, floorl, floord32, floord64, and floord128 subroutines return the value of the macro -HUGE_VAL, -HUGE_VALF, -HUGE_VALL, -HUGE_VAL_D32, -HUGE_VAL_D64, and -HUGE_VAL_D128, respectively.

Error Codes

The itrunc and uitrunc subroutines return the INT_MAX value if x is greater than or equal to the INT_MAX value and the INT_MIN value if x is equal to or less than the INT_MIN value. The itrunc subroutine returns the INT_MIN value if x is a Quiet NaN(not-a-number) or Silent NaN. The uitrunc subroutine returns 0 if x is a Quiet NaN or Silent NaN. (The INT_MAX and INT_MIN values are defined in the limits.h file.) The uitrunc subroutine INT_MAX if x is greater than INT_MAX and 0 if x is less than or equal 0.0

Files

Item Description
float.h Contains the ANSI C FLT_ROUNDS macro.