info cln

4.6 Rounding functions

When a real number is to be converted to an integer, there is no “best” rounding. The desired rounding function depends on the application. The Common Lisp and ISO Lisp standards offer four rounding functions:

floor(x): This is the largest integer <=x.
ceiling(x): This is the smallest integer >=x.
truncate(x): Among the integers between 0 and x (inclusive) the one nearest to x.
round(x): The integer nearest to x. If x is exactly halfway between two integers, choose the even one.

These functions have different advantages:

floor and ceiling are translation invariant: floor(x+n) = floor(x) + n and ceiling(x+n) = ceiling(x) + n for every x and every integer n.

On the other hand, truncate and round are symmetric: truncate(-x) = -truncate(x) and round(-x) = -round(x), and furthermore round is unbiased: on the “average”, it rounds down exactly as often as it rounds up.

The functions are related like this:

ceiling(m/n) = floor((m+n-1)/n) = floor((m-1)/n)+1 for rational numbers m/n (m, n integers, n>0), and
truncate(x) = sign(x) * floor(abs(x))

Each of the classes cl_R, cl_RA, cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operations:

cl_I floor1 (const type& x): Returns floor(x).
cl_I ceiling1 (const type& x): Returns ceiling(x).
cl_I truncate1 (const type& x): Returns truncate(x).
cl_I round1 (const type& x): Returns round(x).

Each of the classes cl_R, cl_RA, cl_I, cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operations:

cl_I floor1 (const type& x, const type& y): Returns floor(x/y).
cl_I ceiling1 (const type& x, const type& y): Returns ceiling(x/y).
cl_I truncate1 (const type& x, const type& y): Returns truncate(x/y).
cl_I round1 (const type& x, const type& y): Returns round(x/y).

These functions are called ‘floor1’, … here instead of ‘floor’, …, because on some systems, system dependent include files define ‘floor’ and ‘ceiling’ as macros.

In many cases, one needs both the quotient and the remainder of a division. It is more efficient to compute both at the same time than to perform two divisions, one for quotient and the next one for the remainder. The following functions therefore return a structure containing both the quotient and the remainder. The suffix ‘2’ indicates the number of “return values”. The remainder is defined as follows:

for the computation of quotient = floor(x), remainder = x - quotient,
for the computation of quotient = floor(x,y), remainder = x - quotient*y,

and similarly for the other three operations.

Each of the classes cl_R, cl_RA, cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operations:

struct type_div_t { cl_I quotient; type remainder; };
type_div_t floor2 (const type& x)
type_div_t ceiling2 (const type& x)
type_div_t truncate2 (const type& x)
type_div_t round2 (const type& x)

Each of the classes cl_R, cl_RA, cl_I, cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operations:

struct type_div_t { cl_I quotient; type remainder; };
type_div_t floor2 (const type& x, const type& y)
type_div_t ceiling2 (const type& x, const type& y)
type_div_t truncate2 (const type& x, const type& y)
type_div_t round2 (const type& x, const type& y)

Sometimes, one wants the quotient as a floating-point number (of the same format as the argument, if the argument is a float) instead of as an integer. The prefix ‘f’ indicates this.

Each of the classes cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operations:

type ffloor (const type& x)
type fceiling (const type& x)
type ftruncate (const type& x)
type fround (const type& x)

and similarly for class cl_R, but with return type cl_F.

The class cl_R defines the following operations:

cl_F ffloor (const type& x, const type& y)
cl_F fceiling (const type& x, const type& y)
cl_F ftruncate (const type& x, const type& y)
cl_F fround (const type& x, const type& y)

These functions also exist in versions which return both the quotient and the remainder. The suffix ‘2’ indicates this.

Each of the classes cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operations:

struct type_fdiv_t { type quotient; type remainder; };
type_fdiv_t ffloor2 (const type& x)
type_fdiv_t fceiling2 (const type& x)
type_fdiv_t ftruncate2 (const type& x)
type_fdiv_t fround2 (const type& x)

and similarly for class cl_R, but with quotient type cl_F.

The class cl_R defines the following operations:

struct type_fdiv_t { cl_F quotient; cl_R remainder; };
type_fdiv_t ffloor2 (const type& x, const type& y)
type_fdiv_t fceiling2 (const type& x, const type& y)
type_fdiv_t ftruncate2 (const type& x, const type& y)
type_fdiv_t fround2 (const type& x, const type& y)

Other applications need only the remainder of a division. The remainder of ‘floor’ and ‘ffloor’ is called ‘mod’ (abbreviation of “modulo”). The remainder ‘truncate’ and ‘ftruncate’ is called ‘rem’ (abbreviation of “remainder”).

mod(x,y) = floor2(x,y).remainder = x - floor(x/y)*y
rem(x,y) = truncate2(x,y).remainder = x - truncate(x/y)*y

If x and y are both >= 0, mod(x,y) = rem(x,y) >= 0. In general, mod(x,y) has the sign of y or is zero, and rem(x,y) has the sign of x or is zero.

The classes cl_R, cl_I define the following operations:

type mod (const type& x, const type& y)
type rem (const type& x, const type& y)

This document was generated on August 27, 2013 using texi2html 5.0.