read-tiny-float

Arguments: string &key (return-zero t)

This is a convenience function which allows users to read a small-magnitude float safely (that is, without floating-point-underflow errors). If the float is smaller in magnitude than the least-positive float of the appropriate format, then zero in the appropriate form (in the appropriate format) is returned by default, or, if the return-zero keyword argument is specified as nil, the least-positive or elast negative float of the appropriate format is returned.

string must be a string whose contents read as a single floating-point number. It is an error resulting in undefined behavior if there is more in the string than the representation of a sinlge floating point number. (The function decides on whether the resulting float is positive or negative based on the presence and location of a \#- charater. Such characters after the float representation could result in an incorrect value. If string represents a float larger than the least positive float or smaller than the least negative, the read is as if done by read-from-string. No protection is provided against floating-point-overflow errors.

Example

;;  This function is intended to allow for forms like the following:
;;  (defconstant *app-single-eps* 
;;               (max least-positive-single-float 1.0e-50))
;;  LEAST-POSITIVE-SINGLE-FLOAT is 1.0e-45, so that is the desried value
;;  but reading 1.0e-50 may cause a floating-point-underflow error.
;;  That can be protected against with this form:
;; (defconstant *app-single-eps* 
;;              (max least-positive-single-float 
;;                   (read-tiny-float "1.0e-50")))
;;
;;  In the reamining examples, we assume *read-default-float-format*
;;  is single-float.
;;
(read-tiny-float "1.0") RETURNS 1.0
(read-tiny-float "1.0e-50") RETURNS 0.0
(read-tiny-float "1.0e-50" :return-zero nil) RETURNS 1.0e-45
        ;; i.e. least-positive-single-float
(read-tiny-float "-1.0e-50" :return-zero nil) RETURNS -1.0e-45
        ;; i.e. least-negative-single-float
(read-tiny-float "-1.0d-50" :return-zero nil) RETURNS -1.0d-50
(read-tiny-float "-1.0d-550" :return-zero nil) RETURNS -5.0d-324
        ;; i.e. least-negative-double-float

See Floating-point infinities and NaNs, and floating-point underflow and overflow in implementation.htm for more information and sample handler code to cath the errors.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.