User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:floor [2019/06/15 02:00]
cl:functions:floor [2019/06/16 07:00] (current)
Line 1: Line 1:
 +====== Function FLOOR, FFLOOR, CEILING, FCEILING, TRUNCATE, FTRUNCATE, ROUND, FROUND ======
 +
 +====Syntax====
 +  * **floor** //number ''&​optional''​ divisor// → //quotient, remainder//
 +  * **ffloor** //number ''&​optional''​ divisor// → //quotient, remainder//
 +  * **ceiling** //number ''&​optional''​ divisor// → //quotient, remainder//
 +  * **fceiling** //number ''&​optional''​ divisor// → //quotient, remainder//
 +  * **truncate** //number ''&​optional''​ divisor// → //quotient, remainder//
 +  * **ftruncate** //number ''&​optional''​ divisor// → //quotient, remainder//
 +  * **round** //number ''&​optional''​ divisor// → //quotient, remainder//
 +  * **fround** //number ''&​optional''​ divisor// → //quotient, remainder//
 +
 +====Arguments and Values====
 +  * //number// - a //​[[CL:​Glossary:​real]]//​.
 +  * //divisor// - a non-zero //​[[CL:​Glossary:​real]]//​. The default is the //​[[CL:​Glossary:​integer]]//​ ''​1''​.
 +  * //​quotient//​ - for **floor**, **ceiling**,​ **truncate**,​ and **round**: an //​[[CL:​Glossary:​integer]]//;​ for **ffloor**, **fceiling**,​ **ftruncate**,​ and **fround**: a //​[[CL:​Glossary:​float]]//​.
 +  * //​remainder//​ - a //​[[CL:​Glossary:​real]]//​.
 +
 +====Description====
 +These functions divide //number// by //​divisor//,​ returning a //​quotient//​ and //​remainder//,​ such that:
 +
 +<​blockquote>​
 +//​quotient//​ * //divisor// + //​remainder//​ = //number//
 +</​blockquote>​
 +
 +The //​quotient//​ always represents a mathematical integer.
 +
 +When more than one mathematical integer might be possible (i.e. when the remainder is not zero), the kind of rounding or truncation depends on the //​[[CL:​Glossary:​operator]]//:​
 +
 +===floor, ffloor===
 +**floor** and **ffloor** produce a //​quotient//​ that has been truncated toward negative infinity; that is, the //​quotient//​ represents the largest mathematical integer that is not larger than the mathematical quotient.
 +
 +===ceiling, fceiling===
 +**ceiling** and **fceiling** produce a //​quotient//​ that has been truncated toward positive infinity; that is, the //​quotient//​ represents the smallest mathematical integer that is not smaller than the mathematical result.
 +
 +===truncate,​ ftruncate===
 +**truncate** and **ftruncate** produce a //​quotient//​ that has been truncated towards zero; that is, the //​quotient//​ represents the mathematical integer of the same sign as the mathematical quotient, and that has the greatest integral magnitude not greater than that of the mathematical quotient.
 +
 +===round, fround===
 +**round** and **fround** produce a //​quotient//​ that has been rounded to the nearest mathematical integer; if the mathematical quotient is exactly halfway between two integers, (that is, it has the form ''​integer + 1/​2''​),​ then the //​quotient//​ has been rounded to the even (divisible by two) integer.
 +
 +----
 +
 +All of these functions perform type conversion operations on //​numbers//​.
 +
 +The //​remainder//​ is an //​[[CL:​Glossary:​integer]]//​ if both //x// and //y// are //​[[CL:​Glossary:​integers]]//,​ is a //​[[CL:​Glossary:​rational]]//​ if both //x// and //y// are //​[[CL:​Glossary:​rationals]]//,​ and is a //​[[CL:​Glossary:​float]]//​ if either //x// or //y// is a //​[[CL:​Glossary:​float]]//​.
 +
 +**ffloor**, **fceiling**,​ **ftruncate**,​ and **fround** handle arguments of different //​[[CL:​Glossary:​type|types]]//​ in the following way: If //number// is a //​[[CL:​Glossary:​float]]//,​ and //divisor// is not a //​[[CL:​Glossary:​float]]//​ of longer format, then the first result is a //​[[CL:​Glossary:​float]]//​ of the same //​[[CL:​Glossary:​type]]//​ as //number//. Otherwise, the first result is of the //​[[CL:​Glossary:​type]]//​ determined by //​[[CL:​Glossary:​contagion]]//​ rules; see section {\secref\NumericContagionRules}.
 +
 +====Examples====
 +<​blockquote>​
 +(floor 3/2) <r>1
 +1/2 </r>
 +(ceiling 3 2) <r>2
 +-1 </r>
 +(ffloor 3 2) <​r>​1.0
 +1 </r>
 +(ffloor -4.7) <​r>​-5.0
 +0.3 </r>
 +(ffloor 3.5d0) <​r>​3.0d0
 +0.5d0 </r>
 +(fceiling 3/2) <​r>​2.0
 +-1/2 </r>
 +(truncate 1) <r>1
 +0 </r>
 +(truncate .5) <r>0
 +0.5 </r>
 +(round .5) <r>0
 +0.5 </r>
 +(ftruncate -7 2) <​r>​-3.0
 +-1 </r>
 +(fround -7 2) <​r>​-4.0
 +1 </r>
 +([[CL:​Macros:​dolist]] (n '(2.6 2.5 2.4 0.7 0.3 -0.3 -0.7 -2.4 -2.5 -2.6)) ​
 +  ([[CL:​Functions:​format]] [[CL:​Constant Variables:​t]] "​~&​~4,​1@F ~2,' D ~2,' D ~2,' D ~2,' D" ​
 +          n (floor n) (ceiling n) (truncate n) (round n)))
 +<​o>​+2.6 ​ 2  3  2  3
 ++2.5  2  3  2  2
 ++2.4  2  3  2  2
 ++0.7  0  1  0  1
 ++0.3  0  1  0  0
 +-0.3 -1  0  0  0
 +-0.7 -1  0  0 -1
 +-2.4 -3 -2 -2 -2
 +-2.5 -3 -2 -2 -2
 +-2.6 -3 -2 -2 -3 </o>
 +<​r>​NIL </r>
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +None.
 +
 +====Notes====
 +When only //number// is given, the two results are exact; the mathematical sum of the two results is always equal to the mathematical value of //number//.
 +
 +''​(function //number// //​divisor//​)''​ and ''​(function (/ //number// //​divisor//​))''​ (where ''​function''​ is any of one of **floor**, **ceiling**,​ **ffloor**, **fceiling**,​ **truncate**,​ **round**, **ftruncate**,​ and **fround**) return the same first value, but they return different remainders as the second value. For example:
 +
 +<​blockquote>​
 +(floor 5 2) <r>2
 +1</r>
 +(floor (/ 5 2)) <r>2
 +1/​2</​r>​
 +</​blockquote>​
 +
 +If an effect is desired that is similar to **round**, but that always rounds up or down (rather than toward the nearest even integer) if the mathematical quotient is exactly halfway between two integers, the programmer should consider a construction such as ''​(floor ([[CL:​Functions:​math-add|+]] x 1/​2))''​ or ''​(ceiling ([[CL:​Functions:​math-subtract|-]] x 1/​2))''​.