Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
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