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

cl:functions:floor [2019/07/14 17:00] |
cl:functions:floor [2019/07/17 21: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))''. | ||