Report a bug
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

# std.math.rounding

This is a submodule of std.math.
It contains several functions for rounding floating point numbers.
Authors:
Walter Bright, Don Clugston, Conversion of CEPHES math library to D by Iain Buclaw and David Nadlinger
pure nothrow @nogc @trusted real `ceil`(real `x`);

pure nothrow @nogc @trusted double `ceil`(double `x`);

pure nothrow @nogc @trusted float `ceil`(float `x`);
Returns the value of x rounded upward to the next integer (toward positive infinity).
Examples:
```import std.math.traits : isNaN;

writeln(ceil(+123.456L)); // +124
writeln(ceil(-123.456L)); // -123
writeln(ceil(-1.234L)); // -1
writeln(ceil(-0.123L)); // 0
writeln(ceil(0.0L)); // 0
writeln(ceil(+0.123L)); // 1
writeln(ceil(+1.234L)); // 2
writeln(ceil(real.infinity)); // real.infinity
assert(isNaN(ceil(real.nan)));
assert(isNaN(ceil(real.init)));
```
pure nothrow @nogc @trusted real `floor`(real `x`);

pure nothrow @nogc @trusted double `floor`(double `x`);

pure nothrow @nogc @trusted float `floor`(float `x`);
Returns the value of x rounded downward to the next integer (toward negative infinity).
Examples:
```import std.math.traits : isNaN;

writeln(floor(+123.456L)); // +123
writeln(floor(-123.456L)); // -124
writeln(floor(+123.0L)); // +123
writeln(floor(-124.0L)); // -124
writeln(floor(-1.234L)); // -2
writeln(floor(-0.123L)); // -1
writeln(floor(0.0L)); // 0
writeln(floor(+0.123L)); // 0
writeln(floor(+1.234L)); // 1
writeln(floor(real.infinity)); // real.infinity
assert(isNaN(floor(real.nan)));
assert(isNaN(floor(real.init)));
```
Unqual!F `quantize`(alias rfunc = rint, F)(const F `val`, const F `unit`)
if (is(typeof(rfunc(F.init)) : F) && isFloatingPoint!F);
Round `val` to a multiple of `unit`. rfunc specifies the rounding function to use; by default this is rint, which uses the current rounding mode.
Examples:
```import std.math.operations : isClose;

assert(isClose(12345.6789L.quantize(0.01L), 12345.68L));
assert(isClose(12345.6789L.quantize!floor(0.01L), 12345.67L));
assert(isClose(12345.6789L.quantize(22.0L), 12342.0L));
```
Examples:
```import std.math.operations : isClose;
import std.math.traits : isNaN;

assert(isClose(12345.6789L.quantize(0), 12345.6789L));
assert(12345.6789L.quantize(real.infinity).isNaN);
assert(12345.6789L.quantize(real.nan).isNaN);
writeln(real.infinity.quantize(0.01L)); // real.infinity
assert(real.infinity.quantize(real.nan).isNaN);
assert(real.nan.quantize(0.01L).isNaN);
assert(real.nan.quantize(real.infinity).isNaN);
assert(real.nan.quantize(real.nan).isNaN);
```
Unqual!F `quantize`(real base, alias rfunc = rint, F, E)(const F `val`, const E `exp`)
if (is(typeof(rfunc(F.init)) : F) && isFloatingPoint!F && isIntegral!E);

Unqual!F `quantize`(real base, long exp = 1, alias rfunc = rint, F)(const F `val`)
if (is(typeof(rfunc(F.init)) : F) && isFloatingPoint!F);
Round `val` to a multiple of pow(base, `exp`). rfunc specifies the rounding function to use; by default this is rint, which uses the current rounding mode.
Examples:
```import std.math.operations : isClose;

assert(isClose(12345.6789L.quantize!10(-2), 12345.68L));
assert(isClose(12345.6789L.quantize!(10, -2), 12345.68L));
assert(isClose(12345.6789L.quantize!(10, floor)(-2), 12345.67L));
assert(isClose(12345.6789L.quantize!(10, -2, floor), 12345.67L));

assert(isClose(12345.6789L.quantize!22(1), 12342.0L));
assert(isClose(12345.6789L.quantize!22, 12342.0L));
```
pure nothrow @nogc @safe real `nearbyint`(real `x`);
Rounds x to the nearest integer value, using the current rounding mode.
Unlike the rint functions, nearbyint does not raise the FE_INEXACT exception.
Examples:
```import std.math.traits : isNaN;

writeln(nearbyint(0.4)); // 0
writeln(nearbyint(0.5)); // 0
writeln(nearbyint(0.6)); // 1
writeln(nearbyint(100.0)); // 100

assert(isNaN(nearbyint(real.nan)));
writeln(nearbyint(real.infinity)); // real.infinity
writeln(nearbyint(-real.infinity)); // -real.infinity
```
pure nothrow @nogc @safe real `rint`(real `x`);

