FunctionPackage: exclToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
This page is new in 8.1.

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-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. This page is new in the 8.1 release.
Created 2007.4.30.

ToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
This page is new in 8.1.