User Tools


Differences

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

Link to this comparison view

cl:functions:decode-float [2019/07/14 17:00]
cl:functions:decode-float [2019/07/17 21:00] (current)
Line 1: Line 1:
 +====== Function DECODE-FLOAT,​ SCALE-FLOAT,​ FLOAT-RADIX,​ FLOAT-SIGN, FLOAT-DIGITS,​ FLOAT-PRECISION,​ INTEGER-DECODE-FLOAT ======
 +
 +====Syntax====
 +  * **decode-float** //float// → //​significand,​ exponent, sign//
 +  * **scale-float** //float integer// → //​scaled-float//​
 +  * **float-radix** //float// → //​float-radix//​
 +  * **float-sign** //float-1** ''&​optional''​ float-2// → //​signed-float//​
 +  * **float-digits** //float// → //digits1//
 +  * **float-precision** //float// → //digits2//
 +  * **integer-decode-float** //float// → //​significand,​ exponent, integer-sign//​
 +
 +====Arguments and Values====
 +  * //digits1// - a non-negative //​[[CL:​Glossary:​integer]]//​.
 +  * //digits2// - a non-negative //​[[CL:​Glossary:​integer]]//​.
 +  * //​exponent//​ - an //​[[CL:​Glossary:​integer]]//​.
 +  * //float// - a //​[[CL:​Glossary:​float]]//​.
 +  * //float-1// - a //​[[CL:​Glossary:​float]]//​.
 +  * //float-2// - a //​[[CL:​Glossary:​float]]//​.
 +  * //​float-radix//​ - an //​[[CL:​Glossary:​integer]]//​.
 +  * //integer// - a non-negative //​[[CL:​Glossary:​integer]]//​.
 +  * //​integer-sign//​ - the //​[[CL:​Glossary:​integer]]//​ ''​-1'',​ or the //​[[CL:​Glossary:​integer]]//​ ''​1''​.
 +  * //​scaled-float//​ - a //​[[CL:​Glossary:​float]]//​.
 +  * //sign// - A //​[[CL:​Glossary:​float]]//​ of the same //​[[CL:​Glossary:​type]]//​ as //float// but numerically equal to ''​1.0''​ or ''​-1.0''​.
 +  * //​signed-float//​ - a //​[[CL:​Glossary:​float]]//​.
 +  * //​significand//​ - a //​[[CL:​Glossary:​float]]//​.
 +
 +====Description====
 +
 +**decode-float** computes three values that characterize //float//. The first value is of the same //​[[CL:​Glossary:​type]]//​ as //float// and represents the significand. The second value represents the exponent to which the radix (notated in this description by ''​b''​) must be raised to obtain the value that, when multiplied with the first result, produces the absolute value of //float//. If //float// is zero, any //​[[CL:​Glossary:​integer]]//​ value may be returned, provided that the identity shown for **scale-float** holds. The third value is of the same //​[[CL:​Glossary:​type]]//​ as //float// and is 1.0 if //float// is greater than or equal to zero or -1.0 otherwise.
 +
 +**decode-float** divides //float// by an integral power of ''​b''​ so as to bring its value between ''​1/​b''​ (inclusive) and ''​1''​ (exclusive),​ and returns the quotient as the first value. If //float// is zero, however, the result equals the absolute value of //float// (that is, if there is a negative zero, its significand is considered to be a positive zero).
 +
 +**scale-float** returns ''​(* //float// (expt (float ''​b''​ //float//) //​integer//​))'',​ where ''​b''​ is the radix of the floating-point representation. //float// is not necessarily between ''​1/​b''​ and ''​1''​.
 +
 +**float-radix** returns the radix of //float//.
 +
 +**float-sign** returns a number ''​z''​ such that ''​z''​ and //float-1// have the same sign and also such that ''​z''​ and //float-2// have the same absolute value. If //float-2// is not supplied, its value is ''​(float 1 //​float-1//​)''​.
 +
 +If an implementation has distinct representations for negative zero and positive zero, then ''​(float-sign -0.0)''​ → ''​-1.0''​.
 +
 +**float-digits** returns the number of radix ''​b''​ digits used in the representation of //float// (including any implicit digits, such as a "​hidden bit").
 +
 +**float-precision** returns the number of significant radix ''​b''​ digits present in //float//; if //float// is a //​[[CL:​Glossary:​float]]//​ zero, then the result is an //​[[CL:​Glossary:​integer]]//​ zero.
 +
 +For //​[[CL:​Glossary:​normalized]]//​ //​[[CL:​Glossary:​floats]]//,​ the results of **float-digits** and **float-precision** are the same, but the precision is less than the number of representation digits for a //​[[CL:​Glossary:​denormalized]]//​ or zero number.
 +
 +**integer-decode-float** computes three values that characterize //float// - the significand scaled so as to be an //​[[CL:​Glossary:​integer]]//,​ and the same last two values that are returned by **decode-float**. If //float// is zero, **[[integer-decode-float** returns zero as the first value. The second value bears the same relationship to the first value as for **decode-float**:​
 +
 +<​blockquote>​
 +([[CL:​Macros:​multiple-value-bind]] (signif expon sign) 
 +    (integer-decode-float f) 
 +  (scale-float ([[CL:​Functions:​float]] signif f) expon)) ≡ ([[CL:​Functions:​abs]] f)
 +</​blockquote>​
 +
 +====Examples====
 +Note that since the purpose of this functionality is to expose details of the //​[[CL:​Glossary:​implementation]]//,​ all of these examples are necessarily very //​[[CL:​Glossary:​implementation-dependent]]//​. Results may vary widely. Values shown here are chosen consistently from one particular //​[[CL:​Glossary:​implementation]]//​.
 +
 +<​blockquote>​
 +(decode-float .5) <​r>​0.5
 +0
 +1.0 </r>
 +(decode-float 1.0) <​r>​0.5
 +1
 +1.0 </r>
 +(scale-float 1.0 1) <​r>​2.0 </r>
 +(scale-float 10.01 -2) <​r>​2.5025 </r>
 +(scale-float 23.0 0) <​r>​23.0 </r>
 +(float-radix 1.0) <r>2 </r>
 +(float-sign 5.0) <​r>​1.0 </r>
 +(float-sign -5.0) <​r>​-1.0 </r>
 +(float-sign 0.0) <​r>​1.0 </r>
 +(float-sign 1.0 0.0) <​r>​0.0 </r>
 +(float-sign 1.0 -10.0) <​r>​10.0 </r>
 +(float-sign -1.0 10.0) <​r>​-10.0 </r>
 +(float-digits 1.0) <r>24 </r>
 +(float-precision 1.0) <r>24 </r>
 +(float-precision least-positive-single-float) <r>1 </r>
 +(integer-decode-float 1.0) <​r>​8388608
 +-23
 +1 </r>
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +The implementation'​s representation for //​[[CL:​Glossary:​floats]]//​.
 +
 +====Exceptional Situations====
 +The functions **decode-float**,​ **float-radix**,​ **float-digits**,​ **float-precision**,​ and **integer-decode-float** should signal an error if their only argument is not a //​[[CL:​Glossary:​float]]//​.
 +
 +The //​[[CL:​Glossary:​function]]//​ **scale-float** should signal an error if its first argument is not a //​[[CL:​Glossary:​float]]//​ or if its second argument is not an //​[[CL:​Glossary:​integer]]//​.
 +
 +The //​[[CL:​Glossary:​function]]//​ **float-sign** should signal an error if its first argument is not a //​[[CL:​Glossary:​float]]//​ or if its second argument is supplied but is not a //​[[CL:​Glossary:​float]]//​.
 +
 +====See Also====
 +None.
 +
 +====Notes====
 +The product of the first result of **decode-float** or **integer-decode-float**,​ of the radix raised to the power of the second result, and of the third result is exactly equal to the value of //float//.
 +
 +<​blockquote>​
 +([[CL:​Macros:​multiple-value-bind]] (signif expon sign) 
 +    (decode-float f) 
 +  (scale-float signif expon)) ​
 +  ≡ ([[CL:​Functions:​abs]] f)
 +
 +([[CL:​Macros:​multiple-value-bind]] (signif expon sign) 
 +    (decode-float f) 
 +  ([[CL:​Functions:​math-multiply|*]] (scale-float signif expon) sign)) ​
 +  ≡ f
 +</​blockquote>​
 +