pure nothrow @nogc @safe double `rint`(double `x`);

pure nothrow @nogc @safe float `rint`(float `x`);
Rounds x to the nearest integer value, using the current rounding mode.
If the return value is not equal to x, the FE_INEXACT exception is raised.
nearbyint performs the same operation, but does not set the FE_INEXACT exception.
Examples:
```import std.math.traits : isNaN;

version (IeeeFlagsSupport) resetIeeeFlags();
writeln(rint(0.4)); // 0
version (IeeeFlagsSupport) assert(ieeeFlags.inexact);

writeln(rint(0.5)); // 0
writeln(rint(0.6)); // 1
writeln(rint(100.0)); // 100

assert(isNaN(rint(real.nan)));
writeln(rint(real.infinity)); // real.infinity
writeln(rint(-real.infinity)); // -real.infinity
```
pure nothrow @nogc @trusted long `lrint`(real `x`);
Rounds x to the nearest integer value, using the current rounding mode.
This is generally the fastest method to convert a floating-point number to an integer. Note that the results from this function depend on the rounding mode, if the fractional part of x is exactly 0.5. If using the default rounding mode (ties round to even integers) lrint(4.5) == 4, lrint(5.5)==6.
Examples:
```writeln(lrint(4.5)); // 4
writeln(lrint(5.5)); // 6
writeln(lrint(-4.5)); // -4
writeln(lrint(-5.5)); // -6

writeln(lrint(int.max - 0.5)); // 2147483646L
writeln(lrint(int.max + 0.5)); // 2147483648L
writeln(lrint(int.min - 0.5)); // -2147483648L
writeln(lrint(int.min + 0.5)); // -2147483648L
```
nothrow @nogc @trusted auto `round`(real `x`);
Return the value of x rounded to the nearest integer. If the fractional part of x is exactly 0.5, the return value is rounded away from zero.
Returns:
A real.
Examples:
```writeln(round(4.5)); // 5
writeln(round(5.4)); // 5
writeln(round(-4.5)); // -5
writeln(round(-5.1)); // -5
```
nothrow @nogc @trusted long `lround`(real `x`);
Return the value of x rounded to the nearest integer.
If the fractional part of x is exactly 0.5, the return value is rounded away from zero.
This function is not implemented for Digital Mars C runtime.
Examples:
```version (CRuntime_DigitalMars) {}
else
{
writeln(lround(0.49)); // 0
writeln(lround(0.5)); // 1
writeln(lround(1.5)); // 2
}
```
pure nothrow @nogc @trusted real `trunc`(real `x`);
Returns the integer portion of x, dropping the fractional portion. This is also known as "chop" rounding. pure on all platforms.
Examples:
```writeln(trunc(0.01)); // 0
writeln(trunc(0.49)); // 0
writeln(trunc(0.5)); // 0
writeln(trunc(1.5)); // 1
```
pure nothrow @nogc @safe long `rndtol`(real `x`);

pure nothrow @nogc @safe long `rndtol`(double `x`);

pure nothrow @nogc @safe long `rndtol`(float `x`);
Returns x rounded to a long value using the current rounding mode. If the integer value of x is greater than long.max, the result is indeterminate.
Examples:
```writeln(rndtol(1.0)); // 1L
writeln(rndtol(1.2)); // 1L
writeln(rndtol(1.7)); // 2L
writeln(rndtol(1.0001)); // 1L
```